XKB

What is XKB?

See: Introduction to XKB.

What does … mean?

See: terminology.

Keyboard layout

Where are the keyboard layouts defined?

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

Why do my keyboard shortcuts not work properly?

🚧 TODO: Setups with multiple layout and/or non-Latin keyboard layouts may have some issues.
🚧 TODO: #420

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

See this issue.

Why does my keyboard layout not work as expected?

There could be many reasons!

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.

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 customize my layout?

This project does not provide any keyboard layout database:

If you want to modify only your local keyboard configuration, see: User-configuration.
If you want to modify the standard keyboard layout database, please first try it locally (see our debugging tools) and then file an issue or a merge request at the xkeyboard-config project.

See also the keymap text format documentation for the syntax.

How do I test my custom layout without installing it?

Use our debugging tools.

How do I swap some keys?

🚧 TODO

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

Consider the following use cases:

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.
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-*:

Wayland session: xkbcli dump-keymap-wayland | xkbcli compile-keymap --modmaps
X11 session: 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 User-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 -

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 User-configuration, which enables making custom layouts discoverable by keyboard configuration GUI.

API

Modifiers

How to get the virtual to real modifiers mappings?

The virtual modifiers mappings to real modifiers is an implementation detail. However, some applications may require it in order to interface with legacy code.

libxkbcommon ≥ 1.10

Use the dedicated function xkb_keymap::xkb_keymap_mod_get_mask().

libxkbcommon ≤ 1.9

Use the following snippet:

// Find the real modifier mapping of the virtual modifier `LevelThree`
#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);

Table of Contents

XKB