libxkbcommon: Frequently Asked Question (FAQ)

libxkbcommon 1.9.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.

# 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 previous) 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 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:

// 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);
xkb_state::xkb_state_unref
XKB_EXPORT void xkb_state_unref(struct xkb_state *state)
Release a reference on a keybaord 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_update_mask for modifiers, to be used on the server side of serializatio...
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:1459
xkb_state
Opaque keyboard state object.
xkbcommon-names.h
Predefined names for common modifiers and LEDs.
xkb_mod_mask_t
uint32_t xkb_mod_mask_t
A mask of modifier indices.
Definition xkbcommon.h:225
xkb_mod_index_t
uint32_t xkb_mod_index_t
Index of a modifier.
Definition xkbcommon.h:223