|
libxkbcommon 1.11.0
Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state
|
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) |
|---|
Wayland support
Wayland support requires the XWayland compatibility layer.
libxkbcommon is the reference implementation of the keyboard keymap handling (parsing/serializing, state) for Wayland.
User configuration
Layout database path is hard-coded in xserver.
xkbcomp enable path configuration, but setxkbmap support is incomplete.
Multiple layout database path can be used simultaneously, enabling user-space configuration.
See User-configuration for further information.
Extended keycodes
Limited to 8-bit keycodes.
Support all Linux keycodes using 32-bit keycodes.
Extended key names
Limited to 4-character names.
Support any key names of any length.
Extended number of layouts
Limited to 4 layouts.
Limited to 4 layouts.
Enable up to 32 layouts when using XKB_KEYMAP_FORMAT_TEXT_V2.
Unified modifiers
Clear separation between real (i.e. core) and virtual modifiers.
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.
Extended modifiers
Limited to up to 8 independent modifiers.
Enable up to 32 independent modifiers.
Canonical virtual modifiers
Virtual modifiers can only mapped to real modifiers (8 bits).
Only if using explicit mapping: e.g. virtual_modifiers M = 0x100; if M has the modifier index 8.
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.
Multiple keysyms per level
Ignored: fallback to NoSymbol.
Multiple actions per level
Parse error.
Currently limited to 1 action for each action type “group” and “modifier”.
Currently limited to 1 action for each action type “group” and “modifier”.
✅ Full support
Rational:
Radio groups
✅ Full support
Unused in xkeyboard-config layouts.
Overlays
✅ Full support
Unused in xkeyboard-config layouts.
✅ Full support
Used to implement radio groups and overlays, and to deal with things like keys that physically lock;
Unused in xkeyboard-config layouts.
✅ Full 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.
| Type | Action | X11 | xkbcommon (v1 format) | xkbcommon (v2 format) |
|---|
Ineffectual
NoAction()
✅ Full support
✅ Full support
VoidAction()
❌️ No support
⚠️ Parsing only (since 1.10)
✅ Full support (since 1.11)
Modifiers
SetModifiers()
LatchModifiers()
LockModifiers()
Groups
SetGroup()
✅ Full support
✅ Full support
LatchGroup()
✅ Full support
✅ Full support
LockGroup()
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
| Feature | X11 (xkbcomp) | xkbcommon (v1 format) | xkbcommon (v2 format) |
|---|
Optional keymap components
❌️ All components are mandatory
Keymap components are no longer mandatory, e.g. a keymap without a xkb_types section is legal.
Strong type check
❌️ Weak type check
Floating-point numbers cannot be used where an integer is expected.
replace merge mode in include statements
❌️ No support
Supported using the prefix ^, in addition to the standard merge | and override + modes.
Keysym as strings
❌️ No support
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.
Unicode escape sequence
❌️ No support
Extended GroupN constants
Only Group1..Group8 are supported, although the resulting group must be in the range 1..4.
Only Group1..Group4 are supported.
Use XKB_KEYMAP_FORMAT_TEXT_V2 in order to support further groups.
The pattern Group<INDEX> can be used for any valid group index <INDEX>.
Extended LevelN constants
Only Level1..Level8 are supported.
Since 1.11, the pattern Level<INDEX> can be used for any valid level index <INDEX>.
Before 1.11, only Level1..Level8 were supported.
Extended include
❌️ No support
Enable absolute paths and %-expansion.
See keymap-include-percent-expansion for further details.
Include predefined maps
✅ Full support
The modern approach is to use RMLVO.
Exponent syntax for floating-point numbers
✅ Full support
alternate merge mode
✅ Full support
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.
Multiple group definition in symbols section
✅ Full support
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.
| Feature | X11 | xkbcommon (v1 format) | xkbcommon (v2 format) |
|---|
Full Unicode support
❌️ Incomplete
Full support of simple case mappings for xkb_keysym_to_lower() and xkb_keysym_to_upper().
✅ Full support
XKM file format
✅ Full support
Obsolete legacy file format tied to X11 ecosystem.
| Feature | X11 | xkbcommon (v1 format) | xkbcommon (v2 format) |
|---|
! include statement
❌️ No support
See rules include statement for further details.
replace merge mode
❌️ No support
Support the merge mode replace via the prefix ^, in addition to the standard merge | and override + modes.
Extended layout indices
❌️ No support
See extended layout indices for further details.
:all qualifier
❌️ No support
the :all qualifier: it applies the qualified item to all layouts.
See :all qualifier for further details.
Extended wild cards
❌️ No support
See rules wildcards for further information.
| Feature | X11 | xkbcommon |
|---|
XML format
❌️ No support
Relative to the standard implementation in libX11 (described in the Compose(5) man-page):
| Feature | X11 (libX11) | xkbcommon |
|---|
[!] MODIFIER syntax
✅ Full support
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.
Modifier keysyms in sequences
✅ Full support
Modifiers should not be used in Compose sequences. Use keymap’s features or a keysym with more appropriate semantics.
Interactions with Braille keysyms
✅ Full support