libxkbcommon  1.10.0
LibraryimplementingtheXKBspecificationforparsingkeyboarddescriptionsandhandlingkeyboardstate
Frequently Asked Question (FAQ)

{html:2}

XKB

What is XKB?

See: ./introduction-to-xkb.md "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?

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.md "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.md "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.md "debugging tools" to ensure that it is specific to the application.
Your keyboard layout uses features not supported by libxkbcommon
See: ./compatibility.md "compatibility"
None of the previous
If none of the previous is conclusive, then this may an issue with libxkbcommon. Please use our ./debugging.md "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:

See also the ./keymap-format-text-v1.md "keymap text format" documentation for the syntax.

How do I test my custom layout without installing it?

Use our ./debugging.md "debugging tools".

How do I swap some keys?

🚧 TODO

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

1 xkbcli dump-keymap-wayland | xkbcli compile-keymap --modmaps
X11 session

1 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:

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

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

Wayland session

1 xkbcli dump-keymap-wayland
X11 session

1 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:

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