libxkbcommon 1.7.0
Introduction to XKB

XKB stands for “X Keyboard Extension”. It may refer to either:

XKB the protocol

A protocol for the X Windows System, that extends the core protocol.

xkbcommon’s API is somehow derived from this API, but has been substantially reworked to function as a library instead of a protocol, and exposes fewer internal details to clients.

xkbcommon does not depend on a particular windows system; for instance it is used by the Wayland protocol.

xkbcommon provides the xkbcommon-x11 module to interface a client with an X server using the XKB protocol. Relevant links:

XKB the keyboard keymap configuration

In order to use the protocol, one must first load a complete keymap. The keymap usually comes from the OS layout database, which is commonly xkeyboard-config. Since keymaps may have definitions in common, the database actually stores their basic components separately to allow maximum composability and coherence. A recipe to compose a keymap from its components is called a keymap configuration.

In XKB, there are several ways to define a keymap configuration. They all aim to produce a complete keymap. The following diagram presents an overview. Then they are presented hereinafter, ordered from end user to low-level implementation.

XKB keymap configurations
RMLVO: Rules, Model, Layout, Variant, Options

This is the configuration the end user usually faces in the UI. The idea is to expose high level concepts such as keyboard model and keyboard layout to the user, then to map them to the corresponding set of low-level configuration files (see KcCGST).

Note
The RMLVO configurations actually available to the end user is managed by the xkbregistry. It uses an XML file, the registry, which exposes and documents the set of RMLVO settings in the layout database.

The RMLVO configuration consists of the following components:

Rules

The rules define the mapping from high to low level components. The rules component is the file containing the set of rules to use. It is usually implicit and set by the system.

See the rules file format for further details.

Model

The name of the model of the keyboard hardware in use. It may depend on:

  • The location and language of the user, because languages may require specific keys for their input methods, such as the muhenkan key on Japanese keyboard and the Hanja key for Korean keyboards. The keyboard are usually classified by the standard it is based on, e.g. ANSI, ISO, JIS, ABNT.
  • The keyboard vendor: keyboard may have a set of keys that are not standard, or may be specific to an OS.
Layout
The identifier of the general layout to use. It usually refers to a country or a language.
Variant
Any minor variants on the general layout. It may be national variants
Options

Set of extra options to customize the standard layouts.

Examples: switch modifiers keys, location of the compose key, etc.

KcCGST: Keycodes, Compat, Geometry, Symbols, Types

This is the low-level configuration of XKB and how the files are actually organized in the layout database. It is not really intuitive or straight-forward for the uninitiated.

Note
xkbcommon does not offer an API for KcCGST: it is considered an implementation detail. Instead, RMLVO is the preferred way for the user to configure XKB.

The KcCGST configuration consists of the following components:

Key codes
A translation of the raw key codes from the keyboard into symbolic names.
Compatibility
A specification of what internal actions modifiers and various special-purpose keys produce.
Geometry

A description of the physical layout of a keyboard.

Attention
This legacy feature is not supported by xkbcommon.
Key symbols
A translation of symbolic key codes into actual key symbols (keysyms).
Key types
Types describe how a pressed key is affected by active modifiers such as Shift, Control, Alt, etc.
Complete Keymap

A complete keymap is a self-contained text file with all the KcCGST components needed to configure a keyboard. This is the result of the resolution of the RMLVO and KcCGST configurations. This is also the format used by X11 and Wayland when prompted to serialize the keymap in use.

Note
This is a low-level configuration. RMLVO is the preferred way for the end user to configure XKB, but some power users may need it for avanced configurations.

See the XKB text format for further details.

Note
Layout making use of dead keys require a Compose file. The same applies when if using a Compose key.

XKB the text format

A text format to define keyboard keymaps. XKB 1.0 is the specification implemented in current X servers. The format supported by xkbcommon is very close to XKB 1.0, with some removals and additions. See the compatibility page for further details.

The format supported by xkbcommon is documented at the page “The XKB keymap text format, V1”.

The documentation of the original XKB 1.0 format is much more scarce than for the protocol. Some priceless resources are:

Generated by doxygen 1.10.0