libxkbcommon

https://github.com/xkbcommon/libxkbcommon
Admin
libxkbcommon is a keyboard keymap compiler and support library that processes XKB keymaps with...
Tokens:35,002
Snippets:461
Trust Score:7.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example indicator configuration

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

A complete example where the Num Lock LED lights up when the NumLock modifier is locked.

```xkb
indicator "Num Lock" {
    modifiers = NumLock;
    whichModState = Locked;
};
```

--------------------------------

### Complete Include Syntax Examples

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Demonstrates various merge modes, absolute paths, and multiple file inclusion patterns.

```c
// Default merge mode, 1 file with an implicit section name
include "<PATH>"
// Augment merge mode, 1 file with an implicit section name
augment "<PATH>(<SECTION_NAME>)"
// Absolute path and %-expansion
include "/usr/share/X11/xkb/symbols/pc"
include "%S/pc"
// Override merge mode, 2 files: a first file with an implicit section name merged
// using the augment mode with a second file with an explicit section name
override "<PATH_1>|<PATH_2>(<SECTION_NAME>)
```

--------------------------------

### Using %-Expansion for System Paths

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Example of using %S expansion to reference system-installed XKB directories while overriding specific keys.

```c
// File: ~/.config/xkb/symbols/de
xkb_symbols "basic" {
    // Include the system file /usr/share/X11/xkb.
    //
    // Note that it is not be possible to use `include "de(basic)"` because
    // it would create an include *loop*.
    include "%S/de(basic)"
    // Override the system file entries
    key <AB01> { [z, Z] };
    key <AD06> { [y, Y] };
}
```

--------------------------------

### Install towncrier

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/changes/README.md

Install the towncrier package using pip.

```bash
python3 -m pip install towncrier
```

--------------------------------

### Initialize and Process Keyboard Events in C

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/quick-guide.md

Demonstrates the lifecycle of a keyboard object, including context initialization, keymap setup, event processing, and resource cleanup.

```c
#include <xkbcommon/xkbcommon.h>

int new_keyboard(…)
{
    /*
    * Initialize the context
    */

    struct xkb_context *ctx;

    ctx = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
    if (!ctx) <error>

    struct xkb_keymap *keymap;
    /* Example RMLVO for Icelandic Dvorak. */
    struct xkb_rule_names names = {
        .rules = NULL,
        .model = "pc105",
        .layout = "is",
        .variant = "dvorak",
        .options = "terminate:ctrl_alt_bksp"
    };

    /*
    * Initialize the keymap
    */

    keymap = xkb_keymap_new_from_names2(ctx, &names,
                                        XKB_KEYMAP_FORMAT_TEXT_V1,
                                        XKB_KEYMAP_COMPILE_NO_FLAGS);
    if (!keymap) <error>

    /*
    * Initialize the keymap
    */

    enum xkb_error_code error;
    struct xkb_machine_builder *machine_builder =
        xkb_machine_builder_new(keymap, XKB_MACHINE_BUILDER_NO_FLAGS, &error);
    if (!machine_builder) {
        assert(error != XKB_SUCCESS);
        switch (error) {
        // ...
        default:
            exit(EXIT_FAILURE);
        }
    }
    struct xkb_machine *machine = xkb_machine_new(machine_builder, &error);
    xkb_machine_builder_unref(machine_builder);
    if (!machine) {
        assert(error != XKB_SUCCESS);
        switch (error) {
        // ...
        default:
            exit(EXIT_FAILURE);
        }
    }

    struct xkb_events *events;

    events = xkb_events_new(ctx, NULL, &error);
    if (!events) {
        assert(error != XKB_SUCCESS);
        switch (error) {
        // ...
        default:
            exit(EXIT_FAILURE);
        }
    }

    char *keymap_string =
        xkb_keymap_get_as_string(keymap, XKB_KEYMAP_FORMAT_TEXT_V1);
    <send keymap to the clients>
    free(keymap_string)

    <save the objects for further use>

    return EXIT_SUCCESS;
}

int destroy_keyboard(…)
{
    xkb_events_unref(events);
    xkb_machine_unref(machine);
    xkb_keymap_unref(keymap);
    xkb_context_unref(ctx);
    return EXIT_SUCCESS;
}

int handle_key(…)
{
    /*
     * Update the server state with the key event
     */

    enum xkb_key_direction direction = (<key release>)
        ? XKB_KEY_UP
        : (<key repeated>)
            ? XKB_KEY_REPEATED
            : XKB_KEY_DOWN;
    int ret = xkb_machine_process_key(machine, keycode, direction, events);
    if (ret) <error>

    /*
     * Process the generated XKB events
     */

    const struct xkb_event *event;
    while ((event = xkb_events_next(events)) != NULL) {
        const enum xkb_event_type event_type =
            xkb_event_get_type(event);
        switch (event_type) {
            case XKB_EVENT_TYPE_KEY_DOWN:
            case XKB_EVENT_TYPE_KEY_REPEATED:
            case XKB_EVENT_TYPE_KEY_UP: {
                const xkb_keycode_t kc = xkb_event_get_keycode(event);
                const enum xkb_key_direction direction =
                    (event_type == XKB_EVENT_TYPE_KEY_UP)
                        ? XKB_KEY_UP
                        : (XKB_EVENT_TYPE_KEY_REPEATED)
                            ? XKB_KEY_REPEATED
                            : XKB_KEY_DOWN;
                <send key event to clients>
            }
            case XKB_EVENT_TYPE_COMPONENTS_CHANGE: {
                const enum xkb_state_component =
                    xkb_event_get_changed_components(event);
                if (changed) {
                    const xkb_mod_mask_t depressed_mods =
                        xkb_event_serialize_mods(event, XKB_STATE_MODS_DEPRESSED);
                    const xkb_mod_mask_t latched_mods =
                        xkb_event_serialize_mods(event, XKB_STATE_MODS_LATCHED);
                    const xkb_mod_mask_t locked_mods =
                        xkb_event_serialize_mods(event, XKB_STATE_MODS_LOCKED);
                    const xkb_layout_index_t depressed_layout =
                        xkb_event_serialize_layout(event, XKB_STATE_LAYOUT_DEPRESSED);
                    const xkb_layout_index_t latched_layout =
                        xkb_event_serialize_layout(event, XKB_STATE_LAYOUT_LATCHED);
                    const xkb_layout_index_t locked_layout =
                        xkb_event_serialize_layout(event, XKB_STATE_LAYOUT_LOCKED);
                    <send modifiers event>
                }
                break;
            }
            default:
                <report unhandled event>
        }
    }
}
```

--------------------------------

### Inferred Key Types Examples

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Demonstrates how the XKB heuristic automatically assigns key types based on the number and nature of keysyms provided.

```c
// 1 to 2 keysyms
key <LFSH> { [Shift_L] };                    // Type: ONE_LEVEL
key <AE01> { [1, exclam] };                  // Type: TWO_LEVEL
key <AD01> { [q, Q] };                       // Type: ALPHABETIC
key <KP1>  { [KP_End, KP_1] };               // Type: KEYPAD
// Edge case: this is consider alphabetic, although
// the lower case does not correspond to the upper case.
key <AD01> { [q, N] };                       // Type: ALPHABETIC

// 3 to 4 keysyms
key <AE01> { [1, exclam, bar] };             // Type: FOUR_LEVEL
key <AE01> { [1, exclam, bar, exclamdown] }; // Type: FOUR_LEVEL
key <AD01> { [q, Q, at] };                   // Type: FOUR_LEVEL_SEMIALPHABETIC
key <AD01> { [q, Q, at, Greek_OMEGA] };      // Type: FOUR_LEVEL_SEMIALPHABETIC
key <AD05> { [t, T, tslash, Tslash] };       // Type: FOUR_LEVEL_ALPHABETIC

// The inferred type is `FOUR_LEVEL`, but using `LevelThree+Lock`
// will produce `Q`, because of the keysyms transformations and
// the corresponding internal capitalization processing.
key <AE01> { [1, exclam, q, Q] };            // Type: FOUR_LEVEL

// Won’t work, because there is no heuristic for more than 4 keysyms
// It will trigger the warnings XKB-183 and XKB-516 and default to ONE_LEVEL,
// ignoring all the keysyms but the first one.
key <AD01> {[q, Q, at, any, masculine, U2642]};
// Will work as expected
key <AD01> {
    type[Group1] = "EIGHT_LEVEL_SEMIALPHABETIC",
    [q, Q, at, any, masculine, U2642]
};
```

--------------------------------

### Define XKB rule sets

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/rules-format.md

Rule sets start with a '!' header and map MLVO options to KcCGST symbols.

```c
// This is a comment

// The following line is a rule header.
// It starts with ‘!’ and introduces a rules set.
// It indicates that the rules map MLVO options to KcCGST symbols.
! option       = symbols
  // The following lines are rules that add symbols of the RHS when the
  // LHS matches an option.
  ctrl:nocaps  = +ctrl(nocaps)
  compose:menu = +compose(menu)

// One may use multiple MLVO components on the LHS
! layout    option          = symbols
  be        caps:digits_row = +capslock(digits_row)
  fr        caps:digits_row = +capslock(digits_row)
```

--------------------------------

### Applying section flags

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Example of applying a partial flag to an xkb_symbols section.

```xkb
partial alphanumeric_keys
xkb_symbols "basic" {
    ...
}
```

--------------------------------

### Register custom layouts and options in evdev.xml

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/custom-configuration.md

Example XML configuration for adding custom layouts, variants, and options to the XKB registry.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xkbConfigRegistry SYSTEM "xkb.dtd">
<xkbConfigRegistry version="1.1">
  <layoutList>
    <!-- Declare a new layout and its variants -->
    <layout>
      <!-- Default variant: `default … xkb_symbols "…"` -->
      <configItem>
        <!-- File name of $XDG_CONFIG_HOME/xkb/symbols/banana -->
        <name>banana</name>
        <shortDescription>ban</shortDescription>
        <!-- Label: use the value of `name[Group1]` -->
        <description>Banana (US)</description>
      </configItem>
      <!-- Other variants -->
      <variantList>
        <variant>
          <configItem>
            <!-- Section name in $XDG_CONFIG_HOME/xkb/symbols/banana -->
            <name>orange</name>
            <shortDescription>or</shortDescription>
            <!-- Label: use the value of `name[Group1]` -->
            <description>Banana (Eurosign on 5)</description>
          </configItem>
        </variant>
      </variantList>
    </layout>
    <!-- Update a *system* layout and its variants -->
    <layout>
      <configItem>
        <!-- NOTE: Only minimal data is required here,
             since it will be merged with the system registry -->
        <name>us</name>
      </configItem>
      <variantList>
        <variant>
          <configItem>
            <!-- Section name in $XDG_CONFIG_HOME/xkb/symbols/us -->
            <name>broccoli</name>
            <shortDescription>bro</shortDescription>
            <!-- Label: use the value of `name[Group1]` -->
            <description>Broccoli</description>
          </configItem>
        </variant>
      </variantList>
    </layout>
  </layoutList>
  <optionList>
    <group allowMultipleSelection="true">
      <configItem>
        <name>custom</name>
        <description>Custom options</description>
      </configItem>
      <option>
      <configItem>
        <name>custom:foo</name>
        <description>Map Tilde to nothing</description>
      </configItem>
      </option>
      <option>
      <configItem>
        <name>custom:baz</name>
        <description>Map Z to K</description>
      </configItem>
      </option>
    </group>
  </optionList>
</xkbConfigRegistry>
```

--------------------------------

### Private action usage

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Examples of using the Private action for raw XKB protocol encoding.

```text
Private(type=123, data="abcdefg");
```

```text
Private(type=123, data[1]=0, data[2]=100, data[3]=12);
```

--------------------------------

### Define Custom Keyboard Layout

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/custom-configuration.md

Example of defining a 'banana' layout with a 'basic' default and an 'orange' variant.

```c
// Like a US layout but swap the top row so numbers are on Shift
default partial alphanumeric_keys
xkb_symbols "basic" {
    include "us(basic)"
    name[Group1]= "Banana (US)";

    key <AE01> { [ exclam,          1]     };
    key <AE02> { [ at,              2]     };
    key <AE03> { [ numbersign,      3]     };
    key <AE04> { [ dollar,          4]     };
    key <AE05> { [ percent,         5]     };
    key <AE06> { [ asciicircum,     6]     };
    key <AE07> { [ ampersand,       7]     };
    key <AE08> { [ asterisk,        8]     };
    key <AE09> { [ parenleft,       9]     };
    key <AE10> { [ parenright,      0]     };
    key <AE11> { [ underscore,      minus] };
    key <AE12> { [ plus,            equal] };
};

// Same as banana but map the euro sign to the 5 key
partial alphanumeric_keys
xkb_symbols "orange" {
    include "banana(basic)"
    name[Group1] = "Banana (Eurosign on 5)";
    include "eurosign(5)"
};
```

--------------------------------

### Implicit Modifier Encoding Example

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Demonstrates how a virtual modifier is implicitly bound to a real modifier through key and modifier maps.

```c
xkb_symbols {
    virtual_modifiers Alt;

    // Virtual modifier map: Alt is bound to <LALT>
    // Note: alternatively one can use xkb_compat interpretations.
    key <LALT> { virtualModifier = Alt };

    // Real modifier map: Mod1 is bound to <LALT>
    modifier_map Mod1 { <LALT> };

    // Implicit encoding: Alt = Mod1
};
```

--------------------------------

### Fix Global Defaults Scope Error

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/message-registry.md

Examples showing how to resolve XKB-428 by moving global default assignments out of key statements.

```c
key <AE01> {
    key.type = "FOUR_LEVEL_SEMIALPHABETIC",
    symbols = [q, Q, at]
};
```

```c
// Either put default key type in global file scope
key.type = "FOUR_LEVEL_SEMIALPHABETIC";
key <AE01> { [q, Q, at] };
// or use a local setting (unqualified, i.e. without `key.`)
key <AE01> {
    type = "FOUR_LEVEL_SEMIALPHABETIC",
    symbols = [ q, Q, at ]
};
```

--------------------------------

### Implement complex key type and usage

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Example of a custom key type using preserve to handle Control shortcuts and its application in a symbol definition.

```c
xkb_types {
    // ...
    type "TWO_LEVEL_PLUS_CONTROL" {
        modifiers = Shift + Control;
        map[None]          = Level1;
        map[Shift]         = Level2;
        map[Control]       = Level3;
        map[Control+Shift] = Level4;
        // Using preserve will make Control not consumed and allow
        // applications to detect keyboard shortcuts with alternative
        // keysyms in levels 3 and 4 rather than the levels 1 and 2.
        preserve[Control]       = Control;
        preserve[Control+Shift] = Control;
        level_name[Level1] = "Base";
        level_name[Level2] = "Shift";
        level_name[Level3] = "Tweaked Control";
        level_name[Level4] = "Tweaked Control + Shift";
    };
};
xkb_symbols {
    // ...
    // The following key would produce Greek keysym on Base and Shift levels,
    // but will produce the corresponding ASCII Latin keysyms when using Control.
    key <AC01> {
        type[Group1]="TWO_LEVEL_PLUS_CONTROL",
        [Greek_alpha, Greek_ALPHA, a, A]
    };
};
```

--------------------------------

### Setting the Real Modifier Map

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Examples of binding real modifiers using direct keycode references, indirect keysym lookups, and combined lists.

```c
// Bind `Mod1` to the keycode <LALT>.
modifier_map Mod1 { <LALT> };
```

```c
// Bind `Mod1` looking up for the keysym `Alt_L`
modifier_map Mod1 { Alt_L };
```

```c
// Bind `Mod1` diretly to keycode <LALT> and indirectly via the keysym `Alt_L`
modifier_map Mod1 { <LALT>, Alt_L };
```

--------------------------------

### Initialize libxkbcommon context

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/quick-guide.md

Create a new library context to manage keymap include paths and logging.

```c
#include <xkbcommon/xkbcommon.h>

struct xkb_context *ctx;

ctx = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
if (!ctx) <error>
```

--------------------------------

### Retrieve keysyms from state

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/quick-guide.md

Use this to get multiple keysyms resulting from a single event.

```c
    const xkb_keysym_t *keysyms;
    int num_keysyms;

    num_keysyms = xkb_state_key_get_syms(state, keycode, &keysyms);
```

--------------------------------

### Simple XKB Include and Section Matching

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Shows how including a specific section from a file merges key definitions, with the included section overriding existing keys.

```c
xkb_symbols {
    key <A> { [a, A, ae, AE] };
    include "B(S2)"
};
```

```c
// This section is not used (does not match)
xkb_symbols "S1" {
    key <B> { [b, B] };
};
// This section will be included (match the included section name)
xkb_symbols "S2" {
    key <A> { [Greek_alpha, Greek_ALPHA] };
    key <B> { [Greek_beta , Greek_BETA ] };
};
```

```c
xkb_symbols {
    // Key overridden: mix of old + new
    key <A> { [Greek_alpha, Greek_ALPHA, ae, AE] };
    // New key
    key <B> { [Greek_beta , Greek_BETA         ] };
};
```

--------------------------------

### Build libxkbcommon with Meson

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/README.md

Standard commands to configure, compile, and test the library using the Meson build system.

```shell
meson setup build
meson compile -C build
meson test -C build # Run the tests.
```

--------------------------------

### Use groups in XKB rules

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/rules-format.md

Groups allow defining a set of values once and referencing them by a name starting with '$'.

```c
// Let’s rewrite the previous rules set using groups.
// Groups starts with ‘$’.

// Define a group for countries with AZERTY layouts
! $azerty = be fr

// The following rule will match option `caps:digits_row` only for
// layouts in the $azerty group, i.e. `fr` and `be`.
! layout    option          = symbols
 $azerty    caps:digits_row = +capslock(digits_row)
```

--------------------------------

### Create temporary XKB directory

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/custom-configuration.md

Sets up a temporary directory structure for testing custom XKB symbols.

```shell
mkdir -p "/tmp/xkb/symbols"
```

--------------------------------

### Define extended real modifier maps

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Examples of using non-X11 core modifiers and mixed modifier masks.

```c
// New: non-X11 core modifiers
modifier_map 0x100 { … };
// New: multiple non-X11 core modifiers
modifier_map 0xf00 { … };
// New: Mix of X11 core and non core modifiers
modifier_map Mod2+0x100 { … };
// New: Numeric equivalent of the previous entry
modifier_map 0x110 { … };
```

--------------------------------

### Define interpretation entry for ISO_Last_Group

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/compatibility.md

Example of using the First/Last group index constants in a keymap interpretation entry.

```c
interpret ISO_Last_Group {
    action= LockGroup(group=last);
};
```

--------------------------------

### XKB Include Path Resolution

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Demonstrates how XKB resolves include statements by searching through user and system configuration directories.

```c
xkb_symbols {
    include "it"          // Exists only in system directory
    include "my_own_file" // Exists only in user directory
    include "es"          // Exists in both user and system directory
};
```

```c
xkb_symbols {
    include "/usr/share/X11/xkb/symbols/it"
    include "/home/<USER>/.config/xkb/symbols/my_own_file"
    include "/home/<USER>/.config/xkb/symbols/es"
};
```

--------------------------------

### Replace xkbcomp -xkb /path/to/keymap/file - with xkbcli

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/faq.md

Compile a keymap file using the xkbcli compile-keymap command.

```bash
xkbcli compile-keymap --keymap /path/to/keymap/file
```

--------------------------------

### Define X11 core modifier maps

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Examples of using X11 core modifiers and numeric masks in modifier maps.

```c
modifier_map Shift { … };
// New: numeric equivalent of the previous entry
modifier_map 0x001 { … };
// New: modifier mask expression
modifier_map Mod1+Mod2 { … };
// New: numeric equivalent of the previous entry
modifier_map 0x018 { … };
```

--------------------------------

### Replace xkbcomp -xkb $DISPLAY - with xkbcli

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/faq.md

Dump the current keymap for different session types.

```bash
xkbcli dump-keymap
```

```bash
xkbcli dump-keymap-wayland
```

```bash
xkbcli dump-keymap-x11
```

--------------------------------

### Preview layout interactively

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/custom-configuration.md

Opens an interactive window to test key behavior in real-time.

```shell
xkbcli compile-keymap --include /tmp/xkb \
                      --include-defaults \
                      --layout test \
| xkbcli interactive
```

--------------------------------

### Apply Custom Keymap to X11

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/debugging.md

Compiles a custom keymap and applies it to the current X11 display using xkbcomp.

```bash
xkbcli compile-keymap --include ~/xkb-test --include-defaults --layout my-layout \
  | xkbcomp - $DISPLAY
```

--------------------------------

### Configure libxkbcommon for Wayland

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/README.md

Build configuration to disable X11 support while specifying paths for X11 keyboard configuration resources.

```shell
meson setup build \
      -Denable-x11=false \
      -Dxkb-config-root=/usr/share/X11/xkb \
      -Dx-locale-root=/usr/share/X11/locale
meson compile -C build
```

--------------------------------

### Effective Modifier Encoding Example

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Illustrates a complex configuration involving multiple virtual modifiers and their respective real modifier mappings.

```c
xkb_symbols {
    virtual_modifiers Alt, Meta, Super = none, Hyper = 0x1000, Useless = none;

    // Virtual modifier maps
    // Note: alternatively one can use xkb_compat interpretations.
    key <LALT> { virtualModifier = Alt   }; // Alt is bound to <LALT>
    key <LWIN> { virtualModifier = Super }; // Super is bound to <LWIN>
    key <RWIN> { virtualModifier = Super }; // Super is bound to <RWIN>
    key <HYPR> { virtualModifier = Hyper }; // Hyper is bound to <HYPR>

    // Real modifier maps
    modifier_map Mod1 { <LALT> }; // Mod1 is bound to <LALT>
    modifier_map Mod4 { <LWIN> }; // Mod4 is bound to <LWIN>
    modifier_map Mod5 { <RWIN> }; // Mod5 is bound to <RWIN>
    modifier_map Mod3 { <HYPR> }; // Mod3 is bound to <HYPR>

};
```

--------------------------------

### Configure action

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Binds actions to matching levels, supporting single actions or sequences since version 1.9.0.

```xkb
action = LockMods(modifiers=NumLock);
action = {SetMods(modifiers=NumLock),SetGroup(group=2)};
```

--------------------------------

### Define layout-specific rules in XKB

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/rules-format.md

Use the [any] range and :%i specifier to create rules that apply to specific layouts within a multi-layout configuration.

```c
! layout[first] = symbols
  *             = pc

! layout[any] = symbols
  *           = +%l[%i]%(v[%i])

// Not layout-specific
! option      = symbols
  opt1        = +opt1

// Layout-specific: note the range `[any]` and the `:%i` specifier
! layout[any]   option     = symbols
  *             opt2       = +opt2:%i
```

--------------------------------

### Replace setxkbmap -print -layout with xkbcli

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/faq.md

Use the --kccgst option to replicate the print layout functionality.

```bash
xkbcli compile-keymap --kccgst --layout …
```

--------------------------------

### Query XKB dependencies

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/introspection.md

Analyze dependencies using RDF Turtle format and SPARQL queries.

```bash
# Get data about the XKB directories
introspection-query tree XKB_ROOT -- --rdf --recursive > /tmp/tree.ttl
# Query direct dependencies
introspection-query deps --include XKB_ROOT --type TYPE --file FILE --section SECTION /tmp/tree.ttl
# Query all dependencies
introspection-query deps --include XKB_ROOT --type TYPE --file FILE --section SECTION --transitive /tmp/tree.ttl
```

--------------------------------

### Identify unused XKB files and sections

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/introspection.md

Analyze rulesets against the XKB tree to find unused items.

```bash
# Get data about the XKB directories
introspection-query tree XKB_ROOT -- --rdf --recursive > /tmp/tree.ttl
# Analyze a ruleset
RULES=evdev; introspection-query rules --rules $RULES --rdf --output /tmp/$RULES.ttl XKB_ROOT
# Get the unused items for a specific ruleset
RULES=evdev; cat /tmp/tree.ttl /tmp/$RULES.ttl | introspection-query use --include XKB_ROOT --unused -
# Get the unused items for multiple rulesets
cat /tmp/tree.ttl /tmp/base.ttl /tmp/evdev.ttl | introspection-query use --include XKB_ROOT --unused -
```

--------------------------------

### Get virtual modifier encoding (libxkbcommon ≤ 1.9)

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/faq.md

Use this approach for older versions of libxkbcommon to map virtual modifiers to real modifier masks.

```c
// Find the real modifier mapping of the virtual modifier `LevelThree`
#include <xkbcommon/xkbcommon.h>
#include <xkbcommon/xkbcommon-names.h>
const xkb_mod_index_t levelThree_idx = xkb_keymap_mod_get_index(keymap, XKB_VMOD_NAME_LEVEL3);
const xkb_mod_mask_t levelThree = UINT32_C(1) << levelThree_idx;
struct xkb_state* state = xkb_state_new(keymap);
assert(state); // Please handle error properly
xkb_state_update_mask(state, levelThree, 0, 0, 0, 0, 0);
const xkb_mod_mask_t levelThree_mapping = xkb_state_serialize_mods(state, XKB_STATE_MODS_EFFECTIVE);
xkb_state_unref(state);
```

--------------------------------

### Create keyboard state

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/quick-guide.md

Initialize an xkb_state object to track modifiers and LEDs, with specific variants for standard and X11 clients.

```c
struct xkb_state *state;

enum xkb_error_code error;
state = xkb_state_new_with_mode(keymap, XKB_STATE_MODE_CLIENT, &error);
if (!state) {
    assert(error != XKB_SUCCESS);
    switch (error) {
    // ...
    default:
        exit(EXIT_FAILURE);
    }
}
```

```c
state = xkb_x11_state_new_from_device(keymap, conn, device_id);
if (!state) <error>
```

--------------------------------

### Compile and Test Custom Keymap

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/debugging.md

Verifies that a custom keymap configuration compiles correctly using the specified include paths.

```bash
xkbcli compile-keymap --include ~/xkb-test --include-defaults --test --layout my-layout
```

--------------------------------

### Define a key type

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Basic syntax for creating a new key type definition.

```xkb
type "FOUR_LEVEL" { ... }
```

--------------------------------

### Define Layout and Option Symbol Rules

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/rules-format.md

Maps layout and option combinations to symbols, demonstrating how rules are applied based on index and order.

```c
! $azerty = be fr

! layout = symbols
  *      = pc+%l%(v)

! layout[1] = symbols
  *         = pc+%l[1]%(v[1])

! layout[2] = symbols
  *         = +%l[2]%(v[2])
// Repeat the previous rules set with indices 3 and 4

! layout     option          = symbols
 $azerty     caps:digits_row = +capslock(digits_row)
  *          misc:typo       = +typo(base)
  *          lv3:ralt_alt    = +level3(ralt_alt)

! layout[1]  option          = symbols
 $azerty     caps:digits_row = +capslock(digits_row):1
  *          misc:typo       = +typo(base):1
  *          lv3:ralt_alt    = +level3(ralt_alt):1
// Repeat the previous rules set for indices 2 to 4
```

```c
! $azerty = be fr

! layout[first] = symbols
  *             = pc+%l[%i]%(v[%i])

! layout[later] = symbols
  *             = +%l[%i]%(v[%i])

! layout[any]  option          = symbols
 $azerty       caps:digits_row = +capslock(digits_row):%i

! option       = symbols
  misc:typo    = +typo(base):all
  lv3:ralt_alt = +level3(ralt_alt):all

// The previous is equivalent to:
! layout[any]  option       = symbols
  *            misc:typo    = +typo(base):%i
  *            lv3:ralt_alt = +level3(ralt_alt):%i
```

--------------------------------

### List XKB file sections in YAML

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/introspection.md

Generate YAML output to analyze file structures, dependencies, or RMLVO-based keymaps.

```bash
# Specific file (absolute path)
introspection --include XKB_ROOT --yaml FILE
# Specific file (relative path)
introspection --include XKB_ROOT --yaml --type TYPE FILE

# Specific file (absolute path) and its transitive dependencies
introspection --include XKB_ROOT --yaml --recursive FILE

# Keymap from RMLVO
xkbcli compile-keymap --kccgst --layout LAYOUT | introspection --include XKB_ROOT --yaml

# XKB tree
introspection-query tree XKB_ROOT -- --yaml --recursive
# XKB tree for a specific type
introspection-query tree XKB_ROOT --type TYPE -- --yaml --recursive
```

--------------------------------

### XKB Merge Modes: Augment, Replace, and Override

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Illustrates different merge modes for XKB symbols, including augment, replace, and combined include operations.

```c
xkb_symbols {
    key <A> { [a, A, ae, AE] };
    augment "B(S2)"
};
```

```c
xkb_symbols {
    // Key unchanged
    key <A> { [a, A, ae, AE] };
    // New key
    key <B> { [Greek_beta , Greek_BETA] };
};
```

```c
xkb_symbols {
    key <A> { [a, A, ae, AE] };
    replace "B(S2)"
};
```

```c
xkb_symbols {
    // Key replaced
    key <A> { Greek_alpha, Greek_ALPHA] };
    // New key
    key <B> { [Greek_beta , Greek_BETA ] };
};
```

```c
xkb_symbols {
    key <A> { [a, A, ae, AE] };
    // Two files merged together with the merge mode
    // augment, then the result is merged this the
    // statement above using the override merge mode
    include "B(S1)|B(S2)"
};
```

```c
xkb_symbols {
    // Key overridden: mix of old + new
    key <A> { [Greek_alpha, Greek_ALPHA, ae, AE] };
    // New key; "B(2)" had no effect with the
    // merge mode augment "|"
    key <B> { [b, B] };
};
```

--------------------------------

### Replace xev -event keyboard with xkbcli

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/faq.md

Run interactive keyboard event monitoring for different session types.

```bash
xkbcli interactive
```

```bash
xkbcli interactive-wayland
```

```bash
xkbcli interactive-x11
```

--------------------------------

### Create keymap from X11 device

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/quick-guide.md

Retrieve a keymap directly from an X server using the core keyboard device ID.

```c
#include <xkbcommon/xkbcommon-x11.h>

xcb_connection_t *conn = <...>;
int32_t device_id;

device_id = xkb_x11_get_core_keyboard_device_id(conn);
if (device_id == -1) <error>

keymap = xkb_x11_keymap_new_from_device(ctx, conn, device_id,
                                        XKB_KEYMAP_COMPILE_NO_FLAGS);
if (!keymap) <error>
```

--------------------------------

### Build the changelog

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/changes/README.md

Commands to preview or finalize the changelog generation for a specific version.

```bash
# Only check the result. Useful after adding a new fragment.
towncrier build --draft --version 1.8.0
# Write the changelog & delete the news fragments
towncrier build --yes --version 1.8.0
```

--------------------------------

### Define symbols and actions explicitly

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Shows the equivalence between shorthand notation and explicit symbol/action definitions.

```c
key <LCTL> { [ { Control_L, ISO_Group_Shift } ] };
```

```c
key <LCTL> {
    symbols[1] = [ { Control_L,                  ISO_Group_Shift    } ],
    actions[1] = [ { SetMods(modifiers=Control), SetGroup(group=+1) } ]
};
```

```c
key <LCTL> {
    symbols[1] = [ Control_L                                          ],
    actions[1] = [ { SetMods(modifiers=Control), SetGroup(group=+1) } ]
};
```

--------------------------------

### Split multiple layouts into individual sections

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/faq.md

Migrate legacy single-layout definitions containing multiple groups by splitting them into separate xkb_symbols sections.

```c
xkb_symbols "variant1_variant2" {
    key <AD01> {
        symbols[Group1] = [U13AA, U13C6],
        symbols[Group2] = [    q,     Q],
    };
    // …
};
```

```c
xkb_symbols "variant1" {
    key <AD01> { [U13AA, U13C6] };
    // …
};

xkb_symbols "variant2" {
    key <AD01> { [    q,     Q] };
    // …
};
```

--------------------------------

### Create keymap from string

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/quick-guide.md

Create a keymap object from a provided keymap string, typically received from a Wayland compositor.

```c
/* From the wl_keyboard::keymap event. */
const char *keymap_string = <...>;
struct xkb_keymap *keymap;

keymap = xkb_keymap_new_from_string(ctx, keymap_string,
                                    XKB_KEYMAP_FORMAT_TEXT_V1,
                                    XKB_KEYMAP_COMPILE_NO_FLAGS);
if (!keymap) <error>
```

--------------------------------

### Create Release Branch

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/RELEASING.md

Command to initialize a new release branch from the master branch.

```bash
git checkout -b release/vMAJOR.MINOR.PATCH master
```

--------------------------------

### XKB Keymap File Structure

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

The basic skeleton of an xkb_keymap file showing the nested component blocks.

```c
xkb_keymap {
  xkb_keycodes "XXX" {
    // ...
  }
  xkb_types "XXX" {
    // ...
  };
  xkb_compatibility "XXX" {
    // ...
  };
  xkb_symbols "XXX" {
    // ...
  };
};
```

--------------------------------

### Create keymap from RMLVO names

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/quick-guide.md

Configure a keymap using Rules, Model, Layout, Variant, and Options for evdev clients.

```c
struct xkb_keymap *keymap;
/* Example RMLVO for Icelandic Dvorak. */
struct xkb_rule_names names = {
    .rules = NULL,
    .model = "pc105",
    .layout = "is",
    .variant = "dvorak",
    .options = "terminate:ctrl_alt_bksp"
};

keymap = xkb_keymap_new_from_names2(ctx, &names,
                                    XKB_KEYMAP_FORMAT_TEXT_V1,
                                    XKB_KEYMAP_COMPILE_NO_FLAGS);
if (!keymap) <error>
```

--------------------------------

### Compile and test layout

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/custom-configuration.md

Compiles the custom layout to verify syntax and functionality.

```shell
xkbcli compile-keymap --include /tmp/xkb \
                      --include-defaults \
                      --test \
                      --layout test \
&& echo "valid!" || echo "invalid!"
```

--------------------------------

### Verify Distribution

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/RELEASING.md

Command to validate the release build using Meson.

```bash
meson dist -C build
```

--------------------------------

### Resolve XKB file paths

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/introspection.md

Use these commands to determine the resolution of includes or registry entries within XKB directories.

```bash
# TYPE is a KcCGST component
# FILE is a file name
# SECTION is a section name in FILE

# Default section
introspection --include XKB_ROOT --resolve --type TYPE FILE
# Specific section
introspection --include XKB_ROOT --resolve --type TYPE --section SECTION FILE
```

--------------------------------

### XKB Keymap Output

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/custom-configuration.md

The resulting keymap structure after compiling the RMLVO configuration.

```c
xkb_keymap {
	xkb_keycodes  { include "evdev+aliases(qwerty)"	};
	xkb_types     { include "complete"	};
	xkb_compat    { include "complete"	};
	xkb_symbols   { include "pc+us(dvorak)+inet(evdev)+terminate(ctrl_alt_bksp)"	};
	xkb_geometry  { include "pc(pc105)"	};
};
```

--------------------------------

### Free libxkbcommon objects

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/quick-guide.md

Release allocated resources when they are no longer needed.

```c
    xkb_state_unref(state);
    xkb_keymap_unref(keymap);
    xkb_context_unref(ctx);
```

--------------------------------

### Draw XKB dependency graphs

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/introspection.md

Generate DOT format output for visualization, which can be converted to SVG or PDF using external tools.

```bash
# Specific file (absolute path)
introspection --include XKB_ROOT --dot FILE
# Specific file (relative path)
introspection --include XKB_ROOT --dot --type TYPE FILE

# Specific file (absolute path) and its transitive dependencies
introspection --include XKB_ROOT --dot --recursive FILE

# Keymap from RMLVO
xkbcli compile-keymap --kccgst --layout LAYOUT | introspection --include XKB_ROOT --dot

# XKB tree
introspection-query tree XKB_ROOT -- --dot --recursive
# XKB tree for a specific type
introspection-query tree XKB_ROOT --type TYPE -- --dot --recursive
```

--------------------------------

### Check xkb_state_mode support

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/message-registry.md

Use this function to verify if the linked libxkbcommon library supports a specific state mode.

```c
xkb_feature_supported(XKB_FEATURE_ENUM_STATE_MODE, flag)
```

--------------------------------

### Update Website Documentation

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/RELEASING.md

Commands to copy generated documentation and update the current version symlink.

```bash
cp -r <xkbommon>/build/doc/html doc/<MAJOR.MINOR.PATCH>
```

```bash
ln -nsrf doc/<MAJOR.MINOR.PATCH> doc/current
```

--------------------------------

### Define Key Code Mappings

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/rules-format.md

Maps models and layouts to specific keycode configurations using variables and wildcards.

```c
! $jollamodels = jollasbj
! $azerty = be fr
! $qwertz = al ch cz de hr hu ro si sk

! model       = keycodes
 $jollamodels = evdev+jolla(jolla)
  olpc        = evdev+olpc(olpc)
  *           = evdev

! layout      = keycodes
 $azerty      = +aliases(azerty)
 $qwertz      = +aliases(qwertz)
  *           = +aliases(qwerty)
```

--------------------------------

### Serialize keymap subset for X11 compatibility

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/faq.md

Configures and executes a lossy serialization of a keymap subset to maintain X11 compatibility.

```c
const struct xkb_keymap_serialize_config config = {
    .size = sizeof(config),
    /* X11 compatibility */
    .format = XKB_KEYMAP_FORMAT_TEXT_V1,
    /* X11 compatibility: 4 layouts (max supported by X11), indices 3-6 (0-indexed) */
    .layouts = 0x78
};

struct xkb_keymap_serialize_result result = { .size = sizeof(result) };

const xkb_error_code ret = xkb_keymap_serialize(keymap, &config, &result);
if (ret == XKB_SUCCESS) {
    // send result.serialized
    …
} else {
    // handle error
    …
}

free(result.serialized);
```

--------------------------------

### Define a key description

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Defining the key description for a specific keycode.

```xkb
key <AD01> { ... };
```

--------------------------------

### Define a custom layout variant for libxkbcommon 1.9+

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/custom-configuration.md

An explicit default section is not required for libxkbcommon versions 1.9 and newer.

```c
// No default section required

partial alphanumeric_keys
xkb_symbols "broccoli" {
    include "us(basic)"
    name[Group1] = "Broccoli";
    key <AD05> { [ b, B, U1F966 ]}; // U1F966 = 🥦 (Unicode keysym)
    include "level3(ralt_switch)"
};
```

--------------------------------

### Define Multiple Key Groups

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Configures multiple groups for a key using either shorthand or long-form syntax.

```c
name[Group1]= "US/ASCII";
name[Group2]= "Russian";
...
key <AD01> { [ q, Q ],
             [ Cyrillic_shorti, Cyrillic_SHORTI ] };
```

```c
key <AD01> {
    symbols[Group1]= [ q, Q ],
    symbols[Group2]= [ Cyrillic_shorti, Cyrillic_SHORTI ]
};
```

```c
key <AD01> { [], [], [ q, Q ] };
```

--------------------------------

### Define multiple symbols per level

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-text-format-v1-v2.md

Supports multiple key symbols and actions per level as an extension to the legacy XKB format.

```c
key <AD08> { [ {i, j}        , U0132         ] }; // IJ Dutch digraph
key <AC05> { [ {g, U0303}    , {G, U0303}    ] }; // G̃ Guarani letter
key <AB05> { [ {U0644, U0627}, {U0644, U0622}] }; // ⁧لا⁩ ⁧لآ⁩ Arabic Lam-Alef ligatures decomposed
key <AD01> { [ {c, U2019, h} , {C, U2019, h} ] }; // C’H Breton trigraph
```

--------------------------------

### Replace xmodmap -pm with xkbcli

Source: https://github.com/xkbcommon/libxkbcommon/blob/master/doc/faq.md

Use these commands to print modifier maps for different session types.

```bash
xkbcli dump-keymap | xkbcli compile-keymap --modmaps
```

```bash
xkbcli dump-keymap-wayland | xkbcli compile-keymap --modmaps
```

```bash
xkbcli dump-keymap-x11 | xkbcli compile-keymap --modmaps
```
Tokens:
Raw