libxkbcommon
1.10.0
Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state
|
❌️ No support
This page presents the differences between the XKB 1.0 specification implemented in current X servers and its implementation in libxkbcommon.
xkbcommon has removed support for some parts of the specification which introduced unnecessary complications. Many of these removals were in fact not implemented, or half-implemented at best, as well as being totally unused in the standard keyboard layout database, xkeyboard-config.
On the other hand, xkbcommon has notable additions that lift hard-coded limitation of the X11 Protocol.
Feature
X11
xkbcommon (v1 format)
xkbcommon (v2 format) </thead> <tbody>
Wayland support
<details>
Wayland support requires the XWayland compatibility layer. </details>
<details>
✅ Full support
libxkbcommon is the reference implementation of the keyboard keymap handling (parsing/serializing, state) for Wayland. </details>
User configuration
<details>
❌️ No support
Layout database path is hard-coded in xserver.
xkbcomp
enable path configuration, but setxkbmap
support is incomplete. </details>
<details>
✅ Full support
Multiple layout database path can be used simultaneously, enabling user-space configuration.
See User-configuration for further information. </details>
Extended keycodes
<details>
❌️ No support
Limited to 8-bit keycodes. </details>
<details>
✅ Full support
Support all Linux keycodes using 32-bit keycodes. </details>
Extended key names
<details>
❌️ No support
Limited to 4-character names. </details>
<details>
✅ Full support
Support any key names of any length. </details>
Extended number of layouts
<details>
❌️ No support
Limited to 4 layouts. </details>
<details>
❌️ No support
Limited to 4 layouts. </details>
<details>
✅ Full support (since 1.11)
Enable up to 32 layouts when using XKB_KEYMAP_FORMAT_TEXT_V2
. </details>
Unified modifiers
<details>
❌️ No support
Clear separation between real (i.e. core) and virtual modifiers. </details>
<details>
✅ Full support
Real and virtual modifiers have been collapsed into the same namespace, with a “significant” flag that largely parallels the core/virtual split.
Real modifiers are predefined modifiers with fixed encoding and considered merely as a X11 compatibility feature. </details>
Extended modifiers
<details>
❌️ No support
Limited to up to 8 independent modifiers. </details>
<details>
✅ Full support
Enable up to 32 independent modifiers. </details>
Canonical virtual modifiers
<details>
❌️ No support
Virtual modifiers can only mapped to real modifiers (8 bits). </details>
<details>
⚠️ Partial support
Only if using explicit mapping: e.g. virtual_modifiers M = 0x100;
if M
has the modifier index 8. </details>
<details>
✅ Full support
Virtual modifiers that are not mapped either explicitly (using e.g. virtual_modifiers M = …
) or implicitly (using modifier_map
and virtualModifier
) automatically use to their canonical mapping. </details>
Multiple keysyms per level
<details>
❌️ Parsing only
Ignored: fallback to NoSymbol
. </details>
<details>
✅ Full support
❌️ No support
Parse error. </details>
<details>
⚠️ Parsing & handling, no serialization
Currently limited to 1 action for each action type “group” and “modifier”.
VoidAction()
for compatibility with X11. </details> <details>
⚠️ Partial support
Currently limited to 1 action for each action type “group” and “modifier”.
✅ Full support
<details>
⚠️ Parsing only
Rational:
Radio groups
✅ Full support
<details>
❌️ No support
Unused in xkeyboard-config layouts. </details>
Overlays
✅ Full support
<details>
❌️ No support
Unused in xkeyboard-config layouts. </details>
✅ Full support
<details>
❌️ No support
Used to implement radio groups and overlays, and to deal with things like keys that physically lock;
Unused in xkeyboard-config layouts. </details>
✅ Full support
<details>
⚠️ Partial support
E.g. LED-controls-key behavior (X11’s IM_LEDDrivesKB
flag enabled) is not supported.
The only supported LED behavior is key-controls-LED.
Unused in xkeyboard-config layouts. </details> </tbody>
Type
Action
X11
xkbcommon (v1 format)
xkbcommon (v2 format) </thead> <tbody>
Ineffectual
NoAction()
✅ Full support
✅ Full support
VoidAction()
❌️ No support
⚠️ Parsing only (since 1.10)
✅ Full support (since 1.11)
Modifiers
SetModifiers()
<details>
⚠️ Partial support
unlockOnPress
parameter is not supported. </details> <details>
⚠️ Partial support
unlockOnPress
parameter is not supported. Use XKB_KEYMAP_FORMAT_TEXT_V2
. </details> <details>
✅ Full support
unlockOnPress
parameter (since 1.11). See its documentation for further details. </details> LatchModifiers()
<details>
⚠️ Partial support
latchOnPress
parameter is not supported.unLockOnPress
parameter is not supported. </details> <details>
⚠️ Partial support
latchOnPress
parameter is not supported. Use XKB_KEYMAP_FORMAT_TEXT_V2
.unLockOnPress
parameter is not supported. Use XKB_KEYMAP_FORMAT_TEXT_V2
. </details> <details>
✅ Full support
latchOnPress
parameter (since 1.11). See its documentation for further details.unLockOnPress
parameter (since 1.11). See its documentation for further details. </details> LockModifiers()
<details>
⚠️ Partial support
unlockOnPress
parameter is not supported. </details> <details>
⚠️ Partial support
unlockOnPress
parameter is not supported. Use XKB_KEYMAP_FORMAT_TEXT_V2
. </details> <details>
✅ Full support
unlockOnPress
parameter (since 1.11). See its documentation for further details. </details> Groups
SetGroup()
✅ Full support
✅ Full support
LatchGroup()
✅ Full support
✅ Full support
LockGroup()
<details>
⚠️ Partial support
lockOnRelease
parameter is not supported. Use XKB_KEYMAP_FORMAT_TEXT_V2
. </details> <details>
⚠️ Partial support
lockOnRelease
parameter is not supported. Use XKB_KEYMAP_FORMAT_TEXT_V2
. </details> <details>
✅ Full support
lockOnRelease
(since 1.11). See its documentation for further details. </details> Legacy action
MovePointer()
✅ Full support
⚠️ Parsing and serializing only, no API support
PointerButton()
✅ Full support
⚠️ Parsing and serializing only, no API support
LockPointerButton()
✅ Full support
⚠️ Parsing and serializing only, no API support
SetPointerDefault()
✅ Full support
⚠️ Parsing and serializing only, no API support
SetControls()
✅ Full support
⚠️ Parsing and serializing only, no API support
LockControls()
✅ Full support
⚠️ Parsing and serializing only, no API support
TerminateServer()
✅ Full support
⚠️ Parsing and serializing only, no API support
SwitchScreen()
✅ Full support
⚠️ Parsing and serializing only, no API support
Private()
✅ Full support
⚠️ Parsing and serializing only, no API support
Unsupported legacy action
RedirectKey()
✅ Full support
❌️ Parsing only
ISOLock()
✅ Full support
❌️ Parsing only
DeviceButton()
✅ Full support
❌️ Parsing only
LockDeviceButton()
✅ Full support
❌️ Parsing only
DeviceValuator()
✅ Full support
❌️ Parsing only
MessageAction()
✅ Full support
❌️ Parsing only </tbody>
Feature
X11 (xkbcomp)
xkbcommon (v1 format)
xkbcommon (v2 format) </thead> <tbody>
Optional keymap components
❌️ All components are mandatory
<details>
✅ Full support (since 1.9)
Keymap components are no longer mandatory, e.g. a keymap without a xkb_types
section is legal. </details>
Strong type check
❌️ Weak type check
<details>
⚠️ Stronger type check (WIP)
Floating-point numbers cannot be used where an integer is expected. </details>
replace
merge mode in include statements
❌️ No support
<details>
✅ Full support (since 1.9)
Supported using the prefix ^
, in addition to the standard merge |
and override +
modes. </details>
Keysym as strings
❌️ No support
<details>
✅ Full support (since 1.9)
Keysyms can be written as their corresponding string, e.g. udiaeresis
can be written "ü"
. A string with multiple Unicode code points denotes a list of the corresponding keysyms. An empty string denotes the keysym NoSymbol
. </details>
Unicode escape sequence
❌️ No support
<details>
✅ Full support (since 1.9)
\u{NNNN}
.
See string literal for further information. </details>
Extended GroupN
constants
<details>
❌️ No support
Only Group1
..Group8
are supported, although the resulting group must be in the range 1..4. </details>
<details>
❌️ No support
Only Group1
..Group4
are supported.
Use XKB_KEYMAP_FORMAT_TEXT_V2
in order to support further groups. </details>
<details>
✅ Full support (since 1.11)
The pattern Group<INDEX>
can be used for any valid group index <INDEX>
. </details>
Extended LevelN
constants
<details>
❌️ No support
Only Level1
..Level8
are supported. </details>
<details>
✅ Full support (since 1.11)
Since 1.11, the pattern Level<INDEX>
can be used for any valid level index <INDEX>
.
Before 1.11, only Level1
..Level8
were supported. </details>
Extended include
❌️ No support
<details>
✅ Full support (since 1.11)
Enable absolute paths and *%
-expansion*.
See keymap-include-percent-expansion for further details. </details>
Include predefined maps
✅ Full support
<details>
❌️ No support
The modern approach is to use RMLVO. </details>
Exponent syntax for floating-point numbers
✅ Full support
<details>
❌️ No support
⚠️ Parsing, fallback to default merge mode
alternate
was used in xkb_keycodes
type sections and meant that if a new keycode name conflicts with an old one, consider it as a keycode alias. </details>
Multiple group definition in symbols section
✅ Full support
<details>
⚠️ Supported, except in the RMLVO API
Since 1.8, only 1 group per symbol section is supported in the RMLVO API, to avoid unintuitive results.
Multiple groups per symbol section is supported when parsing a KcCGST keymap. </details> </tbody>
Feature
X11
xkbcommon (v1 format)
xkbcommon (v2 format) </thead> <tbody>
Full Unicode support
❌️ Incomplete
<details>
✅ Full support
Full support of simple case mappings for xkb_keysym_to_lower()
and xkb_keysym_to_upper()
. </details>
✅ Full support
<details>
⚠️ Partial support (since 1.10)
xkb_component_names::xkb_components_names_from_rules()
for debugging purposes. </details> XKM file format
✅ Full support
<details>
❌️ No support
Obsolete legacy file format tied to X11 ecosystem. </details>
</tbody>
Feature
X11
xkbcommon (v1 format)
xkbcommon (v2 format) </thead> <tbody>
! include
statement
❌️ No support
<details>
✅ Full support
See rules include statement for further details. </details>
replace
merge mode
❌️ No support
<details>
✅ Full support (since 1.9)
Support the merge mode replace via the prefix ^
, in addition to the standard merge |
and override +
modes. </details>
Extended layout indices
❌️ No support
<details>
✅ Full support (since 1.8)
layout[single]
is the same as without explicit index: layout
.layout
and layout[1]
.layout[2]
.. layout[MAX_LAYOUT]
, where MAX_LAYOUT
is currently 4.:all
qualifier: it applies the qualified item to all layouts.See extended layout indices for further details. </details>
:all
qualifier
❌️ No support
<details>
✅ Full support (since 1.8)
the :all
qualifier: it applies the qualified item to all layouts.
See :all qualifier for further details. </details>
Extended wild cards
❌️ No support
<details>
✅ Full support (since 1.9)
<none>
matches empty value;<some>
matches non-empty value in every context.<any>
matches optionally empty value in every context, contrary to the legacy *
wild card which does not match empty values for layout and variant.See rules wildcards for further information. </details>
</tbody>
Feature
X11
xkbcommon </thead> <tbody>
XML format
❌️ No support
<details>
✅ Full support
rationale </details>
</tbody>
Relative to the standard implementation in libX11 (described in the Compose(5) man-page):
Feature
X11 (libX11
)
xkbcommon </thead> <tbody>
[!] MODIFIER
syntax
✅ Full support
<details>
⚠️ Parsing only
Syntax: [([!] ([~] MODIFIER)...) | None] <keysym>
If the modifier list is preceded by !
it must match exactly. MODIFIER may be one of Ctrl
, Lock
, Caps
, Shift
, Alt
or Meta
. Each modifier may be preceded by a ~
character to indicate that the modifier must not be present. If None
is specified, no modifier may be present.
⚠️ Parsed, but key events are ignored
Modifiers should not be used in Compose sequences. Use keymap’s features or a keysym with more appropriate semantics. </details>
Interactions with Braille keysyms
✅ Full support
<details>
❌️ No support
feature description, removal rationale </details>
</tbody>