libxkbcommon  0.5.0
Enumerations | Functions
Keyboard State

Enumerations

enum  xkb_key_direction {
  XKB_KEY_UP,
  XKB_KEY_DOWN
}
 
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)
}
 
enum  xkb_state_match {
  XKB_STATE_MATCH_ANY = (1 << 0),
  XKB_STATE_MATCH_ALL = (1 << 1),
  XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16)
}
 

Functions

struct xkb_statexkb_state::xkb_state_new (struct xkb_keymap *keymap)
 
struct xkb_statexkb_state::xkb_state_ref (struct xkb_state *state)
 
void xkb_state::xkb_state_unref (struct xkb_state *state)
 
struct xkb_keymapxkb_state::xkb_state_get_keymap (struct xkb_state *state)
 
enum xkb_state_component xkb_state::xkb_state_update_key (struct xkb_state *state, xkb_keycode_t key, enum xkb_key_direction direction)
 
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)
 
int xkb_state::xkb_state_key_get_syms (struct xkb_state *state, xkb_keycode_t key, const xkb_keysym_t **syms_out)
 
int xkb_state::xkb_state_key_get_utf8 (struct xkb_state *state, xkb_keycode_t key, char *buffer, size_t size)
 
uint32_t xkb_state::xkb_state_key_get_utf32 (struct xkb_state *state, xkb_keycode_t key)
 
xkb_keysym_t xkb_state::xkb_state_key_get_one_sym (struct xkb_state *state, xkb_keycode_t key)
 
xkb_layout_index_t xkb_state::xkb_state_key_get_layout (struct xkb_state *state, xkb_keycode_t key)
 
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_mod_mask_t xkb_state::xkb_state_serialize_mods (struct xkb_state *state, enum xkb_state_component components)
 
xkb_layout_index_t xkb_state::xkb_state_serialize_layout (struct xkb_state *state, enum xkb_state_component components)
 
int xkb_state::xkb_state_mod_name_is_active (struct xkb_state *state, const char *name, enum xkb_state_component type)
 
int xkb_state::xkb_state_mod_names_are_active (struct xkb_state *state, enum xkb_state_component type, enum xkb_state_match match,...)
 
int xkb_state::xkb_state_mod_index_is_active (struct xkb_state *state, xkb_mod_index_t idx, enum xkb_state_component type)
 
int xkb_state::xkb_state_mod_indices_are_active (struct xkb_state *state, enum xkb_state_component type, enum xkb_state_match match,...)
 
int xkb_state::xkb_state_mod_index_is_consumed (struct xkb_state *state, xkb_keycode_t key, xkb_mod_index_t idx)
 
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_mod_mask_t xkb_state::xkb_state_key_get_consumed_mods (struct xkb_state *state, xkb_keycode_t key)
 
int xkb_state::xkb_state_layout_name_is_active (struct xkb_state *state, const char *name, enum xkb_state_component type)
 
int xkb_state::xkb_state_layout_index_is_active (struct xkb_state *state, xkb_layout_index_t idx, enum xkb_state_component type)
 
int xkb_state::xkb_state_led_name_is_active (struct xkb_state *state, const char *name)
 
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.

Consumed Modifiers

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

  1. 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 (==).
  2. 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.
  3. 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 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_mod_index_is_active() and similar functions. consumed_mods are the modifiers reported by 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

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

Enumerator
XKB_KEY_UP 

The key was released.

XKB_KEY_DOWN 

The key was pressed.

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). Use this unless you explictly 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 explictly care how the state came about.

XKB_STATE_LEDS 

LEDs (derived from the other state components).

Match flags for xkb_state_mod_indices_are_active() and 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.

Function Documentation

struct xkb_state * xkb_state_new ( struct xkb_keymap keymap)

Create a new keyboard state object.

Parameters
keymapThe keymap which the state will use.
Returns
A new keyboard state object, or NULL on failure.
struct xkb_state * xkb_state_ref ( struct xkb_state state)

Take a new reference on a keyboard state object.

Returns
The passed in object.
void xkb_state_unref ( struct xkb_state state)

Release a reference on a keybaord state object, and possibly free it.

Parameters
stateThe state. If it is NULL, this function does nothing.
struct xkb_keymap * xkb_state_get_keymap ( struct xkb_state state)

Get the keymap which a keyboard state object is using.

Returns
The keymap which was passed to xkb_state_new() when creating 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.

This entry point is intended for programs which track the keyboard state explictly (like an evdev client). If the state is serialized to you by a master process (like a Wayland compositor) using functions like xkb_state_serialize_mods(), you should use xkb_state_update_mask() instead. The two functins should not generally be used together.

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.

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

If you do not fit the description above, you should use xkb_state_update_key() instead. The two functions should not generally be used together.

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_key
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]stateThe keyboard state object.
[in]keyThe keycode of the key.
[out]syms_outAn 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.

This function does not perform any Keysym Transformations. (This might change).

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.
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]stateThe keyboard state object.
[in]keyThe keycode of the key.
[out]bufferA buffer to write the string into.
[in]sizeSize of the buffer.
Warning
If the buffer passed is too small, the string is truncated (though still NUL-terminated).
Returns
The number of bytes required for the string, excluding the NUL 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 NUL-byte).

This function performs Capitalization and Control Keysym Transformations.

Since
0.4.1
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.

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

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_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
stateThe keyboard state.
keyThe keycode of the key.
layoutThe 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:
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_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
stateThe keyboard state.
componentsA 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
stateThe keyboard state.
componentsA 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.

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

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()
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()
xkb_mod_mask_t xkb_state_key_get_consumed_mods ( struct xkb_state state,
xkb_keycode_t  key 
)

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

Returns
a mask of the consumed modifiers.
See also
xkb_state_mod_index_is_consumed()
Since
0.4.1
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