libxkbcommon 1.7.0
|
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) } |
enum | xkb_consumed_mode { XKB_CONSUMED_MODE_XKB , XKB_CONSUMED_MODE_GTK } |
Creating, destroying and manipulating keyboard state objects.
The xkb_state API is used by two distinct actors in most window-system architectures:
A server - for example, a Wayland compositor, an X11 server, 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.
A client - for example, a Wayland client, 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.
Some entry points in the xkb_state API are only meant for servers and some are only meant for clients, and the two should generally not be mixed.
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:
In summary, this is approximately how the matching would be performed:
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.
enum xkb_key_direction |
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'.
enum xkb_state_match |
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.
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 |
XKB_CONSUMED_MODE_GTK | This is the mode used by the GTK+ toolkit. The mode consists of the following two independent heuristics:
|
struct xkb_state * xkb_state_new | ( | struct xkb_keymap * | keymap | ) |
Create a new keyboard state object.
keymap | The keymap which the state will use. |
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.
state | The 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.
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 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.
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 xkb_state_update_key() instead.
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 client state objects, and must not be used to update the server state.
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.
[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.
This function does not perform any Keysym Transformations. (This might change).
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.
[in] | state | The keyboard state object. |
[in] | key | The keycode of the key. |
[out] | buffer | A buffer to write the string into. |
[in] | size | Size of the buffer. |
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.
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.
This function performs Capitalization and Control Keysym Transformations.
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).
This function performs Capitalization Keysym Transformations.
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.
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)
xkb_state_key_get_layout(state, key)
|
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.
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.
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. |
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.
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.
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. |
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.
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). |
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.
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 indices to test, terminated by a XKB_MOD_INVALID argument (sentinel). |
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.
state | The keyboard state. |
key | The keycode of the key. |
mode | The consumed modifiers mode to use; see enum description. |
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.
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.
state | The keyboard state. |
key | The keycode of the key. |
idx | The index of the modifier to check. |
mode | The consumed modifiers mode to use; see enum description. |
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_MOD_XKB.
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()).
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.
If multiple layouts in the keymap have this name, the one with the lowest index is tested.
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.