libxkbcommon: Frequently Asked Question (FAQ)

libxkbcommon 1.13.2 Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state

Loading...
Searching...
No Matches
Frequently Asked Question (FAQ)

# XKB

## What is XKB?

See: Introduction to XKB.

## What does … mean?

See: terminology.

## What are the differences with the Xorg/X11 implementations?

Features
  See XKB Compatibility.
Tools
  See Legacy X tools replacement.

# Keyboard layouts

## Is there a quick guide?

Yes, see the custom configuration.

## Where are the standard keyboard layouts designed?
How to report an issue or propose a patch?

The xkbcommon project does not provide keyboard layouts. Standard keyboard layouts are provided by the xkeyboard-config project. See contributing to xkeyboard-config for further information.

## Where are the system keyboard layouts located?

They are usually located at /usr/share/xkeyboard-config-<VERSION>, or /usr/share/X11/xkb on older setups.

Note
  Do not modify system files! See How do I customize my layout? for further instructions.

## How do I customize my layout?

This project does not provide any keyboard layout database:

- If you want to modify only your user keyboard configuration, see: custom configuration.
- If you want to modify the system-wide keyboard configuration, follow the custom configuration but replace $XDG_CONFIG_HOME with <sysconfdir> (usually /etc) in the file locations.
- If you want to modify the standard keyboard layout database, please first try it locally (see our debugging tools) and then file a merge request at the xkeyboard-config project.

See also the keymap text format documentation for the syntax and the compatibility page for the supported features.

## How do I test my custom layout without installing it?

Use our debugging tools.

## How can I create a package for my layout?

See Packaging keyboard layouts.

## Why does my key combination to switch between layouts not work?

There are some issues with modifier-only shortcuts: see this bug report.

This can be fixed by using the new parameter `lockOnRelease` in LockGroup(), available since libxkbcommon 1.11. This will be done at some point in xkeyboard-config.

xkb_compatibility {
interpret ISO_Next_Group {
useModMapMods= level1;
virtualModifier= AltGr;
- action= LockGroup(group=+1);
+ action= LockGroup(group=+1, lockOnRelease);
};
};

## Why do my keyboard shortcuts not work properly?

Users have different expectations when it comes to keyboard shortcuts. However, the reference use case is usually a single Latin keyboard layout, with fallbacks for other configurations. These fallbacks may not match users’ expectations nor even be consistent across applications. See this issue.

## Why does my keyboard layout not work as expected?

There could be many reasons!

Wrong keyboard model
  Nowadays most keyboards follow standards, so prefer using one of the “generic” keyboard models in the XKB configuration to avoid vendor-specific mappings.
There is an issue with your keyboard layout database

  libxkbcommon may not be able to load your configuration due to an issue (file not found, syntax error, unsupported keysym, etc.). Please use our debugging tools to get further information.

  Note that the xkbcommon project does not provide keyboard layouts. See the xkeyboard-config project for further information.

Diacritics/accents do not work

  This is most probably an issue with your Compose configuration. If you customized it, do not forget to restart your session before trying it.

  Please use our debugging tools with the option --enable-compose to get further information.

Multiple groups per key do not work
  See How do I define multiple groups per key?.
The application you use does not handle the keyboard properly
  Please use our debugging tools to ensure that it is specific to the application.
Your keyboard layout uses features not supported by libxkbcommon
  See: compatibility
None of the previous
  If none of the previous is conclusive, then this may an issue with libxkbcommon. Please use our debugging tools to provide the maximum information (setup, log, expected/got results) and file a bug report!

## How do I swap some keys?

🚧 TODO

## How do I define multiple groups per key?

Since version 1.8 the RMLVO API does not support parsing multiple groups per key anymore, because it may break the expectation of most desktop environments and tools that the number of groups should be equal to the number of configured layouts. See #262 and #518 for further details.

The following explain how to migrate for some common use cases:

Multiple layouts

  If you define multiple layouts in a single xkb_symbols section, you should instead split them into individual sections and update your keyboard settings to use each such layout.

  E.g. if you have a single layout variant1_variant2 defined as:

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

  then you should split it into:

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

  See also the instructions to make the layouts discoverable for easy configuration in your keyboard settings app.

Option for multiple layouts

  If you define an option that affect multiple groups at once in a single xkb_symbols section, you should split that section and update the corresponding rules for each layout index.

  E.g. if one has the following group switcher on CapsLock key:

  // File: ~/.config/xkb/symbols/group
  partial xkb_symbols "caps_pairs" {
  replace key <CAPS> {
  repeat=No,
  symbols[Group1] = [ISO_Group_Lock, ISO_Group_Lock],
  symbols[Group2] = [ISO_Group_Lock, ISO_Group_Lock],
  symbols[Group3] = [ISO_Group_Lock, ISO_Group_Lock],
  symbols[Group4] = [ISO_Group_Lock, ISO_Group_Lock],
  actions[Group1] = [LockGroup(group=2), LockGroup(group=3) ],
  actions[Group2] = [LockGroup(group=1), LockGroup(group=4) ],
  actions[Group3] = [LockGroup(group=4), LockGroup(group=1) ],
  actions[Group4] = [LockGroup(group=3), LockGroup(group=2) ]
  };
  };

  and the corresponding custom rules:

  // File: ~/.config/xkb/rules/evdev
  include %S/evdev
  ! option = symbols
  grp:caps_pairs = +group(caps_pairs)

  then it should be migrated to:

  // File: ~/.config/xkb/symbols/group
  partial xkb_symbols "caps_pairs_1" {
  replace key <CAPS> {
  repeat=No,
  symbols[Group1] = [ISO_Group_Lock, ISO_Group_Lock],
  actions[Group1] = [LockGroup(group=2), LockGroup(group=3) ]
  };
  };
  partial xkb_symbols "caps_pairs_2" {
  replace key <CAPS> {
  symbols[Group1] = [ISO_Group_Lock, ISO_Group_Lock],
  actions[Group1] = [LockGroup(group=1), LockGroup(group=4) ]
  };
  };
  partial xkb_symbols "caps_pairs_3" {
  replace key <CAPS> {
  symbols[Group1] = [ISO_Group_Lock, ISO_Group_Lock],
  actions[Group1] = [LockGroup(group=4), LockGroup(group=1) ]
  };
  };
  partial xkb_symbols "caps_pairs_4" {
  replace key <CAPS> {
  symbols[Group1] = [ISO_Group_Lock, ISO_Group_Lock],
  actions[Group1] = [LockGroup(group=3), LockGroup(group=2) ]
  };
  };

  with the corresponding custom rules:

  // File: ~/.config/xkb/rules/evdev
  include %S/evdev
  ! layout[1] option = symbols
  * grp:caps_pairs = +group(caps_pairs_1):1
  ! layout[2] option = symbols
  * grp:caps_pairs = +group(caps_pairs_2):2
  ! layout[3] option = symbols
  * grp:caps_pairs = +group(caps_pairs_3):3
  ! layout[4] option = symbols
  * grp:caps_pairs = +group(caps_pairs_4):4

## How do I break a latch before triggering another latch or lock?

Consider the following use cases:

1. If Caps_Lock is on the second level of some key, and Shift is latched, pressing the key locks Caps while also breaking the Shift latch, ensuring that the next character is properly uppercase.
2. On the German E1 layout, ISO_Level5_Latch is on the third level of <AC04>. So if a level 3 latch (typically on <RALT>) is used to access it, the level 5 must break the previous level 3 latch, else both latches would be active: the effective level would be 7 instead of the intended 5.

Both uses cases can be implemented using the following features:

- explicit action;
- multiple actions per level;
- VoidAction(): to break latches.

Patch that fixes the first use case:

--- old
+++ new
key <LFSH> {
[ISO_Level2_Latch, Caps_Lock],
+ [LatchMods(modifiers=Shift,latchToLock,clearLocks),
+ {VoidAction(), LockMods(modifiers=Lock)}],
type=\"ALPHABETIC\"
};

# Legacy X tools replacement

## xmodmap

xmodmap -pm

  There is no strict equivalent. Since 1.10 xkbcli compile-keymap has the option --modmaps to print the modifiers maps from a keymap, but it does not print keysyms. In order to get the output for the current keymap, use it with xkbcli dump-keymap-*:

  Automatic session type detection

    xkbcli dump-keymap | xkbcli compile-keymap --modmaps
  Wayland session

    xkbcli dump-keymap-wayland | xkbcli compile-keymap --modmaps
  X11 session / XWayland

    xkbcli dump-keymap-x11 | xkbcli compile-keymap --modmaps
xmodmap -e "…"
xmodmap /path/to/file
  No equivalent: xkbcli does not modify the display server keymap.

## setxkbmap

setxkbmap -print -layout …

  Since 1.9 one can use the --kccgst option:

  xkbcli compile-keymap --kccgst --layout …
setxkbmap -query

  No equivalent: xkbcli only query raw keymaps and has no access to the original RMLVO settings.

setxkbmap -layout …

  No equivalent: xkbcli does not modify the display server keymap. One must use the tools specific to each display server in order order to achieve it.

  If you use a custom layout, please have a look at Custom configuration, which enables making custom layouts discoverable by keyboard configuration GUI.

## xkbcomp

xkbcomp -xkb /path/to/keymap/file -

  xkbcli compile-keymap --keymap /path/to/keymap/file
xkbcomp -xkb $DISPLAY -

  Automatic session type detection

    xkbcli dump-keymap
  Wayland session

    xkbcli dump-keymap-wayland
  X11 session

    xkbcli dump-keymap-x11
xkbcomp - $DISPLAY
xkbcomp /path/to/keymap/file $DISPLAY

  No equivalent: xkbcli does not modify the display server keymap. One must use the tools specific to each display server in order order to achieve it. Please have a look at Custom configuration, which enables making custom layouts discoverable by keyboard configuration GUI.

## xev

xev -event keyboard
  Automatic session type detection

    xkbcli interactive
  Wayland session

    xkbcli interactive-wayland
  X11 session

    xkbcli interactive-x11

# API

## Modifiers

### How to get the virtual modifier encoding?

The virtual modifiers encoding, (also: mappings to real modifiers in X11 jargon) is an implementation detail. However, some applications may require it in order to interface with legacy code.

#### libxkbcommon ≥ 1.10

Use the dedicated functions xkb_keymap::xkb_keymap_mod_get_mask() (since 1.10) and xkb_keymap::xkb_keymap_mod_get_mask2() (since 1.11).

#### libxkbcommon ≤ 1.9

Use the following snippet:

// 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);
xkb_state::xkb_state_unref
XKB_EXPORT void xkb_state_unref(struct xkb_state *state)
Release a reference on a keyboard state object, and possibly free it.
xkb_state::xkb_state_new
XKB_EXPORT struct xkb_state * xkb_state_new(struct xkb_keymap *keymap)
Create a new keyboard state object.
xkb_state::xkb_state_serialize_mods
XKB_EXPORT xkb_mod_mask_t xkb_state_serialize_mods(struct xkb_state *state, enum xkb_state_component components)
The counterpart to xkb_state::xkb_state_update_mask() for modifiers, to be used on the server side of...
xkb_state::xkb_state_update_mask
XKB_EXPORT enum xkb_state_component xkb_state_update_mask(struct xkb_state *state, xkb_mod_mask_t depressed_mods, xkb_mod_mask_t latched_mods, xkb_mod_mask_t locked_mods, xkb_layout_index_t depressed_layout, xkb_layout_index_t latched_layout, xkb_layout_index_t locked_layout)
Update a keyboard state from a set of explicit masks.
XKB_STATE_MODS_EFFECTIVE
@ XKB_STATE_MODS_EFFECTIVE
Effective modifiers, i.e.
Definition xkbcommon.h:1894
XKB_VMOD_NAME_LEVEL3
#define XKB_VMOD_NAME_LEVEL3
Definition xkbcommon-names.h:60
xkb_state
Opaque keyboard state object.
xkbcommon-names.h
Predefined names for common modifiers and LEDs.
xkbcommon.h
Main libxkbcommon API.
xkb_mod_mask_t
uint32_t xkb_mod_mask_t
A mask of modifier indices.
Definition xkbcommon.h:226
xkb_mod_index_t
uint32_t xkb_mod_index_t
Index of a modifier.
Definition xkbcommon.h:224

### How to get the keys that trigger modifiers?

There is no dedicated API, since the use cases are too diverse or niche. Nevertheless, the following snippet provide a minimal example to achieve it.

#include <xkbcommon/xkbcommon.h>
static ssize_t
xkb_keymap_mod_get_codes(struct xkb_keymap *keymap, xkb_mod_index_t mod,
xkb_keycode_t *codes_out, size_t codes_size)
{
if (mod >= xkb_keymap_num_mods(keymap))
return -1;
ssize_t idx = 0;
for (xkb_keycode_t k = xkb_keymap_min_keycode(keymap);
k <= xkb_keymap_max_keycode(keymap) && idx >= 0; k++) {
/*
* We only test the first level of the first group.
*
* Since there is currently no way to reset the state, use a new one to
* avoid side effects (latches, etc.)
*/
struct xkb_state * const state = xkb_state_new(keymap);
assert(state);
static const enum xkb_key_direction directions[] = {
XKB_KEY_DOWN,
XKB_KEY_UP
};
for (size_t d = 0; d < ARRAY_SIZE(directions); d++) {
if (xkb_state_update_key(state, k, directions[d]) &&
xkb_state_mod_index_is_active(state, mod,
XKB_STATE_MODS_EFFECTIVE)) {
if ((size_t) idx < codes_size) {
assert(idx < (ssize_t) (SIZE_MAX / 2));
codes_out[idx++] = k;
} else {
idx = -2;
}
break;
}
}
xkb_state_unref(state);
}
return idx;
}

## Keys

### How to check if a keymap defines/binds a keycode?

Check if a keymaps defines a keycode

  xkb_keymap::xkb_keymap_key_get_name() returns NULL if the keycode is not defined in the corresponding keymap:

  if (xkb_keymap_key_get_name(keymap, keycode) != NULL)
  // use existing key ...
Check if a keymaps binds a keycode

  xkb_keymap::xkb_keymap_num_layouts_for_key() returns 0 if the keycode is either not defined or unbound:

  if (xkb_keymap_num_layouts_for_key(keymap, keycode))
  // use bound key ...