XKB Compatibility

Table of Contents

• Keymap support
  • General features
  • Key actions
  • Keymap text format
  • API
• Rules support
• Keyboard layout registry
• Compose support

❌️ 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.

Todo:

This page is work in progress. It aims to be exhaustive. Please report any issue.

Keymap support

General features

Keymap features compatibility table

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

Todo:

rationale </details>

❌️ No support

Parse error. </details>

<details>

⚠️ Parsing & handling, no serialization

Currently limited to 1 action for each action type “group” and “modifier”.

Since

1.8: Enable multiple actions per level (parsing, serializing & handling).

1.11: Serialize to VoidAction() for compatibility with X11. </details>

<details>

⚠️ Partial support

Currently limited to 1 action for each action type “group” and “modifier”.

Since

1.11 </details>

Geometry

✅ Full support

<details>

⚠️ Parsing only

Rational:

• There were very few geometry definitions available in xkeyboard-config, and while xkbcommon was responsible for parsing this insanely complex format, it never actually did anything with it.
• Hopefully someone will develop a companion library which supports keyboard geometries in a more useful format, e.g. SVG. </details>

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>

Key behaviors

✅ 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>

Indicator behaviors

✅ 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>

Key actions

Key actions compatibility table

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>

Keymap text format

Keymap text format compatibility table

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

Todo:

syntax description </details>

⚠️ 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>

API

API compatibility table

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>

KcCGST

✅ Full support

<details>

⚠️ Partial support (since 1.10)

• KcCGST is considered an implementation detail, use RMLVO instead.
• Use 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>

Rules support

API compatibility table

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)

• single: matches a single layout; layout[single] is the same as without explicit index: layout.
• first: matches the first layout/variant, no matter how many layouts are in the RMLVO configuration. Acts as both layout and layout[1].
• later: matches all but the first layout. This is an index range. Acts as layout[2] .. layout[MAX_LAYOUT], where MAX_LAYOUT is currently 4.
• any: matches layout at any position. This is an index range.
• the :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>

Keyboard layout registry

Keyboard layout registry support

Feature

X11

xkbcommon </thead> <tbody>

XML format

❌️ No support

<details>

✅ Full support

Todo:

rationale </details>

</tbody>

Compose support

Relative to the standard implementation in libX11 (described in the Compose(5) man-page):

Compose support

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.

Todo:

removal rationale </details>

⚠️ 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

Todo:

feature description, removal rationale </details>

</tbody>