DOCSEARCHbyAlgolia
Submit Docs

libxkbcommon Documentation

repository·master·Indexed 18 days ago

https://github.com/xkbcommon/libxkbcommon

A keyboard keymap compiler and support library implementing the XKB specification. Used widely in Wayland environments to translate hardware key events into characters and actions. Includes documentation on building with Meson, using xkbcli tools for layout development, and creating custom keyboard layouts and options.

Tokens
27.9K
Snippets
61
Records
110
Agent score
60%

What's inside libxkbcommon

  1. Overview of libxkbcommon

    master

    libxkbcommon is a keyboard keymap compiler and support library that processes keymaps defined by the XKB (X Keyboard Extension) specification. It is the standard keymap handling library on Wayland and is used by compositors, toolkits, and applications to translate key events into characters and actions.

    Key components include:

    • Keymap Compiler: Processes XKB-compliant keymaps.
    • Compose/Dead Keys Module: Handles character composition and dead keys.
    • Registry Library: A separate library for listing available keyboard layouts.
    • CLI Tools: Provided via xkbcli for development and debugging.

  2. What is a Complete Keymap?

    master

    A complete keymap is a self-contained text file containing all the necessary KcCGST components to configure a keyboard. It is the result of resolving an RMLVO configuration into its low-level parts.

    This format is used by X11 and Wayland when they need to serialize the keymap currently in use. While RMLVO is the preferred configuration method for most users, power users may interact with complete keymaps for advanced configurations.

  3. Understand the `xkb_types` section in XKB keymaps

    master

    The xkb_types section defines key types, which determine the shift level used to translate a key into a keysym based on the current keyboard state (modifiers and group). Key types are assigned to specific groups of keys within the xkb_symbols section.

    Key types act as a mapping between modifiers and shift levels. They are used by the library to compute:

    • The shift level (via xkb_state::xkb_state_key_get_level()).
    • The consumed modifiers (via xkb_state::xkb_state_key_get_consumed_mods() and xkb_state::xkb_state_key_get_consumed_mods2()).

  4. Use keyboard overlays

    master

    An overlay allows a subset of the keyboard to report alternate keycodes when an overlay control (e.g., XKB_KEYBOARD_CONTROL_OVERLAY1) is enabled. This is common for simulating a numeric keypad on a laptop.

    Overlay Support by Format

    FeatureXKB_KEYMAP_FORMAT_TEXT_V1XKB_KEYMAP_FORMAT_TEXT_V2
    Number of overlays28
    ControlsOverlay1, Overlay2Overlay1 to Overlay8
    OverlappingDisjoint only (no overlap)Overlapping allowed

    Overlapping Overlays (V2 only)

    In V2, a key can belong to multiple overlays. If multiple overlays are active, the most recently activated overlay takes precedence. When the most recent overlay is deactivated, the previously active overlay resumes precedence.

    xkb_symbols {
    key <AD07> {
        [u, U],
        overlay1=<KP6>, // numpad overlay
        overlay2=<INS>  // edit overlay
    };
};

  5. How the XKB extensions lookup mechanism works

    master

    When libxkbcommon resolves include paths, it appends subdirectories from the extensions directories in lexicographic order after the extra path but before the canonical XKB root.

    Priority Rules:

    • Versioned vs Unversioned: Unversioned subdirectories are only appended if there is no corresponding versioned subdirectory for that package. This allows a package to provide specific files for an older version of xkeyboard-config while providing fallback files for newer versions.
    • Order of operations: The lookup follows this general sequence:
      1. User paths (~/.config/xkb, ~/.xkb)
      2. Extra paths (/etc/xkb)
      3. Versioned extensions subdirectories (lexicographic order)
      4. Unversioned extensions subdirectories (lexicographic order, only if no versioned match exists)
      5. Canonical XKB root

  6. Understand the XKB text format and use cases

    master

    The XKB text format is a configuration syntax similar to C, used to define keyboard keymaps. It is used in two primary scenarios:

    1. Server-side: The server assembles a keymap from an RMLVO configuration and its corresponding KcCGST component files from a configuration database. It then handles input events by updating the keyboard state.
    2. Client-side: The client loads a complete, self-contained keymap file directly from the server and handles update events.

    File Types

    • Keymap file: A complete description of the xkb_keymap object. This is what a server sends to a client.
    • Keymap component file: Contains descriptions of specific KcCGST components. A server uses these to assemble a full keymap file.

  7. Use `preserve` to prevent modifiers from being consumed

    master

    When a key type is used for keysym translation, its modifiers are considered "consumed." This means applications processing modifiers later should mask them out because they have already performed their role.

    If you want a modifier to affect the keysym translation but not be reported as consumed (allowing applications to detect shortcuts using that modifier), use a preserve[] statement. The modifiers inside preserve[] must match one of the map[] entries in the type.

    Example: In a type where Control is used to access levels 3 and 4, using preserve[Control] = Control; ensures Control is not reported as consumed, allowing applications to detect shortcuts with alternative keysyms.

    type "TWO_LEVEL_PLUS_CONTROL" {
    modifiers = Shift + Control;
    map[None]          = Level1;
    map[Shift]         = Level2;
    map[Control]        = Level3;
    map[Control+Shift] = Level4;
    
    preserve[Control]       = Control;
    preserve[Control+Shift] = Control;
    // ...
};

  8. Understand Unicode keysym encoding

    master

    Unicode keysyms represent ISO 10646 / Unicode characters in the range 0x01000100 to 0x0110FFFF.

    To calculate the numeric value of a Unicode keysym, take the Unicode code point of the character and add 0x01000000. For example, the character U+0100 is represented by the keysym 0x01000100.

    Important Encoding Rules:

    • Dead keys: These must be encoded as function keysyms, not as the Unicode keysym for an equivalent combining character.
    • Graphical symbols vs. Functions: If a keycap shows a symbol that also exists in Unicode (like an arrow) but the key performs a specific function (like cursor movement), use the appropriate function keysym instead of the Unicode keysym.

  9. Understand XKB Modifiers

    master

    A modifier is a key that changes the effect of other keys. Modifiers are categorized into two types:

    Real Modifiers

    These are the 8 predefined (core/X11) modifiers used for backward compatibility and to compute shift levels. They are communicated via the xkbcommon API.

    • Core modifiers: Predefined modifiers like Shift, Lock, Control, and generic Mod[1-5].
    • Extended real modifiers: Real modifiers that are not among the 8 predefined ones.

    Virtual Modifiers

    These are names of real modifier masks and are not predefined. Core real modifiers are also interpreted as canonical virtual modifiers.

    Modifier States

    A modifier can report its state in three ways:

    • Depressed: Active while the key is logically held down (e.g., standard Shift).
    • Latched: Activated on press/release, then automatically deactivated after the next non-modifier key press (e.g., a "sticky" Shift).
    • Locked: Toggled on/off by pressing the key (e.g., Caps_Lock).

  10. Understand XKB extensions directories for layout packaging

    master

    Since version 1.13, libxkbcommon supports a mechanism for installing keyboard layout packages via extensions directories. This allows packages to install files without modifying the core xkeyboard-config system directories.

    There are two optional root extensions directories:

    1. Unversioned directory (XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH): Intended as the default path and for forward compatibility. It typically defaults to <xkeyboard-config-root> - version suffix + .d (e.g., /usr/share/xkeyboard-config.d).
    2. Versioned directory (XKB_CONFIG_VERSIONED_EXTENSIONS_PATH): Intended for backward compatibility with older xkeyboard-config packages. It typically defaults to <xkeyboard-config-root> + .d (e.g., /usr/share/xkeyboard-config-2.d).

    Note: The versioned directory has higher priority than the unversioned directory.

  11. How KcCGST values are updated via rules

    master

    When a rule matches a rule set, its KcCGST value is used to update the current configuration. The update behavior depends on the merge mode specified in the rule value:

    • Replace (default): Using a bare value like bar replaces the old value (if the old value was foo, it becomes bar). If the old value was empty, it becomes bar.
    • Skip: If the rule value is bar and the old value is foo, the update is skipped (the value remains foo).
    • Override/Prepend (+): Using +bar prepends the value. For example, if the old value was foo, the new value becomes bar+foo.
    • Augment (|) or Replace (^): These are alternative merge modes used to specify different behaviors (refer to the full grammar for specific logic).
    Rule valueOld KcCGST valueNew KcCGST value
    bar(empty)bar
    barfoofoo (skip)
    +foobarbar+foo (prepend)
    +bar(empty)+bar
    +barfoofoo+bar
    +bar+foo+foo+bar

  12. Understand the three meanings of XKB

    master

    XKB (X Keyboard Extension) refers to three distinct but related concepts that a developer needs to distinguish:

    1. The Protocol: An extension for the X Window System. While libxkbcommon is derived from this, it is a reworked library that works independently of a windowing system (e.g., it is used by Wayland).
    2. Keyboard Layout Configuration: The method of composing a complete keymap. Users typically interact with high-level configurations (RMLVO), while the system uses low-level components (KcCGST).
    3. The Text Format: A specific text-based specification used to define keyboard keymaps. libxkbcommon supports a format very close to XKB 1.0.