libxkbcommon  1.9.2
LibraryimplementingtheXKBspecificationforparsingkeyboarddescriptionsandhandlingkeyboardstate
Frequently Asked Question (FAQ)

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 swap some keys?

🚧 TODO

API

Modifiers

How to get the virtual to real modifiers mappings?

The virtual modifiers mappings to real modifiers is an implementation detail that is not exposed directly. However, some applications may require it in order to interface with legacy code. These may adapt 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); ```