Creating, destroying and manipulating keyboard state objects. More...

Enumerations
enum	xkb_key_direction { XKB_KEY_UP, XKB_KEY_DOWN }
	Specifies the direction of the key (press / release). More...
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) }
	Modifier and layout types for state objects. More...
enum	xkb_state_match { XKB_STATE_MATCH_ANY = (1 << 0), XKB_STATE_MATCH_ALL = (1 << 1), XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16) }
	Match flags for xkb_state_mod_indices_are_active and xkb_state_mod_names_are_active, specifying how the conditions for a successful match. More...

Functions
struct xkb_state *	xkb_state_new (struct xkb_keymap *keymap)
	Create a new keyboard state object for a keymap.
struct xkb_state *	xkb_state_ref (struct xkb_state *state)
	Take a new reference on a keyboard state object.
void	xkb_state_unref (struct xkb_state *state)
	Release a reference on a keybaord state object, and possibly free it.
struct xkb_keymap *	xkb_state_get_keymap (struct xkb_state *state)
	Get the keymap from which a keyboard state object was created.
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.
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.
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.
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_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.
enum xkb_state_component	xkb_state_update_mask (struct xkb_state *state, xkb_mod_mask_t depressed_mods, xkb_mod_mask_t latched_mods, xkb_mod_mask_t locked_mods, xkb_layout_index_t depressed_layout, xkb_layout_index_t latched_layout, xkb_layout_index_t locked_layout)
	Update a keyboard state from a set of explicit masks.
xkb_mod_mask_t	xkb_state_serialize_mods (struct xkb_state *state, enum xkb_state_component components)
	The counterpart to xkb_state_update_mask for modifiers, to be used on the server side of serialization.
xkb_layout_index_t	xkb_state_serialize_layout (struct xkb_state *state, enum xkb_state_component components)
	The counterpart to xkb_state_update_mask for layouts, to be used on the server side of serialization.
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.
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.
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.
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.
int	xkb_state_mod_index_is_consumed (struct xkb_state *state, xkb_keycode_t key, xkb_mod_index_t idx)
	Test whether a modifier is consumed by keyboard state translation for a key.
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.
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.
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.
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.
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.

Detailed Description

Creating, destroying and manipulating keyboard state objects.

Enumeration Type Documentation

enum xkb_key_direction

Specifies the direction of the key (press / release).

Enumerator:

XKB_KEY_UP	The key was released.
XKB_KEY_DOWN	The key was pressed.

enum xkb_state_component

Modifier and layout types for state objects.

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).
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).
XKB_STATE_LEDS	LEDs (derived from the other state components).

enum xkb_state_match

Match flags for xkb_state_mod_indices_are_active and xkb_state_mod_names_are_active, specifying how 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.

Function Documentation

struct xkb_state * xkb_state_new ( struct xkb_keymap * keymap )

read

Create a new keyboard state object for a keymap.

Parameters

keymap The keymap for which to create the state.

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

struct xkb_state * xkb_state_ref ( struct xkb_state * state )

read

Take a new reference on a keyboard state object.

Returns: The passed in object.

struct xkb_keymap * xkb_state_get_keymap ( struct xkb_state * state )

read

Get the keymap from which a keyboard state object was created.

Returns: The keymap which was used in xkb_state_new() to create this state object.

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.

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.

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

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 immutible 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().

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.

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 with a simplified interface for users which cannot or do not want to handle the case where multiple keysyms are returned.

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

See Also: xkb_state_key_get_syms()

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.

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

state	The keyboard state.
key	The keycode of the key.
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)

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 entrypoint is really only for window systems and the like, where a master process holds an xkb_state, then serializes it over a wire protocol, and clients then use the serialization to feed in to their own xkb_state.

All parameters must always be passed, or the resulting state may be incoherent.

The serialization is lossy and will not survive round trips; it must only be used to feed slave state objects, and must not be used to update the master state.

Please do not use this unless you fit the description above.

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

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

The counterpart to xkb_state_update_mask for modifiers, to be used on the server side of serialization.

Parameters

state	The keyboard state.
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.

This function should not be used in regular clients; please use the xkb_state_mod_*_is_active API instead.

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

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

Parameters

state	The keyboard state.
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 xkb_layout_mask_t representing the given components of the layout state.

This function should not be used in regular clients; please use the xkb_state_layout_*_is_active API instead.

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.

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

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.

Parameters

state	The keyboard state.
type	The component of the state against which to match the given modifiers.
match	The manner by which to match the state against the given modifiers.
...	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.

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.

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

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.

Parameters

state	The keyboard state.
type	The component of the state against which to match the given modifiers.
match	The manner by which to match the state against the given modifiers.
...	The set of of modifier indexes 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 indexes are invalid in the keymap, returns -1.

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

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

Some functions, like 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 active, so it is not consumed by this translation.

It may be desireable for some application to not reuse consumed modifiers for further processing, e.g. for hotkeys or keyboard shortcuts.

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

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.

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

See Also: xkb_state_mod_index_is_consumed()

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.

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

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.

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

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.

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

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.

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

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation