Collaboration diagram for Keyboard state objects:

Modules
	Client keyboard state

	Server companion keyboard state

	Legacy keyboard state machine

Data Structures
struct	xkb_state

Enumerations
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 struct xkb_state *	xkb_state::xkb_state_new_with_mode (struct xkb_keymap keymap, enum xkb_state_mode mode, enum xkb_status status)

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 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_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 client, server companion and legacy server state.

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_state_mode

enum xkb_state_mode

Mode for creating a keyboard state object.

See also: xkb_state::xkb_state_new_with_mode()

Since: 1.14.0

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 using the xkb_machine API, 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)*

Warning: Do not pass this value to xkb_state::xkb_state_new_with_mode() directly, unless the corresponding xkb_machine has not processed any input event yet: the result would not be initialized from the machine’s current state, and cannot be brought back into sync afterward if the machine already processed events. Use xkb_state::xkb_state_new_from_machine() instead.

See also: struct xkb_machine; xkb_state::xkb_state_new_from_machine()

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_state_new_with_mode()

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

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. Borrowed: the returned `xkb_state` keeps a pointer to this parameter without taking ownership.
[in]	mode	The state mode to use.
[out]	status	Pointer to store the resulting status code, or `NULL` if not needed.

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

Postcondition

if status is not NULL, *status is set to XKB_SUCCESS on success or to an error code corresponding to the failure. Possible errors are:

See also: enum xkb_state_mode

Since: 1.14.0

◆ 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. Shared ownership: the returned xkb_state takes a new reference on this parameter.

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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Returns: The borrowed 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_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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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 given keyboard state.

Parameters

[in] state The keyboard state object.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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_controls()

XKB_EXPORT enum xkb_keyboard_control_flags xkb_state_serialize_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_EFFECTIVE` 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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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 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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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 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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]	key	The keycode of the key.
[in]	mode	The consumed modifiers mode to use; see the 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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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.
Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[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

Modules

Data Structures

Enumerations

Functions

Detailed Description

Consumed Modifiers

Enumeration Type Documentation

◆ xkb_state_mode

◆ xkb_state_match

◆ xkb_consumed_mode

Function Documentation

◆ xkb_state_new_with_mode()

◆ xkb_state_new()

◆ xkb_state_ref()

◆ xkb_state_unref()

◆ xkb_state_get_keymap()

◆ 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_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()