Data Structures
struct	xkb_state_components_update

struct	xkb_layout_policy_update

struct	xkb_state_update

struct	xkb_machine

struct	xkb_state

struct	xkb_event

struct	xkb_events

struct	xkb_machine_builder

Enumerations
enum	xkb_event_type { XKB_EVENT_TYPE_KEY_DOWN = 1 , XKB_EVENT_TYPE_KEY_REPEATED , XKB_EVENT_TYPE_KEY_UP , XKB_EVENT_TYPE_COMPONENTS_CHANGE }

enum	xkb_state_component { XKB_STATE_MODS_DEPRESSED = (1 << 0) , XKB_STATE_MODS_LATCHED = (1 << 1) , XKB_STATE_MODS_LOCKED = (1 << 2) , XKB_STATE_MODS_EFFECTIVE = (1 << 3) , XKB_STATE_LAYOUT_DEPRESSED = (1 << 4) , XKB_STATE_LAYOUT_LATCHED = (1 << 5) , XKB_STATE_LAYOUT_LOCKED = (1 << 6) , XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7) , XKB_STATE_LEDS = (1 << 8) , XKB_STATE_CONTROLS = (1 << 9) }

enum	xkb_keyboard_control_flags { XKB_KEYBOARD_CONTROL_NO_FLAGS = 0 , XKB_KEYBOARD_CONTROL_A11Y_STICKY_KEYS = (1 << 0) , XKB_KEYBOARD_CONTROL_OVERLAY1 = (1 << 1) , XKB_KEYBOARD_CONTROL_OVERLAY2 = (1 << 2) , XKB_KEYBOARD_CONTROL_OVERLAY3 = (1 << 3) , XKB_KEYBOARD_CONTROL_OVERLAY4 = (1 << 4) , XKB_KEYBOARD_CONTROL_OVERLAY5 = (1 << 5) , XKB_KEYBOARD_CONTROL_OVERLAY6 = (1 << 6) , XKB_KEYBOARD_CONTROL_OVERLAY7 = (1 << 7) , XKB_KEYBOARD_CONTROL_OVERLAY8 = (1 << 8) }

enum	xkb_events_flags { XKB_EVENTS_NO_FLAGS = 0 }

enum	xkb_machine_builder_flags { XKB_MACHINE_BUILDER_NO_FLAGS = 0 }

enum	xkb_a11y_flags { XKB_A11Y_NO_FLAGS = 0 , XKB_A11Y_STICKY_KEYS_NO_SIMULTANEOUS_KEYS = (1 << 0) , XKB_A11Y_STICKY_KEYS_LATCH_TO_LOCK = (1 << 1) , XKB_A11Y_LATCH_SIMULTANEOUS_KEYS = (1 << 2) }

enum	xkb_key_direction { XKB_KEY_UP , XKB_KEY_DOWN , XKB_KEY_REPEATED }

enum	xkb_layout_out_of_range_policy { XKB_LAYOUT_OUT_OF_RANGE_WRAP = 0 , XKB_LAYOUT_OUT_OF_RANGE_CLAMP , XKB_LAYOUT_OUT_OF_RANGE_REDIRECT }

enum	xkb_state_mode { XKB_STATE_MODE_CLIENT = 0 , XKB_STATE_MODE_SERVER_QUERY = 1 , XKB_STATE_MODE_SERVER = 2 }

enum	xkb_state_match { XKB_STATE_MATCH_ANY = (1 << 0) , XKB_STATE_MATCH_ALL = (1 << 1) , XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16) }

enum	xkb_consumed_mode { XKB_CONSUMED_MODE_XKB , XKB_CONSUMED_MODE_GTK }

Functions
XKB_EXPORT enum xkb_event_type	xkb_event::xkb_event_get_type (const struct xkb_event *event)

XKB_EXPORT xkb_keycode_t	xkb_event::xkb_event_get_keycode (const struct xkb_event *event)

XKB_EXPORT enum xkb_state_component	xkb_event::xkb_event_get_changed_components (const struct xkb_event *event)

XKB_EXPORT enum xkb_keyboard_control_flags	xkb_event::xkb_event_serialize_enabled_controls (const struct xkb_event *event, enum xkb_state_component components)

XKB_EXPORT xkb_mod_mask_t	xkb_event::xkb_event_serialize_mods (const struct xkb_event *event, enum xkb_state_component components)

XKB_EXPORT xkb_layout_index_t	xkb_event::xkb_event_serialize_layout (const struct xkb_event *event, enum xkb_state_component components)

XKB_EXPORT struct xkb_events *	xkb_events::xkb_events_new_batch (struct xkb_context *context, enum xkb_events_flags flags)

XKB_EXPORT void	xkb_events::xkb_events_destroy (struct xkb_events *events)

XKB_EXPORT const struct xkb_event *	xkb_events::xkb_events_next (struct xkb_events *events)

XKB_EXPORT struct xkb_machine_builder *	xkb_machine_builder::xkb_machine_builder_new (struct xkb_keymap *keymap, enum xkb_machine_builder_flags flags)

XKB_EXPORT void	xkb_machine_builder::xkb_machine_builder_destroy (struct xkb_machine_builder *builder)

XKB_EXPORT struct xkb_keymap *	xkb_machine_builder::xkb_machine_builder_get_keymap (const struct xkb_machine_builder *builder)

XKB_EXPORT enum xkb_error_code	xkb_machine_builder::xkb_machine_builder_update_a11y_flags (struct xkb_machine_builder *builder, enum xkb_a11y_flags affect, enum xkb_a11y_flags flags)

XKB_EXPORT enum xkb_error_code	xkb_machine_builder::xkb_machine_builder_remap_mods (struct xkb_machine_builder *builder, xkb_mod_mask_t source, xkb_mod_mask_t target)

XKB_EXPORT enum xkb_error_code	xkb_machine_builder::xkb_machine_builder_update_shortcut_mods (struct xkb_machine_builder *builder, xkb_mod_mask_t affect, xkb_mod_mask_t mask)

XKB_EXPORT enum xkb_error_code	xkb_machine_builder::xkb_machine_builder_remap_shortcut_layout (struct xkb_machine_builder *builder, xkb_layout_index_t source, xkb_layout_index_t target)

XKB_EXPORT struct xkb_machine *	xkb_machine::xkb_machine_new (const struct xkb_machine_builder *builder)

XKB_EXPORT struct xkb_machine *	xkb_machine::xkb_machine_ref (struct xkb_machine *machine)

XKB_EXPORT void	xkb_machine::xkb_machine_unref (struct xkb_machine *machine)

XKB_EXPORT struct xkb_keymap *	xkb_machine::xkb_machine_get_keymap (const struct xkb_machine *machine)

XKB_EXPORT enum xkb_error_code	xkb_machine::xkb_machine_process_key (struct xkb_machine machine, xkb_keycode_t key, enum xkb_key_direction direction, struct xkb_events events)

XKB_EXPORT enum xkb_error_code	xkb_machine::xkb_machine_process_synthetic (struct xkb_machine machine, const struct xkb_state_update update, struct xkb_events *events)

XKB_EXPORT struct xkb_state *	xkb_state::xkb_state_new_with_mode (struct xkb_keymap *keymap, enum xkb_state_mode mode)

XKB_EXPORT struct xkb_state *	xkb_state::xkb_state_new (struct xkb_keymap *keymap)

XKB_EXPORT struct xkb_state *	xkb_state::xkb_state_ref (struct xkb_state *state)

XKB_EXPORT void	xkb_state::xkb_state_unref (struct xkb_state *state)

XKB_EXPORT struct xkb_keymap *	xkb_state::xkb_state_get_keymap (struct xkb_state *state)

XKB_EXPORT enum xkb_state_component	xkb_state::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)

XKB_EXPORT enum xkb_state_component	xkb_state::xkb_state_update_event (struct xkb_state state, const struct xkb_event event)

XKB_EXPORT enum xkb_state_component	xkb_state::xkb_state_update_key (struct xkb_state *state, xkb_keycode_t key, enum xkb_key_direction direction)

XKB_EXPORT enum xkb_error_code	xkb_state::xkb_state_update_synthetic (struct xkb_state state, const struct xkb_state_update update, enum xkb_state_component *changed)

XKB_EXPORT enum xkb_state_component	xkb_state::xkb_state_update_latched_locked (struct xkb_state *state, xkb_mod_mask_t affect_latched_mods, xkb_mod_mask_t latched_mods, bool affect_latched_layout, int32_t latched_layout, xkb_mod_mask_t affect_locked_mods, xkb_mod_mask_t locked_mods, bool affect_locked_layout, int32_t locked_layout)

XKB_EXPORT int	xkb_state::xkb_state_key_get_syms (struct xkb_state state, xkb_keycode_t key, const xkb_keysym_t *syms_out)

XKB_EXPORT int	xkb_state::xkb_state_key_get_utf8 (struct xkb_state state, xkb_keycode_t key, char buffer, size_t size)

XKB_EXPORT uint32_t	xkb_state::xkb_state_key_get_utf32 (struct xkb_state *state, xkb_keycode_t key)

XKB_EXPORT xkb_keysym_t	xkb_state::xkb_state_key_get_one_sym (struct xkb_state *state, xkb_keycode_t key)

XKB_EXPORT xkb_layout_index_t	xkb_state::xkb_state_key_get_layout (struct xkb_state *state, xkb_keycode_t key)

XKB_EXPORT xkb_level_index_t	xkb_state::xkb_state_key_get_level (struct xkb_state *state, xkb_keycode_t key, xkb_layout_index_t layout)

XKB_EXPORT enum xkb_keyboard_control_flags	xkb_state::xkb_state_serialize_enabled_controls (const struct xkb_state *state, enum xkb_state_component components)

XKB_EXPORT xkb_mod_mask_t	xkb_state::xkb_state_serialize_mods (struct xkb_state *state, enum xkb_state_component components)

XKB_EXPORT xkb_layout_index_t	xkb_state::xkb_state_serialize_layout (struct xkb_state *state, enum xkb_state_component components)

XKB_EXPORT int	xkb_state::xkb_state_mod_name_is_active (struct xkb_state state, const char name, enum xkb_state_component type)

XKB_EXPORT int	xkb_state::xkb_state_mod_names_are_active (struct xkb_state *state, enum xkb_state_component type, enum xkb_state_match match,...)

XKB_EXPORT int	xkb_state::xkb_state_mod_index_is_active (struct xkb_state *state, xkb_mod_index_t idx, enum xkb_state_component type)

XKB_EXPORT int	xkb_state::xkb_state_mod_indices_are_active (struct xkb_state *state, enum xkb_state_component type, enum xkb_state_match match,...)

XKB_EXPORT xkb_mod_mask_t	xkb_state::xkb_state_key_get_consumed_mods2 (struct xkb_state *state, xkb_keycode_t key, enum xkb_consumed_mode mode)

XKB_EXPORT xkb_mod_mask_t	xkb_state::xkb_state_key_get_consumed_mods (struct xkb_state *state, xkb_keycode_t key)

XKB_EXPORT int	xkb_state::xkb_state_mod_index_is_consumed2 (struct xkb_state *state, xkb_keycode_t key, xkb_mod_index_t idx, enum xkb_consumed_mode mode)

XKB_EXPORT int	xkb_state::xkb_state_mod_index_is_consumed (struct xkb_state *state, xkb_keycode_t key, xkb_mod_index_t idx)

XKB_EXPORT xkb_mod_mask_t	xkb_state::xkb_state_mod_mask_remove_consumed (struct xkb_state *state, xkb_keycode_t key, xkb_mod_mask_t mask)

XKB_EXPORT int	xkb_state::xkb_state_layout_name_is_active (struct xkb_state state, const char name, enum xkb_state_component type)

XKB_EXPORT int	xkb_state::xkb_state_layout_index_is_active (struct xkb_state *state, xkb_layout_index_t idx, enum xkb_state_component type)

XKB_EXPORT int	xkb_state::xkb_state_led_name_is_active (struct xkb_state state, const char name)

XKB_EXPORT int	xkb_state::xkb_state_led_index_is_active (struct xkb_state *state, xkb_led_index_t idx)

Detailed Description

Creating, destroying and manipulating keyboard state objects.

Server State and Client State

There are two distinct actors in most window-system architectures:

Server

For example: a Wayland compositor, an X11 server or an evdev listener.

Servers maintain the XKB state for a device according to input events from the device, such as key presses and releases, and out-of-band events from the user, like UI layout switchers.

Client

For example: a Wayland client or an X11 client.

Clients do not listen to input from the device; instead, whenever the server state changes, the server serializes the state and notifies the clients that the state has changed; the clients then update the state from the serialization.

There are two corresponding APIs:

xkb_machine: the server API

This is the recommended API for server applications. It enables the full feature set that libxkbcommon supports.

xkb_machine is a Mealy machine: it is a finite-state machine that takes a stream of raw key events – a pair (keycode, direction) – as input, and produces a stream of atomic XKB events as output.

The observable state of the machine is exposed via a companion xkb_state object:

Create it with xkb_state::xkb_state_new_with_mode() using XKB_STATE_MODE_SERVER_QUERY.
Update it with xkb_state::xkb_state_update_event().
Query it (keysyms, modifiers, layout, LEDs) via the xkb_state query API.

Note that the xkb_machine API supports events other than state components changes, such as key press/release events, so that it enables handling most of the XKB key actions.

See the example for a Wayland server in the quick guide.

Since: 1.14.0

xkb_state: the client API (and legacy server API)

This is the API for client applications and the legacy API for server applications.

Client applications: Create the state object with xkb_state::xkb_state_new_with_mode() using XKB_STATE_MODE_CLIENT, then update it via xkb_state::xkb_state_update_mask() from server serializations.
Server applications not using xkb_machine: Create the state object with xkb_state::xkb_state_new_with_mode() using XKB_STATE_MODE_SERVER, or with the legacy xkb_state::xkb_state_new() constructor, then update it via xkb_state::xkb_state_update_key() for key events and xkb_state::xkb_state_update_synthetic() for out-of-band inputs such as layout switchers.

Warning: Some entry points in the xkb_state API are only meant for servers and some are only meant for clients. Thus it is recommended to use xkb_state::xkb_state_new_with_mode() because it enforces correct usage at runtime and logs misuse as XKB_ERROR_UNEXPECTED_STATE_MODE. Using xkb_state::xkb_state_new() does not enforce this: mixing entry points may lead to incorrect state.

Note: Since version 1.14.0, server applications should use the xkb_machine API, which supports more features.

See the examples for clients in the quick guide.

Consumed Modifiers

Some functions, like xkb_state::xkb_state_key_get_syms(), look at the state of the modifiers in the keymap and derive from it the correct shift level to use for the key. For example, in a US layout, pressing the key labeled <A> while the Shift modifier is active, generates the keysym A. In this case, the Shift modifier is said to be consumed. However, the Num Lock modifier does not affect this translation at all, even if it is active, so it is not consumed by this translation.

It may be desirable for some application to not reuse consumed modifiers for further processing, e.g. for hotkeys or keyboard shortcuts. To understand why, consider some requirements from a standard shortcut mechanism, and how they are implemented:

The shortcut’s modifiers must match exactly to the state. For example, it is possible to bind separate actions to <Alt><Tab> and to <Alt><Shift><Tab>. Further, if only <Alt><Tab> is bound to an action, pressing <Alt><Shift><Tab> should not trigger the shortcut. Effectively, this means that the modifiers are compared using the equality operator (==).
Only relevant modifiers are considered for the matching. For example, Caps Lock and Num Lock should not generally affect the matching, e.g. when matching <Alt><Tab> against the state, it does not matter whether Num Lock is active or not. These relevant, or significant, modifiers usually include Alt, Control, Shift, Super and similar. Effectively, this means that non-significant modifiers are masked out, before doing the comparison as described above.
The matching must be independent of the layout/keymap. For example, the <Plus> (+) symbol is found on the first level on some layouts, but requires holding Shift on others. If you simply bind the action to the <Plus> keysym, it would work for the unshifted kind, but not for the others, because the match against Shift would fail. If you bind the action to <Shift><Plus>, only the shifted kind would work. So what is needed is to recognize that Shift is used up in the translation of the keysym itself, and therefore should not be included in the matching. Effectively, this means that consumed modifiers (Shift in this example) are masked out as well, before doing the comparison.

In summary, this is approximately how the matching would be performed:

(keysym == shortcut_keysym) &&

((state_mods & ~consumed_mods & significant_mods) == shortcut_mods)

state_mods are the modifiers reported by xkb_state::xkb_state_mod_index_is_active() and similar functions. consumed_mods are the modifiers reported by xkb_state::xkb_state_mod_index_is_consumed() and similar functions. significant_mods are decided upon by the application/toolkit/user; it is up to them to decide whether these are configurable or hard-coded.

Enumeration Type Documentation

◆ xkb_event_type

enum xkb_event_type

Denotes the type of a state event.

Since: 1.14.0

Enumerator
XKB_EVENT_TYPE_KEY_DOWN	Key down event Since 1.14.0
XKB_EVENT_TYPE_KEY_REPEATED	Key repeated event Since 1.14.0
XKB_EVENT_TYPE_KEY_UP	Key up event Since 1.14.0
XKB_EVENT_TYPE_COMPONENTS_CHANGE	Components change event Since 1.14.0

◆ xkb_state_component

enum xkb_state_component

Component types for state objects, which belong to the following categories:

This enum is bitmaskable, e.g. (XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED) is valid to exclude locked modifiers.

In XKB, the DEPRESSED components are also known as base.

Enumerator
XKB_STATE_MODS_DEPRESSED	Depressed modifiers, i.e. a key is physically holding them.
XKB_STATE_MODS_LATCHED	Latched modifiers, i.e. will be unset after the next non-modifier key press.
XKB_STATE_MODS_LOCKED	Locked modifiers, i.e. will be unset after the key provoking the lock has been pressed again.
XKB_STATE_MODS_EFFECTIVE	Effective modifiers, i.e. currently active and affect key processing (derived from the other state components). Use this unless you explicitly care how the state came about.
XKB_STATE_LAYOUT_DEPRESSED	Depressed layout, i.e. a key is physically holding it.
XKB_STATE_LAYOUT_LATCHED	Latched layout, i.e. will be unset after the next non-modifier key press.
XKB_STATE_LAYOUT_LOCKED	Locked layout, i.e. will be unset after the key provoking the lock has been pressed again.
XKB_STATE_LAYOUT_EFFECTIVE	Effective layout, i.e. currently active and affects key processing (derived from the other state components). Use this unless you explicitly care how the state came about.
XKB_STATE_LEDS	LEDs (derived from the other state components).
XKB_STATE_CONTROLS	Effective keyboard controls. Since 1.14.0

◆ xkb_keyboard_control_flags

enum xkb_keyboard_control_flags

Boolean global keyboard controls, which affect the way libxkbcommon handles the keyboard as a whole.

This enumeration is bit-maskable.

Since: 1.14.0

Enumerator
XKB_KEYBOARD_CONTROL_NO_FLAGS	Do not apply any control. Since 1.14.0
XKB_KEYBOARD_CONTROL_A11Y_STICKY_KEYS	Sticky keys is an accessibility feature primarily aimed at helping people that find it difficult or impossible to press two keys at once. The `XKB_KEYBOARD_CONTROL_A11Y_STICKY_KEYS` control makes it easier for them to type by changing the behavior of the modifier and group switch keys. When sticky keys are enabled, set modifiers/group switch are transformed into their corresponding latch version: e.g. the user can first press a modifier, release it, then press another key. See also `XKB_A11Y_STICKY_KEYS_LATCH_TO_LOCK` Since 1.14.0
XKB_KEYBOARD_CONTROL_OVERLAY1	Enable the keyboard overlay 1. Since 1.14.0
XKB_KEYBOARD_CONTROL_OVERLAY2	Enable the keyboard overlay 2. Since 1.14.0
XKB_KEYBOARD_CONTROL_OVERLAY3	Enable the keyboard overlay 3. Since 1.14.0
XKB_KEYBOARD_CONTROL_OVERLAY4	Enable the keyboard overlay 4. Since 1.14.0
XKB_KEYBOARD_CONTROL_OVERLAY5	Enable the keyboard overlay 5. Since 1.14.0
XKB_KEYBOARD_CONTROL_OVERLAY6	Enable the keyboard overlay 6. Since 1.14.0
XKB_KEYBOARD_CONTROL_OVERLAY7	Enable the keyboard overlay 7. Since 1.14.0
XKB_KEYBOARD_CONTROL_OVERLAY8	Enable the keyboard overlay 8. Since 1.14.0

◆ xkb_events_flags

enum xkb_events_flags

Flags for xkb_events::xkb_events_new_batch().

Since: 1.14.0

Enumerator

XKB_EVENTS_NO_FLAGS

Do not apply any flags.

Since: 1.14.0

◆ xkb_machine_builder_flags

enum xkb_machine_builder_flags

Flags for xkb_machine_builder::xkb_machine_builder_new().

Since: 1.14.0

Enumerator

XKB_MACHINE_BUILDER_NO_FLAGS

Do not apply any flags.

Since: 1.14.0

◆ xkb_a11y_flags

enum xkb_a11y_flags

Flags for xkb_machine_builder::xkb_machine_builder_update_a11y_flags().

These flags configure the accessibility (a11y) features.

Since: 1.14.0

Enumerator
XKB_A11Y_NO_FLAGS	Do not apply any flags. Since 1.14.0
XKB_A11Y_STICKY_KEYS_NO_SIMULTANEOUS_KEYS	If both `XKB_A11Y_STICKY_KEYS_NO_SIMULTANEOUS_KEYS` and `XKB_KEYBOARD_CONTROL_A11Y_STICKY_KEYS` are activated, they enable users to deactivate sticky keys whenever two keys or more are pressed simultaneously. See also `XKB_KEYBOARD_CONTROL_A11Y_STICKY_KEYS` Since 1.14.0 1.14.0
XKB_A11Y_STICKY_KEYS_LATCH_TO_LOCK	If both `XKB_A11Y_STICKY_KEYS_LATCH_TO_LOCK` and `XKB_KEYBOARD_CONTROL_A11Y_STICKY_KEYS` are activated, they enable users to lock modifier keys without requiring special locking keys. The user can press a latch modifier twice in a row to lock it, and then unlock it by pressing it one more time. See also `XKB_KEYBOARD_CONTROL_A11Y_STICKY_KEYS` Since 1.14.0
XKB_A11Y_LATCH_SIMULTANEOUS_KEYS	Without this option, the latch keys are only triggers if keys are strictly sequentially tapped, e.g.: `ISO_Level2_Latch` ↓ `ISO_Level2_Latch` ↑ `A` ↓ `A` ↑ If one wants multiple active latches, they must be tapped in sequence: e.g.: `ISO_Level2_Latch` ↓ `ISO_Level2_Latch` ↑ `ISO_Level3_Latch` ↓ `ISO_Level3_Latch` ↑ `A` ↓ `A` ↑ This option relaxes the strict sequence requirement and enables operating keys that do not break latches simultaneously with a latch key, e.g.: `ISO_Level2_Latch` ↓ `ISO_Level3_Latch` ↓ `ISO_Level2_Latch` ↑ `ISO_Level3_Latch` ↑ `A` ↓ `A` ↑ This is an extension to the X11 XKB protocol and is enabled by default when using `XKB_KEYMAP_FORMAT_TEXT_V2`. Since 1.14.0

◆ xkb_key_direction

enum xkb_key_direction

Specifies the direction of the key (press / release) or a repetition.

Enumerator

XKB_KEY_UP

The key was released.

XKB_KEY_DOWN

The key was pressed.

XKB_KEY_REPEATED

The key was repeated.

This should be used by the compositor only if it handles key repetition itself.

Since: 1.14.0

◆ xkb_layout_out_of_range_policy

enum xkb_layout_out_of_range_policy

Policies defining how to bring out-of-range layout indices into range.

Since: 1.14.0

Enumerator

XKB_LAYOUT_OUT_OF_RANGE_WRAP

Wrap into range using integer modulus (default).

Since: 1.14.0

XKB_LAYOUT_OUT_OF_RANGE_CLAMP

Clamp into range, i.e.

invalid indices are corrected to the closest valid bound (0 or highest layout index).

Since: 1.14.0

XKB_LAYOUT_OUT_OF_RANGE_REDIRECT

Redirect to a specific layout index.

Since: 1.14.0

◆ xkb_state_mode

enum xkb_state_mode

Mode for creating a keyboard state object.

Since: 1.14.0

See also: xkb_state::xkb_state_new_with_mode()

Enumerator

XKB_STATE_MODE_CLIENT

State driven by serialized state updates via xkb_state::xkb_state_update_mask().

Use this mode for client applications.

This is the recommended mode for new client applications, as it creates xkb_state objects with much smaller memory footprint than with xkb_state::xkb_state_new().

@important xkb_state objects created with this mode cannot be used with the following API:

xkb_state::xkb_state_update_event()
xkb_state::xkb_state_update_key()
xkb_state::xkb_state_update_synthetic()
xkb_state::xkb_state_update_latched_locked() *(deprecated)*

Since: 1.14.0

XKB_STATE_MODE_SERVER_QUERY

State driven by XKB events via xkb_state::xkb_state_update_event().

Use this mode for an observable state companion to an xkb_machine in server applications using the xkb_machine API.

This is the recommended mode for new server applications, as it creates xkb_state objects with much smaller memory footprint than with xkb_state::xkb_state_new().

@important xkb_state objects created with this mode cannot be used with the following API:

xkb_state::xkb_state_update_mask()
xkb_state::xkb_state_update_key()
xkb_state::xkb_state_update_synthetic()
xkb_state::xkb_state_update_latched_locked() *(deprecated)*

Since: 1.14.0

XKB_STATE_MODE_SERVER

State driven directly by key events, via xkb_state::xkb_state_update_key() or by synthetic input events, via xkb_state::xkb_state_update_synthetic().

Use this mode for server applications that do not use the preferred full-featured xkb_machine API.

@important Contrary to xkb_state::xkb_state_new(), xkb_state objects created with this mode cannot be used with the following API:

Warning: Prefer xkb_machine for new server applications. This mode exists for compatibility with code predating the xkb_machine API and may be deprecated in a future release.

Since: 1.14.0

◆ xkb_state_match

enum xkb_state_match

Match flags for xkb_state::xkb_state_mod_indices_are_active() and xkb_state::xkb_state_mod_names_are_active(), specifying the conditions for a successful match.

XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with the other modes.

Enumerator
XKB_STATE_MATCH_ANY	Returns `true` if any of the modifiers are active.
XKB_STATE_MATCH_ALL	Returns `true` if all of the modifiers are active.
XKB_STATE_MATCH_NON_EXCLUSIVE	Makes matching non-exclusive, i.e. will not return `false` if a modifier not specified in the arguments is active.

◆ xkb_consumed_mode

enum xkb_consumed_mode

Consumed modifiers mode.

There are several possible methods for deciding which modifiers are consumed and which are not, each applicable for different systems or situations. The mode selects the method to use.

Keep in mind that in all methods, the keymap may decide to preserve a modifier, meaning it is not reported as consumed even if it would have otherwise.

Enumerator

XKB_CONSUMED_MODE_XKB

This is the mode defined in the XKB specification and used by libX11.

A modifier is consumed if and only if it may affect key translation.

For example, if Control+Alt+<Backspace> produces some assigned keysym, then when pressing just <Backspace>, Control and Alt are consumed, even though they are not active, since if they were active they would have affected key translation.

XKB_CONSUMED_MODE_GTK

This is the mode used by the GTK+ toolkit.

The mode consists of the following two independent heuristics:

The currently active set of modifiers, excluding modifiers which do not affect the key (as described for XKB_CONSUMED_MODE_XKB), are considered consumed, if the keysyms produced when all of them are active are different from the keysyms produced when no modifiers are active.
A single modifier is considered consumed if the keysyms produced for the key when it is the only active modifier are different from the keysyms produced when no modifiers are active.

Function Documentation

◆ xkb_event_get_type()

XKB_EXPORT enum xkb_event_type xkb_event_get_type ( const struct xkb_event * event )

Get the type of an event.

Parameters

[in] event The event to process.

Returns: The event’s type.

Since: 1.14.0

◆ xkb_event_get_keycode()

XKB_EXPORT xkb_keycode_t xkb_event_get_keycode ( const struct xkb_event * event )

Get the keycode associated to a state event of type XKB_EVENT_TYPE_KEY_DOWN, XKB_EVENT_TYPE_KEY_REPEATED or XKB_EVENT_TYPE_KEY_UP.

Parameters

[in] event The event object to process.

Precondition

The event must be of one of the following types:

XKB_EVENT_TYPE_KEY_DOWN
XKB_EVENT_TYPE_KEY_REPEATED
XKB_EVENT_TYPE_KEY_UP Otherwise the result is undefined.

Returns: The keycode corresponding to the event.

Since: 1.14.0

◆ xkb_event_get_changed_components()

XKB_EXPORT enum xkb_state_component xkb_event_get_changed_components ( const struct xkb_event * event )

Get the state components changes corresponding to a state event of type XKB_EVENT_TYPE_COMPONENTS_CHANGE .

Parameters

[in] event The event object to process.

Precondition: The event must be of type XKB_EVENT_TYPE_COMPONENTS_CHANGE. Otherwise the result is undefined.

Returns: The corresponding mask of state components that have changed. If nothing in the state has changed, returns 0.

Since: 1.14.0

◆ xkb_event_serialize_enabled_controls()

XKB_EXPORT enum xkb_keyboard_control_flags xkb_event_serialize_enabled_controls	(	const struct xkb_event *	event,
		enum xkb_state_component	components
	)

Serialization of the boolean global keyboard controls corresponding to a state event of type XKB_EVENT_TYPE_COMPONENTS_CHANGE .

Parameters

[in]	event	The event object to process.
[in]	components	A mask of the keyboard control state components to serialize. State components other than `XKB_STATE_CONTROLS` are ignored.

Precondition: The event must be of type XKB_EVENT_TYPE_COMPONENTS_CHANGE. Otherwise the result is undefined.

Returns: The corresponding control mask representing the given components of the boolean controls state.

Since: 1.14.0

◆ xkb_event_serialize_mods()

XKB_EXPORT xkb_mod_mask_t xkb_event_serialize_mods	(	const struct xkb_event *	event,
		enum xkb_state_component	components
	)

Serialization of the modifiers corresponding to a state event of type XKB_EVENT_TYPE_COMPONENTS_CHANGE .

Parameters

[in]	event	The event object to process.
[in]	components	A mask of the modifier state components to serialize. State components other than `XKB_STATE_MODS_*` are ignored. If `XKB_STATE_MODS_EFFECTIVE` is included, all other state components are ignored.

Precondition: The event must be of type XKB_EVENT_TYPE_COMPONENTS_CHANGE. Otherwise the result is undefined.

Returns: The corresponding modifier mask representing the given components of the modifier state.

Since: 1.14.0

◆ xkb_event_serialize_layout()

XKB_EXPORT xkb_layout_index_t xkb_event_serialize_layout	(	const struct xkb_event *	event,
		enum xkb_state_component	components
	)

Serialization of the layout corresponding to a state event of type XKB_EVENT_TYPE_COMPONENTS_CHANGE .

Parameters

[in]	event	The event object to process.
[in]	components	A mask of the layout state components to serialize. State components other than `XKB_STATE_LAYOUT_*` are ignored. If `XKB_STATE_LAYOUT_EFFECTIVE` is included, all other state components are ignored.

Precondition: The event must be of type XKB_EVENT_TYPE_COMPONENTS_CHANGE. Otherwise the result is undefined.

Returns: The corresponding layout index representing the given components of the layout state.

Since: 1.14.0

◆ xkb_events_new_batch()

XKB_EXPORT struct xkb_events * xkb_events_new_batch	(	struct xkb_context *	context,
		enum xkb_events_flags	flags
	)

Create a new event batch.

Parameters

[in]	context	The context in which to create the batch.
[in]	flags	Optional flags for the batch, or 0.

Returns: A new event batch, or NULL on failure.

Since: 1.14.0

See also: xkb_events_destroy(); xkb_events_next(); xkb_machine::xkb_machine_process_key()

◆ xkb_events_destroy()

XKB_EXPORT void xkb_events_destroy ( struct xkb_events * events )

Free an event collection.

Parameters

[in] events The event collection to free. If it is NULL, this function does nothing.

Since: 1.14.0

See also: xkb_events_new_batch()

◆ xkb_events_next()

XKB_EXPORT const struct xkb_event * xkb_events_next ( struct xkb_events * events )

Get the next event from an event collection.

Parameters

[in] events The event collection.

Returns: The next event, or NULL if there are no more events to read.

Since: 1.14.0

◆ xkb_machine_builder_new()

XKB_EXPORT struct xkb_machine_builder * xkb_machine_builder_new	(	struct xkb_keymap *	keymap,
		enum xkb_machine_builder_flags	flags
	)

Create a new xkb_machine builder object.

xkb_machine objects can then be created from the builder using xkb_machine::xkb_machine_new().

Parameters

[in]	keymap	The keymap which the state machine will use.
[in]	flags	Flags to control the builder behavior, or 0.

Returns: A new xkb_machine builder object, or NULL on failure.

Since: 1.14.0

See also: xkb_machine_builder_destroy(); xkb_machine::xkb_machine_new()

◆ xkb_machine_builder_destroy()

XKB_EXPORT void xkb_machine_builder_destroy ( struct xkb_machine_builder * builder )

Free a xkb_machine builder object.

Parameters

[in] builder The xkb_machine builder. If it is NULL, this function does nothing.

Since: 1.14.0

See also: xkb_machine_builder_new()

◆ xkb_machine_builder_get_keymap()

XKB_EXPORT struct xkb_keymap * xkb_machine_builder_get_keymap ( const struct xkb_machine_builder * builder )

Get the keymap which a xkb_machine_builder object is using.

Parameters

[in] builder The state machine builder object.

Returns: The keymap which was passed to xkb_machine_builder_new() when creating this xkb_machine_builder object.

Warning: This function does not take a new reference on the keymap; you must explicitly reference it yourself if you plan to use it beyond the lifetime of the xkb_machine_builder object.

Since: 1.14.0

◆ xkb_machine_builder_update_a11y_flags()

XKB_EXPORT enum xkb_error_code xkb_machine_builder_update_a11y_flags	(	struct xkb_machine_builder *	builder,
		enum xkb_a11y_flags	affect,
		enum xkb_a11y_flags	flags
	)

Update the accessibility flags of an xkb_machine_builder object.

Parameters

[in,out]	builder	The `xkb_machine` builder object to modify.
[in]	affect	Accessibility flags to modify.
[in]	flags	Accessibility flags to set or unset. Flags in `affect` but not in `flags` are cleared. Flags outside `affect` are not changed.

Returns: XKB_SUCCESS on success, otherwise an error code.

Since: 1.14.0

◆ xkb_machine_builder_remap_mods()

XKB_EXPORT enum xkb_error_code xkb_machine_builder_remap_mods	(	struct xkb_machine_builder *	builder,
		xkb_mod_mask_t	source,
		xkb_mod_mask_t	target
	)

Remap a modifier combination, e.g.

to make Control+Alt act as LevelThree (AltGr). This helps improve compatibility across platforms.

The remapping takes effect only using xkb_machine::xkb_machine_process_key() and under certain conditions:

The corresponding effective modifiers are active.
The key being processed has a type that does not use any of the source modifiers.
There is no other remapping entry with the source modifiers being a superset of this entry. E.g. Control+Alt has priority over Control.

Parameters

[in,out]	builder	The `xkb_machine` builder object to modify.
[in]	source	Modifier combination to remap, using their encoding. Must be non-zero, unless both `source` and `target` are 0 to clear all entries.
[in]	target	Modifier combination to remap to, using their encoding, or 0 to remove the entry for `source`. If both `source` and `target` are 0, all entries are cleared.

Returns: XKB_SUCCESS on success, otherwise an error code.

Example:

struct xkb_keymap *keymap = xkb_machine_builder_get_keymap(builder);
// Remap Control+Alt to LevelThree (AltGr)
const xkb_mod_mask_t ctrl = xkb_keymap_mod_get_mask(keymap, XKB_MOD_NAME_CTRL);
const xkb_mod_mask_t alt = xkb_keymap_mod_get_mask(keymap, XKB_VMOD_NAME_ALT);
const xkb_mod_mask_t level3 = xkb_keymap_mod_get_mask(keymap, XKB_VMOD_NAME_LEVEL3);
if (xkb_machine_builder_remap_mods(builder, ctrl | alt, level3)) {
    // handle error
    …
}

Since: 1.14.0

◆ xkb_machine_builder_update_shortcut_mods()

XKB_EXPORT enum xkb_error_code xkb_machine_builder_update_shortcut_mods	(	struct xkb_machine_builder *	builder,
		xkb_mod_mask_t	affect,
		xkb_mod_mask_t	mask
	)

Set the modifiers that trigger the keyboard shortcut overrides.

When any of the specified modifiers is active, the effective layout is substituted according to the mapping set by xkb_machine_builder_remap_shortcut_layout(). This ensures a consistent user experience with keyboard shortcuts across the layouts.

Parameters

[in,out]	builder	The `xkb_machine` builder object to modify.
[in]	affect	Modifiers to consider, using their encoding.
[in]	mask	Modifiers to set or unset, using their encoding. Modifiers in `affect` but not in `mask` are cleared. Modifiers outside `affect` are not changed.

Returns: XKB_SUCCESS on success, otherwise an error code.

See also: xkb_machine_builder_remap_shortcut_layout(); xkb_keymap::xkb_keymap_mod_get_mask2()

Since: 1.14.0

◆ xkb_machine_builder_remap_shortcut_layout()

XKB_EXPORT enum xkb_error_code xkb_machine_builder_remap_shortcut_layout	(	struct xkb_machine_builder *	builder,
		xkb_layout_index_t	source,
		xkb_layout_index_t	target
	)

Set a layout substitution for the shortcut layout override.

When any modifier set via xkb_machine_builder_update_shortcut_mods() is active, the effective layout source is substituted with layout target in key processing. This allows shortcuts defined in layout target (typically a Latin layout) to remain reachable when layout source is active.

Parameters

[in,out]	builder	The `xkb_machine` builder object to modify.
[in]	source	Source layout to substitute.
[in]	target	Target layout to use instead of `source`.

Returns: XKB_SUCCESS on success, otherwise an error code.

Since: 1.14.0

See also: xkb_machine_builder_update_shortcut_mods()

◆ xkb_machine_new()

XKB_EXPORT struct xkb_machine * xkb_machine_new ( const struct xkb_machine_builder * builder )

Create a new keyboard state machine object.

This entry point is intended for server applications; client applications should not run a state machine locally: instead they should use the xkb_state API and process server state update using xkb_state::xkb_state_update_mask(). See Server State and Client State for further information.

Parameters

[in] builder The builder object from which to create the state machine.

Returns: A new keyboard state machine object, or NULL on failure.

Since: 1.14.0

See also: xkb_machine_builder::xkb_machine_builder_new()

◆ xkb_machine_ref()

XKB_EXPORT struct xkb_machine * xkb_machine_ref ( struct xkb_machine * machine )

Take a new reference on a xkb_machine object.

Parameters

[in] machine The state machine.

Returns: The passed in object.

Since: 1.14.0

◆ xkb_machine_unref()

XKB_EXPORT void xkb_machine_unref ( struct xkb_machine * machine )

Release a reference on a xkb_machine object, and possibly free it.

Parameters

[in] machine The state machine. If it is NULL, this function does nothing.

Since: 1.14.0

◆ xkb_machine_get_keymap()

XKB_EXPORT struct xkb_keymap * xkb_machine_get_keymap ( const struct xkb_machine * machine )

Get the keymap which a xkb_machine object is using.

Parameters

[in] machine The state machine.

Returns: The keymap which was used to create the xkb_machine object, i.e. the keymap passed to xkb_machine_builder::xkb_machine_builder_new() when creating the corresponding builder used in xkb_machine_new().

Warning: This function does not take a new reference on the keymap; you must explicitly reference it yourself if you plan to use it beyond the lifetime of the xkb_machine object.

Since: 1.14.0

◆ xkb_machine_process_key()

XKB_EXPORT enum xkb_error_code xkb_machine_process_key	(	struct xkb_machine *	machine,
		xkb_keycode_t	key,
		enum xkb_key_direction	direction,
		struct xkb_events *	events
	)

Process a key event – a pair (keycode, direction) – through the XKB state machine, and collect the resulting keyboard events into an event batch.

The produced events form a single frame.

Use this function for in-band (device) inputs. Use xkb_machine_process_synthetic() instead to update the state machine in response to out-of-band (non-device) inputs, such as UI layout switchers or accessibility settings changes.

A series of calls to this function should be consistent; that is, a call with XKB_KEY_DOWN for a key should be matched by an XKB_KEY_UP; if a key is pressed twice, it should be released twice; etc. Otherwise (e.g. due to missed input events), situations like “stuck modifiers” may occur.

Parameters

[in,out]	machine	The XKB state machine object.
[in]	key	The keycode of the key being operated.
[in]	direction	The direction of the key operation.
[out]	events	The event batch to collect events into. It will be reset before collecting.

Returns: XKB_SUCCESS on success, otherwise an error code.

Since: 1.14.0

See also: xkb_machine_process_synthetic()

◆ xkb_machine_process_synthetic()

XKB_EXPORT enum xkb_error_code xkb_machine_process_synthetic	(	struct xkb_machine *	machine,
		const struct xkb_state_update *	update,
		struct xkb_events *	events
	)

Process a synthetic (out-of-band) atomic update through the XKB state machine, and collect the resulting keyboard events into an event batch.

Use this function to update the state machine in response to out-of-band (non-device) inputs, such as UI layout switchers or accessibility settings changes. Use xkb_machine_process_key() instead for in-band (device) inputs.

All changes specified in update are applied atomically as a single frame: the resulting events reflect the net state change at the end of the frame, not intermediate steps. In particular, a XKB_EVENT_TYPE_COMPONENTS_CHANGE event in the batch represents the cumulative state change for the entire frame — individual intermediate state transitions are not observable.

Only latched, locked and control components can be updated out-of-band; depressed components can only change through key presses via xkb_machine_process_key().

Layout out of range: If the effective layout, after taking into account the depressed, latched and locked layout, is out of range (negative or greater than the maximum layout index), it is brought into range according to the current out-of-range layout policy (see xkb_layout_out_of_range_policy).

Parameters

[in,out]	machine	The XKB state machine object.
[in]	update	The update to apply. Must have `xkb_state_update::size` set.
[out]	events	The event batch to collect events into. It will be reset before collecting.

Returns: XKB_SUCCESS on success, otherwise an error code.

Since: 1.14.0

See also: xkb_state_update; xkb_machine_process_key()

◆ xkb_state_new_with_mode()

XKB_EXPORT struct xkb_state * xkb_state_new_with_mode	(	struct xkb_keymap *	keymap,
		enum xkb_state_mode	mode
	)

Create a new keyboard state object with an explicit mode.

This entry point is intended for both server and client applications. It enables using the optimal implementation for the intended use.

Parameters

[in]	keymap	The keymap which the state will use.
[in]	mode	The state mode to use.

Returns: A new keyboard state object, or NULL on failure.

Since: 1.14.0

See also: xkb_state_mode

◆ xkb_state_new()

XKB_EXPORT struct xkb_state * xkb_state_new ( struct xkb_keymap * keymap )

Create a new keyboard state object.

Note: This is the legacy constructor, predating the xkb_machine API. It imposes no restrictions on which update functions may be called, making it easy to accidentally mix incompatible update paths. Prefer xkb_state::xkb_state_new_with_mode() for new code, which enforces correct API usage at runtime and optimal performance.

Parameters

[in] keymap The keymap which the state will use.

Returns: A new keyboard state object, or NULL on failure.

◆ xkb_state_ref()

XKB_EXPORT struct xkb_state * xkb_state_ref ( struct xkb_state * state )

Take a new reference on a keyboard state object.

Parameters

[in] state The state to reference.

Returns: The passed-in object.

◆ 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.

Parameters

[in] state The state. If it is NULL, this function does nothing.

◆ xkb_state_get_keymap()

XKB_EXPORT struct xkb_keymap * xkb_state_get_keymap ( struct xkb_state * state )

Get the keymap which a keyboard state object is using.

Parameters

[in] state The keyboard state object.

Returns: The keymap which was passed to xkb_state_new() or xkb_state_new_with_mode() when creating this state object.

Warning: This function does not take a new reference on the keymap; you must explicitly reference it yourself if you plan to use it beyond the lifetime of the 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.

This entry point is intended for client applications; see Server State and Client State for details. Server applications should use either the recommended modern xkb_machine API with the corresponding xkb_state_update_event() or the legacy xkb_state_update_synthetic() API instead.

Parameters

[in,out]	state	The keyboard state object.
[in]	depressed_mods	Modifiers to set as depressed.
[in]	latched_mods	Modifiers to set as latched.
[in]	locked_mods	Modifiers to set as locked.
[in]	depressed_layout	Layout to set as depressed.
[in]	latched_layout	Layout to set as latched.
[in]	locked_layout	Layout to set as locked.

Precondition: All parameters must represent a consistent snapshot of the server keyboard state at a single point in time. In case the server provides only a single layout state (e.g. the effective layout in the Wayland protocol), it should be used for locked_layout, while depressed_layout and latched_layout are both set to 0.

@important If state was not created with XKB_STATE_MODE_CLIENT or xkb_state_new(), the call is rejected without updating the state, and the misuse is logged as XKB_ERROR_UNEXPECTED_STATE_MODE. The return value is 0 in this case, which is indistinguishable from a no-op update.

Returns: A mask of state components that have changed as a result of the update. If nothing in the state has changed, returns 0.

See also: xkb_state_component; xkb_state_update_synthetic(); xkb_state_update_event()

◆ xkb_state_update_event()

XKB_EXPORT enum xkb_state_component xkb_state_update_event	(	struct xkb_state *	state,
		const struct xkb_event *	event
	)

Update the keyboard state components from an event.

This entry point is intended for server applications and should not be used by client applications; see Server State and Client State for details.

It enables server applications to use xkb_state as the observable state companion to an xkb_machine: feed each event produced by xkb_machine::xkb_machine_process_key() or xkb_machine::xkb_machine_process_synthetic() into this function to keep the observable state in sync.

Parameters

[in,out]	state	The keyboard state object.
[in]	event	The state event to update from.

@important If state was not created with XKB_STATE_MODE_SERVER_QUERY or xkb_state_new(), the call is rejected without updating the state, and the misuse is logged as XKB_ERROR_UNEXPECTED_STATE_MODE. The return value is 0 in this case, which is indistinguishable from a no-op update.

Returns: A mask of state components that have changed as a result of the update. If nothing in the state has changed, returns 0.

Since: 1.14.0

◆ xkb_state_update_key()

XKB_EXPORT enum xkb_state_component xkb_state_update_key	(	struct xkb_state *	state,
		xkb_keycode_t	key,
		enum xkb_key_direction	direction
	)

Update the keyboard state to reflect a given key being pressed or released.

This entry point is intended for server applications and should not be used by client applications; see Server State and Client State for details.

A series of calls to this function should be consistent; that is, a call with XKB_KEY_DOWN for a key should be matched by an XKB_KEY_UP; if a key is pressed twice, it should be released twice; etc. Otherwise (e.g. due to missed input events), situations like “stuck modifiers” may occur.

This function is often used in conjunction with the function xkb_state_key_get_syms() (or xkb_state_key_get_one_sym()), for example, when handling a key event. In this case, you should prefer to get the keysyms before updating the key, such that the keysyms reported for the key event are not affected by the event itself. This is the conventional behavior.

Note: This is the legacy server entry point and only supports a restricted set of libxkbcommon features. Since 1.14.0, prefer xkb_machine for new server applications to enable the full feature set.

Parameters

[in,out]	state	The keyboard state object.
[in]	key	The key being operated.
[in]	direction	The direction of the key operation.

@important If state was not created with XKB_STATE_MODE_SERVER or xkb_state_new(), the call is rejected without updating the state, and the misuse is logged as XKB_ERROR_UNEXPECTED_STATE_MODE. The return value is 0 in this case, which is indistinguishable from a no-op update.

Returns: A mask of state components that have changed as a result of the update. If nothing in the state has changed, returns 0.

See also: xkb_state_update_mask()

◆ xkb_state_update_synthetic()

XKB_EXPORT enum xkb_error_code xkb_state_update_synthetic	(	struct xkb_state *	state,
		const struct xkb_state_update *	update,
		enum xkb_state_component *	changed
	)

Apply a synthetic (out-of-band) atomic update to the keyboard state.

This entry point is intended for server applications and should not be used by client applications; see Server State and Client State for details.

Use this function to update the keyboard state in response to out-of-band (non-device) inputs, such as UI layout switchers or accessibility settings changes.
Use xkb_state_update_key() instead for in-band (device) inputs.
Use xkb_state_update_event() instead when updating from an event produced by xkb_machine.

Only latched, locked and control components can be updated out-of-band; depressed components can only change through key presses via xkb_state_update_key().

Layout out of range: If the effective layout, after taking into account the depressed, latched and locked layout, is out of range (negative or greater than the maximum layout index), it is brought into range according to the current out-of-range layout policy (see xkb_layout_out_of_range_policy).

Note: This entry point serves the legacy server use case and only supports a restricted set of libxkbcommon features. Since 1.14.0, prefer xkb_machine for new server applications to enable the full feature set.

Parameters

[in,out]	state	The keyboard state object.
[in]	update	The update to apply. Must have `xkb_state_update::size` set.
[out]	changed	A pointer to store the mask of state components that have changed as a result of the update, or `NULL` to ignore. Set to 0 if nothing in the state has changed.

Returns

XKB_SUCCESS on success;
XKB_ERROR_UNEXPECTED_STATE_MODE without updating the state if state was not created with XKB_STATE_MODE_SERVER or xkb_state_new().
Otherwise another error code.

Note: This function returns an error code rather than a state component delta (unlike the other xkb_state_update_* functions), in order to align with the xkb_machine::xkb_machine_process_synthetic() API. The delta is optionally available via the changed parameter.

Since: 1.14.0

See also: xkb_state_update; xkb_state_update_key(); xkb_machine::xkb_machine_process_synthetic()

◆ xkb_state_update_latched_locked()

XKB_EXPORT enum xkb_state_component xkb_state_update_latched_locked	(	struct xkb_state *	state,
		xkb_mod_mask_t	affect_latched_mods,
		xkb_mod_mask_t	latched_mods,
		bool	affect_latched_layout,
		int32_t	latched_layout,
		xkb_mod_mask_t	affect_locked_mods,
		xkb_mod_mask_t	locked_mods,
		bool	affect_locked_layout,
		int32_t	locked_layout
	)

Update the keyboard state to change the latched and locked state of the modifiers and layout.

Deprecated:: Use xkb_state_update_synthetic() instead.

This entry point is intended for server applications and should not be used by client applications; see Server State and Client State for details.

Use this function to update the latched and locked state according to out-of-band (non-device) inputs, such as UI layout switchers.

Layout out of range: If the effective layout, after taking into account the depressed, latched and locked layout, is out of range (negative or greater than the maximum layout), it is brought into range. Currently, the layout is wrapped using integer modulus (with negative values wrapping from the end). The wrapping behavior can be configured using xkb_state_update_synthetic().

Parameters

[in,out]	state	The keyboard state object.
[in]	affect_latched_mods	See `latched_mods`.
[in]	latched_mods	Modifiers to set as latched or unlatched. Only modifiers in `affect_latched_mods` are considered.
[in]	affect_latched_layout	See `latched_layout`.
[in]	latched_layout	Layout to latch. Only considered if `affect_latched_layout` is `true`. May be out of range (including negative) – see note above.
[in]	affect_locked_mods	See `locked_mods`.
[in]	locked_mods	Modifiers to set as locked or unlocked. Only modifiers in `affect_locked_mods` are considered.
[in]	affect_locked_layout	See `locked_layout`.
[in]	locked_layout	Layout to lock. Only considered if `affect_locked_layout` is `true`. May be out of range (including negative) – see note above.

@important If state was not created with XKB_STATE_MODE_SERVER or xkb_state_new(), the call is rejected without updating the state, and the misuse is logged as XKB_ERROR_UNEXPECTED_STATE_MODE. The return value is 0 in this case, which is indistinguishable from a no-op update.

Returns: A mask of state components that have changed as a result of the update. If nothing in the state has changed, returns 0.

See also: xkb_state_update_synthetic()

◆ xkb_state_key_get_syms()

XKB_EXPORT int xkb_state_key_get_syms	(	struct xkb_state *	state,
		xkb_keycode_t	key,
		const xkb_keysym_t **	syms_out
	)

Get the keysyms obtained from pressing a particular key in a given keyboard state.

Get the keysyms for a key according to the current active layout, modifiers and shift level for the key, as determined by a keyboard state.

Parameters

[in]	state	The keyboard state object.
[in]	key	The keycode of the key.
[out]	syms_out	An immutable array of keysyms corresponding the key in the given keyboard state.

As an extension to XKB, this function can return more than one keysym. If you do not want to handle this case, you can use xkb_state_key_get_one_sym() for a simpler interface.

Returns: The number of keysyms in the syms_out array. If no keysyms are produced by the key in the given keyboard state, returns 0 and sets syms_out to NULL.

This function performs Capitalization Keysym Transformations.

Since: 1.9.0 This function now performs Keysym Transformations.

◆ xkb_state_key_get_utf8()

XKB_EXPORT int xkb_state_key_get_utf8	(	struct xkb_state *	state,
		xkb_keycode_t	key,
		char *	buffer,
		size_t	size
	)

Get the Unicode/UTF-8 string obtained from pressing a particular key in a given keyboard state.

Parameters

[in]	state	The keyboard state object.
[in]	key	The keycode of the key.
[out]	buffer	A buffer to write the string into.
[in]	size	Capacity of the buffer.

Warning: If the buffer passed is too small, the string is truncated (though still NULL-terminated).

Returns: The number of bytes required for the string, excluding the NULL byte. If there is nothing to write, returns 0.

You may check if truncation has occurred by comparing the return value with the size of buffer, similarly to the snprintf(3) function. You may safely pass NULL and 0 to buffer and size to find the required size (without the NULL-byte).

This function performs Capitalization and Control Keysym Transformations.

Since: 0.4.1

◆ xkb_state_key_get_utf32()

XKB_EXPORT uint32_t xkb_state_key_get_utf32	(	struct xkb_state *	state,
		xkb_keycode_t	key
	)

Get the Unicode/UTF-32 codepoint obtained from pressing a particular key in a a given keyboard state.

Parameters

[in]	state	The keyboard state object.
[in]	key	The keycode of the key.

Returns: The UTF-32 representation for the key, if it consists of only a single codepoint. Otherwise, returns 0.

This function performs Capitalization and Control Keysym Transformations.

Since: 0.4.1

◆ xkb_state_key_get_one_sym()

XKB_EXPORT xkb_keysym_t xkb_state_key_get_one_sym	(	struct xkb_state *	state,
		xkb_keycode_t	key
	)

Get the single keysym obtained from pressing a particular key in a given keyboard state.

This function is similar to xkb_state_key_get_syms(), but intended for users which cannot or do not want to handle the case where multiple keysyms are returned (in which case this function is preferred).

Parameters

[in]	state	The keyboard state object.
[in]	key	The keycode of the key.

Returns: The keysym. If the key does not have exactly one keysym, returns XKB_KEY_NoSymbol.

This function performs Capitalization Keysym Transformations.

See also: xkb_state_key_get_syms()

◆ xkb_state_key_get_layout()

XKB_EXPORT xkb_layout_index_t xkb_state_key_get_layout	(	struct xkb_state *	state,
		xkb_keycode_t	key
	)

Get the effective layout index for a key in a given keyboard state.

Parameters

[in]	state	The keyboard state object.
[in]	key	The keycode of the key.

Returns: The layout index for the key in the given keyboard state. If the given keycode is invalid, or if the key is not included in any layout at all, returns XKB_LAYOUT_INVALID.

Invariant: If the returned layout is valid, the following always holds:
xkb_state_key_get_layout(state, key) < xkb_keymap_num_layouts_for_key(keymap, key)

xkb_state::xkb_state_key_get_layout
XKB_EXPORT xkb_layout_index_t xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t key)
Get the effective layout index for a key in a given keyboard state.

◆ xkb_state_key_get_level()

XKB_EXPORT xkb_level_index_t xkb_state_key_get_level	(	struct xkb_state *	state,
		xkb_keycode_t	key,
		xkb_layout_index_t	layout
	)

Get the effective shift level for a key in a given keyboard state and layout.

Parameters

[in]	state	The keyboard state.
[in]	key	The keycode of the key.
[in]	layout	The layout for which to get the shift level. This must be smaller than: xkb_keymap_num_layouts_for_key(keymap, key) usually it would be: xkb_state_key_get_layout(state, key)

Returns: The shift level index. If the key or layout are invalid, returns XKB_LEVEL_INVALID.

Invariant: If the returned level is valid, the following always holds:
xkb_state_key_get_level(state, key, layout) < xkb_keymap_num_levels_for_key(keymap, key, layout)

xkb_state::xkb_state_key_get_level
XKB_EXPORT xkb_level_index_t xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key, xkb_layout_index_t layout)
Get the effective shift level for a key in a given keyboard state and layout.

◆ xkb_state_serialize_enabled_controls()

XKB_EXPORT enum xkb_keyboard_control_flags xkb_state_serialize_enabled_controls	(	const struct xkb_state *	state,
		enum xkb_state_component	components
	)

Serialization of the boolean global keyboard controls, to be used on the server side of serialization.

This entry point is intended for server applications; see Server State and Client State for details.

Parameters

[in]	state	The keyboard state.
[in]	components	A mask of the keyboard control state components to serialize. State components other than `XKB_STATE_CONTROLS` are ignored.

Returns: A xkb_keyboard_control_flags mask representing the enabled keyboard controls for the given components.

Since: 1.14.0

◆ 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 serialization.

This entry point is intended for server applications; see Server State and Client State for details. Client applications should use the xkb_state_mod_*_is_active API.

Warning: The serialization is lossy and will not survive round trips. It must only be used to feed client state objects created with either XKB_STATE_MODE_CLIENT or xkb_state_new(), and must not be used to update the server state.

Parameters

[in]	state	The keyboard state.
[in]	components	A mask of the modifier state components to serialize. State components other than `XKB_STATE_MODS_*` are ignored. If `XKB_STATE_MODS_EFFECTIVE` is included, all other state components are ignored.

Returns: A xkb_mod_mask_t representing the given components of the modifier state.

◆ xkb_state_serialize_layout()

XKB_EXPORT xkb_layout_index_t xkb_state_serialize_layout	(	struct xkb_state *	state,
		enum xkb_state_component	components
	)

The counterpart to xkb_state::xkb_state_update_mask() for layouts, to be used on the server side of serialization.

This entry point is intended for server applications; see Server State and Client State for details. Client applications should use the xkb_state_layout_*_is_active API.

Warning: The serialization is lossy and will not survive round trips. It must only be used to feed client state objects created with either XKB_STATE_MODE_CLIENT or xkb_state_new(), and must not be used to update the server state.

Parameters

[in]	state	The keyboard state.
[in]	components	A mask of the layout state components to serialize. State components other than `XKB_STATE_LAYOUT_*` are ignored. If `XKB_STATE_LAYOUT_EFFECTIVE` is included, all other state components are ignored.

Returns: A layout index representing the given components of the layout state.

◆ xkb_state_mod_name_is_active()

XKB_EXPORT int xkb_state_mod_name_is_active	(	struct xkb_state *	state,
		const char *	name,
		enum xkb_state_component	type
	)

Test whether a modifier is active in a given keyboard state by name.

Warning: For virtual modifiers, this function may overmatch in case there are virtual modifiers with overlapping mappings to real modifiers.

Parameters

[in]	state	The keyboard state object.
[in]	name	The modifier name, as a `NULL`-terminated string.
[in]	type	The component of the state against which to match the given modifiers.

Returns: 1 if the modifier is active, 0 if it is not. If the modifier name does not exist in the keymap, returns -1.

Since: 0.1.0: Works only with real modifiers; 1.8.0: Works also with virtual modifiers

◆ xkb_state_mod_names_are_active()

XKB_EXPORT int xkb_state_mod_names_are_active	(	struct xkb_state *	state,
		enum xkb_state_component	type,
		enum xkb_state_match	match,
			...
	)

Test whether a set of modifiers are active in a given keyboard state by name.

Warning: For virtual modifiers, this function may overmatch in case there are virtual modifiers with overlapping mappings to real modifiers.

Parameters

[in]	state	The keyboard state.
[in]	type	The component of the state against which to match the given modifiers.
[in]	match	The manner by which to match the state against the given modifiers.
[in]	...	The set of of modifier names to test, terminated by a `NULL` argument (sentinel).

Returns: 1 if the modifiers are active, 0 if they are not. If any of the modifier names do not exist in the keymap, returns -1. If match contains invalid flags, returns -2.

Since: 0.1.0: Works only with real modifiers; 1.8.0: Works also with virtual modifiers; 1.14.0: Reject invalid match flags

◆ xkb_state_mod_index_is_active()

XKB_EXPORT int xkb_state_mod_index_is_active	(	struct xkb_state *	state,
		xkb_mod_index_t	idx,
		enum xkb_state_component	type
	)

Test whether a modifier is active in a given keyboard state by index.

Warning: For virtual modifiers, this function may overmatch in case there are virtual modifiers with overlapping mappings to real modifiers.

Parameters

[in]	state	The keyboard state.
[in]	idx	The index of the modifier to test.
[in]	type	The component of the state against which to match the given modifiers.

Returns: 1 if the modifier is active, 0 if it is not. If the modifier index is invalid in the keymap, returns -1.

Since: 0.1.0: Works only with real modifiers; 1.8.0: Works also with virtual modifiers

◆ xkb_state_mod_indices_are_active()

XKB_EXPORT int xkb_state_mod_indices_are_active	(	struct xkb_state *	state,
		enum xkb_state_component	type,
		enum xkb_state_match	match,
			...
	)

Test whether a set of modifiers are active in a given keyboard state by index.

Warning: For virtual modifiers, this function may overmatch in case there are virtual modifiers with overlapping mappings to real modifiers.

Parameters

[in]	state	The keyboard state.
[in]	type	The component of the state against which to match the given modifiers.
[in]	match	The manner by which to match the state against the given modifiers.
[in]	...	The set of of modifier indices to test, terminated by a `XKB_MOD_INVALID` argument (sentinel).

Returns: 1 if the modifiers are active, 0 if they are not. If any of the modifier indices are invalid in the keymap, returns -1. If match contains invalid flags, returns -2.

Since: 0.1.0: Works only with real modifiers; 1.8.0: Works also with virtual modifiers; 1.14.0: Reject invalid match flags

◆ xkb_state_key_get_consumed_mods2()

XKB_EXPORT xkb_mod_mask_t xkb_state_key_get_consumed_mods2	(	struct xkb_state *	state,
		xkb_keycode_t	key,
		enum xkb_consumed_mode	mode
	)

Get the mask of modifiers consumed by translating a given key.

Parameters

[in]	state	The keyboard state.
[in]	key	The keycode of the key.
[in]	mode	The consumed modifiers mode to use; see enum description.

Returns: a mask of the consumed real modifiers modifiers.

Since: 0.7.0

◆ xkb_state_key_get_consumed_mods()

XKB_EXPORT xkb_mod_mask_t xkb_state_key_get_consumed_mods	(	struct xkb_state *	state,
		xkb_keycode_t	key
	)

Same as xkb_state_key_get_consumed_mods2() with mode XKB_CONSUMED_MODE_XKB.

Since: 0.4.1

◆ xkb_state_mod_index_is_consumed2()

XKB_EXPORT int xkb_state_mod_index_is_consumed2	(	struct xkb_state *	state,
		xkb_keycode_t	key,
		xkb_mod_index_t	idx,
		enum xkb_consumed_mode	mode
	)

Test whether a modifier is consumed by keyboard state translation for a key.

Warning: For virtual modifiers, this function may overmatch in case there are virtual modifiers with overlapping mappings to real modifiers.

Parameters

[in]	state	The keyboard state.
[in]	key	The keycode of the key.
[in]	idx	The index of the modifier to check.
[in]	mode	The consumed modifiers mode to use; see enum description.

Returns: 1 if the modifier is consumed, 0 if it is not. If the modifier index is not valid in the keymap, returns -1.

See also: xkb_state_mod_mask_remove_consumed(); xkb_state_key_get_consumed_mods()

Since: 0.7.0: Works only with real modifiers; 1.8.0: Works also with virtual modifiers

◆ xkb_state_mod_index_is_consumed()

XKB_EXPORT int xkb_state_mod_index_is_consumed	(	struct xkb_state *	state,
		xkb_keycode_t	key,
		xkb_mod_index_t	idx
	)

Same as xkb_state_mod_index_is_consumed2() with mode XKB_CONSUMED_MODE_XKB.

Warning: For virtual modifiers, this function may overmatch in case there are virtual modifiers with overlapping mappings to real modifiers.

Since: 0.4.1: Works only with real modifiers; 1.8.0: Works also with virtual modifiers

◆ xkb_state_mod_mask_remove_consumed()

XKB_EXPORT xkb_mod_mask_t xkb_state_mod_mask_remove_consumed	(	struct xkb_state *	state,
		xkb_keycode_t	key,
		xkb_mod_mask_t	mask
	)

Remove consumed modifiers from a modifier mask for a key.

Deprecated:: Use xkb_state_key_get_consumed_mods2() instead.

Takes the given modifier mask, and removes all modifiers which are consumed for that particular key (as in xkb_state_mod_index_is_consumed()).

Returns: a mask of real modifiers modifiers.

See also: xkb_state_mod_index_is_consumed()

Since: 0.5.0: Works only with real modifiers; 1.8.0: Works also with virtual modifiers

◆ xkb_state_layout_name_is_active()

XKB_EXPORT int xkb_state_layout_name_is_active	(	struct xkb_state *	state,
		const char *	name,
		enum xkb_state_component	type
	)

Test whether a layout is active in a given keyboard state by name.

Parameters

[in]	state	The keyboard state.
[in]	name	The layout name to test (`NULL`-terminated string).
[in]	type	The component of the state against which to match the given layout.

Returns: 1 if the layout is active, 0 if it is not. If no layout with this name exists in the keymap, return -1.

If multiple layouts in the keymap have this name, the one with the lowest index is tested.

See also: xkb_layout_index_t

◆ xkb_state_layout_index_is_active()

XKB_EXPORT int xkb_state_layout_index_is_active	(	struct xkb_state *	state,
		xkb_layout_index_t	idx,
		enum xkb_state_component	type
	)

Test whether a layout is active in a given keyboard state by index.

Parameters

[in]	state	The keyboard state.
[in]	idx	The layout index to test.
[in]	type	The component of the state against which to match the given layout.

Returns: 1 if the layout is active, 0 if it is not. If the layout index is not valid in the keymap, returns -1.

See also: xkb_layout_index_t

◆ xkb_state_led_name_is_active()

XKB_EXPORT int xkb_state_led_name_is_active	(	struct xkb_state *	state,
		const char *	name
	)

Test whether a LED is active in a given keyboard state by name.

Parameters

[in]	state	The keyboard state.
[in]	name	The LED name to test (`NULL`-terminated string).

Returns: 1 if the LED is active, 0 if it not. If no LED with this name exists in the keymap, returns -1.

See also: xkb_led_index_t

◆ xkb_state_led_index_is_active()

XKB_EXPORT int xkb_state_led_index_is_active	(	struct xkb_state *	state,
		xkb_led_index_t	idx
	)

Test whether a LED is active in a given keyboard state by index.

Parameters

[in]	state	The keyboard state.
[in]	idx	The LED index to test.

Returns: 1 if the LED is active, 0 if it not. If the LED index is not valid in the keymap, returns -1.

See also: xkb_led_index_t

Data Structures

Enumerations

Functions

Detailed Description

Server State and Client State

Consumed Modifiers

Enumeration Type Documentation

◆ xkb_event_type

◆ xkb_state_component

◆ xkb_keyboard_control_flags

◆ xkb_events_flags

◆ xkb_machine_builder_flags

◆ xkb_a11y_flags

◆ xkb_key_direction

◆ xkb_layout_out_of_range_policy

◆ xkb_state_mode

◆ xkb_state_match

◆ xkb_consumed_mode

Function Documentation

◆ xkb_event_get_type()

◆ xkb_event_get_keycode()

◆ xkb_event_get_changed_components()

◆ xkb_event_serialize_enabled_controls()

◆ xkb_event_serialize_mods()

◆ xkb_event_serialize_layout()

◆ xkb_events_new_batch()

◆ xkb_events_destroy()

◆ xkb_events_next()

◆ xkb_machine_builder_new()

◆ xkb_machine_builder_destroy()

◆ xkb_machine_builder_get_keymap()

◆ xkb_machine_builder_update_a11y_flags()

◆ xkb_machine_builder_remap_mods()

◆ xkb_machine_builder_update_shortcut_mods()

◆ xkb_machine_builder_remap_shortcut_layout()

◆ xkb_machine_new()

◆ xkb_machine_ref()

◆ xkb_machine_unref()

◆ xkb_machine_get_keymap()

◆ xkb_machine_process_key()

◆ xkb_machine_process_synthetic()

◆ xkb_state_new_with_mode()

◆ xkb_state_new()

◆ xkb_state_ref()

◆ xkb_state_unref()

◆ xkb_state_get_keymap()

◆ xkb_state_update_mask()

◆ xkb_state_update_event()

◆ xkb_state_update_key()

◆ xkb_state_update_synthetic()

◆ xkb_state_update_latched_locked()

◆ xkb_state_key_get_syms()

◆ xkb_state_key_get_utf8()

◆ xkb_state_key_get_utf32()

◆ xkb_state_key_get_one_sym()

◆ xkb_state_key_get_layout()

◆ xkb_state_key_get_level()

◆ xkb_state_serialize_enabled_controls()

◆ xkb_state_serialize_mods()

◆ xkb_state_serialize_layout()

◆ xkb_state_mod_name_is_active()

◆ xkb_state_mod_names_are_active()

◆ xkb_state_mod_index_is_active()

◆ xkb_state_mod_indices_are_active()

◆ xkb_state_key_get_consumed_mods2()

◆ xkb_state_key_get_consumed_mods()

◆ xkb_state_mod_index_is_consumed2()

◆ xkb_state_mod_index_is_consumed()

◆ xkb_state_mod_mask_remove_consumed()

◆ xkb_state_layout_name_is_active()

◆ xkb_state_layout_index_is_active()

◆ xkb_state_led_name_is_active()

◆ xkb_state_led_index_is_active()