 |
xkbcommon 1.14.0-beta2
Reference library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state
|
|
xkbcommon 1.14.0-beta2
Reference library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state
|
Data Structures | |
| struct | xkb_event_components |
| struct | xkb_event_pointer_motion |
| struct | xkb_event_pointer_button |
| struct | xkb_events_config |
| struct | xkb_machine_builder_config |
| struct | xkb_machine_builder_a11y_update |
| struct | xkb_machine_builder_mods_remap_update |
| struct | xkb_machine_builder_shortcut_override_update |
| 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 |
Creating, destroying and manipulating keyboard state objects.
There are two distinct actors in most window-system architectures:
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.
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:
This is the recommended API for server applications. It enables the full feature set that xkbcommon 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:
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.
This is the API for client applications and the legacy API for server applications.
See the examples for clients in the quick guide.
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:
In summary, this is approximately how the matching would be performed:
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.
| enum xkb_event_type |
Denotes the type of a state event.
| Enumerator | |
|---|---|
| XKB_EVENT_TYPE_INVALID | Invalid event. This is not a real event type but an error indicator.
|
| XKB_EVENT_TYPE_KEY | Key event
|
| XKB_EVENT_TYPE_STATE_COMPONENTS | State components change event
|
| XKB_EVENT_TYPE_POINTER_MOTION | Pointer motion event
|
| XKB_EVENT_TYPE_POINTER_BUTTON | Pointer button event
|
| XKB_EVENT_TYPE_TERMINATE_DISPLAY_SERVER | Terminate display server event This event is only generated by a state machine if it was created with XKB_MACHINE_SERVER_ACTIONS set. See xkb_machine_builder_config::machine_flags for further details.
|
| XKB_EVENT_TYPE_SWITCH_VIRTUAL_CONSOLE | Switch virtual console event This event is only generated by a state machine if it was created with XKB_MACHINE_SERVER_ACTIONS set. See xkb_machine_builder_config::machine_flags for further details.
|
| enum xkb_key_direction |
| 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_NO_COMPONENT | Represents the empty set of state components. This is the identity value for state component bitmask operations. It corresponds also to the result of updates operation when the state components remain unchanged.
|
| 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 | Effective keyboard controls.
|
Boolean global keyboard controls, which affect the way xkbcommon handles the keyboard as a whole.
This enumeration is bit-maskable.
| Enumerator | |
|---|---|
| XKB_KEYBOARD_CONTROL_NO_FLAGS | Do not apply any control.
|
| 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.
|
| XKB_KEYBOARD_CONTROL_MOUSE_KEYS | Enable mouse keys for controlling the mouse functions from the keyboard. When mouse keys are enabled, all keys with pointer actions bound to them generate pointer events instead of normal key press and release events.
|
Pointer motion flags for xkb_event_pointer_motion.
| Enumerator | |
|---|---|
| XKB_POINTER_MOTION_NO_FLAGS | Do not apply any flags; the corresponding pointer motion:
|
| XKB_POINTER_MOTION_REPEATS | The pointer motion repeats.
|
| XKB_POINTER_MOTION_ABSOLUTE_X | The x coordinate is absolute.
|
| XKB_POINTER_MOTION_ABSOLUTE_Y | The y coordinate is absolute.
|
Specifies the direction of a button (press/release).
| Enumerator | |
|---|---|
| XKB_POINTER_BUTTON_DOWN | The pointer button was pressed.
|
| XKB_POINTER_BUTTON_UP | The pointer button was released.
|
| XKB_POINTER_BUTTON_CLICK | The pointer button was clicked (pressed then released). Equals XKB_POINTER_BUTTON_DOWN | XKB_POINTER_BUTTON_UP.
|
| enum xkb_events_flags |
Flags for xkb_events_config::flags.
| Enumerator | |
|---|---|
| XKB_EVENTS_NO_FLAGS | Do not apply any flags: the corresponding event collection will behave as a batch of events.
|
| enum xkb_machine_flags |
Flags for xkb_machine_builder_config::machine_flags.
| Enumerator | |
|---|---|
| XKB_MACHINE_NO_FLAGS | Do not apply any flags.
|
| XKB_MACHINE_SERVER_ACTIONS | Enable server actions. When this flag is enabled, all keys with server actions bound to them generate server events instead of usual key press and release events.
|
| enum xkb_a11y_flags |
Flags for xkb_machine_builder_a11y_update::flags.
These flags configure the accessibility (a11y) features.
| Enumerator | |
|---|---|
| XKB_A11Y_NO_FLAGS | Do not apply any flags.
|
| 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.
|
| 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.
|
| XKB_A11Y_LATCH_SIMULTANEOUS_KEYS | Without this option, the latch keys are only triggers if keys are strictly sequentially tapped, e.g.:
If one wants multiple active latches, they must be tapped in sequence: e.g.:
This option relaxes the strict sequence requirement and enables operating keys that do not break latches simultaneously with a latch key, e.g.:
This is an extension to the X11 XKB protocol and is enabled by default when using XKB_KEYMAP_FORMAT_TEXT_V2.
|
Policies defining how to bring out-of-range layout indices into range.
| Enumerator | |
|---|---|
| XKB_LAYOUT_OUT_OF_RANGE_WRAP | Wrap into range using integer modulus (default).
|
| 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).
|
| XKB_LAYOUT_OUT_OF_RANGE_REDIRECT | Redirect to a specific layout index.
|
| enum xkb_state_mode |
Mode for creating a keyboard state object.
| 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().
|
| 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().
|
| 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.
|
| 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.
| 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:
|
| XKB_EXPORT enum xkb_event_type xkb_event_get_type | ( | const struct xkb_event * | event | ) |
Get the type of an event.
| [in] | event | The event to process. |
| XKB_EXPORT enum xkb_error_code xkb_event_get_keycode | ( | const struct xkb_event * | event, |
| xkb_keycode_t * | keycode, | ||
| enum xkb_key_direction * | direction ) |
Get the keycode and direction associated to a state event of type XKB_EVENT_TYPE_KEY.
| [in] | event | The event object to process. |
| [out] | keycode | A pointer to store the keycode of the key event. |
| [out] | direction | A pointer to store the direction of the key event. |
keycode and direction are not updated.| XKB_EXPORT enum xkb_error_code xkb_event_get_components | ( | const struct xkb_event * | event, |
| struct xkb_event_components * | components ) |
Serialization of the state components corresponding to a state event of type XKB_EVENT_TYPE_STATE_COMPONENTS.
| [in] | event | The event object to process. |
| [in,out] | components | A pointer to an event components object to update with the event. |
components is not updated.components must point to a zero-initialized struct with components->size set per Extensible structure ABI contract.components that fall within components->size.| XKB_EXPORT enum xkb_error_code xkb_event_get_pointer_motion | ( | const struct xkb_event * | event, |
| struct xkb_event_pointer_motion * | motion ) |
Get the pointer motion corresponding to a state event of type XKB_EVENT_TYPE_POINTER_MOTION.
| [in] | event | The event object to process. |
| [in,out] | motion | A pointer to a pointer motion object to update with the event. |
motion is not updated.motion must point to a zero-initialized struct with motion->size set per Extensible structure ABI contract.motion that fall within motion->size.| XKB_EXPORT enum xkb_error_code xkb_event_get_pointer_button | ( | const struct xkb_event * | event, |
| struct xkb_event_pointer_button * | button ) |
Get the pointer button corresponding to a state event of type XKB_EVENT_TYPE_POINTER_BUTTON.
| [in] | event | The event object to process. |
| [in,out] | button | A pointer to a pointer button object to update with the event. |
button is not updated.button must point to a zero-initialized struct with button->size set per Extensible structure ABI contract.button that fall within button->size.| XKB_EXPORT enum xkb_error_code xkb_event_get_virtual_console | ( | const struct xkb_event * | event, |
| int8_t * | index_or_offset, | ||
| bool * | is_offset ) |
Get the virtual console index or offset associated to a state event of type XKB_EVENT_TYPE_SWITCH_VIRTUAL_CONSOLE.
| [in] | event | The event object to process. |
| [out] | index_or_offset | A pointer to store the absolute or relative virtual console target. |
| [out] | is_offset | A pointer to store whether index_or_offset is an index (false) or an offset (true). |
index_or_offset and is_offset are not updated.| XKB_EXPORT struct xkb_events * xkb_events_new | ( | struct xkb_context * | context, |
| const struct xkb_events_config * | config, | ||
| enum xkb_error_code * | error ) |
Create a new event collection object.
| [in] | context | The context in which to create the object. |
| [in] | config | Configuration to control the collection behavior, or NULL for the defaults: an xkb_events_config struct with size set per Extensible structure ABI contract and all other fields zeroed. |
| [out] | error | Pointer to store the resulting error code, or NULL if not needed. |
config must point to a zero-initialized struct with config->size set per Extensible structure ABI contract.| XKB_EXPORT struct xkb_events * xkb_events_ref | ( | struct xkb_events * | events | ) |
Take a new reference on an event collection object.
| [in] | events | The collection to reference. |
| XKB_EXPORT void xkb_events_unref | ( | struct xkb_events * | events | ) |
Release a reference on an event collection object, and possibly free it.
| [in] | events | The event collection object. If it is NULL, this function does nothing. |
| XKB_EXPORT const struct xkb_event * xkb_events_next | ( | struct xkb_events * | events | ) |
| XKB_EXPORT struct xkb_machine_builder * xkb_machine_builder_new | ( | struct xkb_keymap * | keymap, |
| const struct xkb_machine_builder_config * | config, | ||
| enum xkb_error_code * | error ) |
Create a new xkb_machine builder object.
xkb_machine objects can then be created from the builder using xkb_machine::xkb_machine_new().
| [in] | keymap | The keymap which the state machine will use. |
| [in] | config | Configuration to control the builder behavior, or NULL for the defaults: an xkb_machine_builder_config struct with size set per Extensible structure ABI contract and all other fields zeroed. |
| [out] | error | Pointer to store the resulting error code, or NULL if not needed. |
config must point to a zero-initialized struct with config->size set per Extensible structure ABI contract.| XKB_EXPORT struct xkb_machine_builder * xkb_machine_builder_ref | ( | struct xkb_machine_builder * | builder | ) |
Take a new reference on an xkb_machine builder object.
| [in] | builder | The builder to reference. |
| XKB_EXPORT void xkb_machine_builder_unref | ( | struct xkb_machine_builder * | builder | ) |
Release a reference on an xkb_machine builder object, and possibly free it.
| [in] | builder | The xkb_machine builder. If it is NULL, this function does nothing. |
| 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.
| [in] | builder | The state machine builder object. |
| XKB_EXPORT enum xkb_error_code xkb_machine_builder_update_a11y | ( | struct xkb_machine_builder * | builder, |
| const struct xkb_machine_builder_a11y_update * | update ) |
Update the accessibility flags of an xkb_machine_builder object.
| [in,out] | builder | The xkb_machine builder object to modify. |
| [in] | update | Accessibility update object. |
update must point to a zero-initialized struct with update->size set per Extensible structure ABI contract.| XKB_EXPORT enum xkb_error_code xkb_machine_builder_update_mods_remap | ( | struct xkb_machine_builder * | builder, |
| const struct xkb_machine_builder_mods_remap_update * | update ) |
Update the modifiers remapping of an xkb_machine_builder object.
| [in,out] | builder | The xkb_machine builder object to modify. |
| [in] | update | Modifiers remapping update object. |
update must point to a zero-initialized struct with update->size set per Extensible structure ABI contract.| XKB_EXPORT enum xkb_error_code xkb_machine_builder_update_shortcut_override | ( | struct xkb_machine_builder * | builder, |
| const struct xkb_machine_builder_shortcut_override_update * | update ) |
Update layout substitution of the shortcut layout overrides.
| [in,out] | builder | The xkb_machine builder object to modify. |
| [in] | update | Shortcut layout substitution update object. |
update must point to a zero-initialized struct with update->size set per Extensible structure ABI contract.| XKB_EXPORT struct xkb_machine * xkb_machine_new | ( | const struct xkb_machine_builder * | builder, |
| enum xkb_error_code * | error ) |
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.
| [in] | builder | The builder object from which to create the state machine. |
| [out] | error | Pointer to store the resulting error code, or NULL if not needed. |
| XKB_EXPORT struct xkb_machine * xkb_machine_ref | ( | struct xkb_machine * | machine | ) |
Take a new reference on a xkb_machine object.
| [in] | machine | The state machine. |
| XKB_EXPORT void xkb_machine_unref | ( | struct xkb_machine * | machine | ) |
Release a reference on a xkb_machine object, and possibly free it.
| [in] | machine | The state machine. If it is NULL, this function does nothing. |
| XKB_EXPORT struct xkb_keymap * xkb_machine_get_keymap | ( | const struct xkb_machine * | machine | ) |
Get the keymap which a xkb_machine object is using.
| [in] | machine | The state machine. |
| 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.
| [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. |
| 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_STATE_COMPONENTS 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().
| [in,out] | machine | The XKB state machine object. |
| [in] | update | The update to apply. |
| [out] | events | The event batch to collect events into. It will be reset before collecting. |
update must point to a zero-initialized struct with update->size set per Extensible structure ABI contract.| XKB_EXPORT struct xkb_state * xkb_state_new_with_mode | ( | struct xkb_keymap * | keymap, |
| enum xkb_state_mode | mode, | ||
| enum xkb_error_code * | error ) |
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.
| [in] | keymap | The keymap which the state will use. |
| [in] | mode | The state mode to use. |
| [out] | error | Pointer to store the resulting error code, or NULL if not needed. |
| XKB_EXPORT struct xkb_state * xkb_state_new_from_machine | ( | const struct xkb_machine * | machine, |
| enum xkb_error_code * | error ) |
Create a new keyboard state object as an observer of an xkb_machine.
Constructor for server applications using the xkb_machine API:
machine’s keymap;machine’s state. See Server State and Client State for further information.| [in] | machine | The state machine whose keymap the new state will use. |
| [out] | error | Pointer to store the resulting error code, or NULL if not needed. |
| XKB_EXPORT struct xkb_state * xkb_state_new | ( | struct xkb_keymap * | keymap | ) |
Create a new keyboard state object.
| [in] | keymap | The keymap which the state will use. |
Take a new reference on a keyboard state object.
| [in] | state | The state to reference. |
| XKB_EXPORT void xkb_state_unref | ( | struct xkb_state * | state | ) |
Release a reference on a keyboard state object, and possibly free it.
| [in] | state | The state. If it is NULL, this function does nothing. |
| XKB_EXPORT struct xkb_keymap * xkb_state_get_keymap | ( | struct xkb_state * | state | ) |
Get the keymap which a keyboard state object is using.
| [in] | state | The keyboard state object. |
| 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.
| [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. |
locked_layout, while depressed_layout and latched_layout are both set to 0.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.| XKB_EXPORT enum xkb_error_code xkb_state_update_event | ( | struct xkb_state * | state, |
| const struct xkb_event * | event, | ||
| enum xkb_state_component * | changed ) |
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.
| [in,out] | state | The keyboard state object. |
| [in] | event | The state event to update from. |
| [out] | changed | A pointer to the mask of state components that have changed as a result of the update, or NULL to ignore. If nothing in the state has changed, the mask is set to 0 (XKB_STATE_NO_COMPONENT). |
state must be created with xkb_state_new_from_machine() (i.e. with mode XKB_STATE_MODE_SERVER_QUERY) or xkb_state_new(), otherwise the call is rejected without updating the state and the misuse is logged as XKB_ERROR_UNEXPECTED_STATE_MODE.state was not created with XKB_STATE_MODE_SERVER_QUERY or xkb_state_new().changed parameter.| 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.
| [in,out] | state | The keyboard state object. |
| [in] | key | The key being operated. |
| [in] | direction | The direction of the key operation. |
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.| 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.
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().
| [in,out] | state | The keyboard state object. |
| [in] | update | The update to apply. |
| [out] | changed | A pointer to the mask of state components that have changed as a result of the update, or NULL to ignore. If nothing in the state has changed, the mask is set to 0 (XKB_STATE_NO_COMPONENT). |
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.update must point to a zero-initialized struct with update->size set per Extensible structure ABI contract.state was not created with XKB_STATE_MODE_SERVER or xkb_state_new().changed parameter.| 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.
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.
| [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. |
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.| 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.
| [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 performs Capitalization Keysym Transformations.
| 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.
| [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. |
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.
| 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.
| [in] | state | The keyboard state object. |
| [in] | key | The keycode of the key. |
This function performs Capitalization and Control Keysym Transformations.
| 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).
| [in] | state | The keyboard state object. |
| [in] | key | The keycode of the key. |
This function performs Capitalization Keysym Transformations.
| 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.
| [in] | state | The keyboard state object. |
| [in] | key | The keycode of the key. |
| 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.
| [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) |
| 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.
| [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. |
components.| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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 modifier names to test, terminated by a NULL argument (sentinel). |
match contains invalid flags, returns -2.match flags | 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.
| [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. |
| 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.
| [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 modifier indices to test, terminated by a XKB_MOD_INVALID argument (sentinel). |
match contains invalid flags, returns -2.match flags | 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.
| [in] | state | The keyboard state. |
| [in] | key | The keycode of the key. |
| [in] | mode | The consumed modifiers mode to use; see enum description. |
| 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.
| 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.
| [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. |
| 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.
| 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.
Takes the given modifier mask, and removes all modifiers which are consumed for that particular key (as in xkb_state_mod_index_is_consumed()).
| 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.
| [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. |
If multiple layouts in the keymap have this name, the one with the lowest index is tested.
| 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.
| [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. |
| 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.
| [in] | state | The keyboard state. |
| [in] | name | The LED name to test (NULL-terminated string). |
| 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.
| [in] | state | The keyboard state. |
| [in] | idx | The LED index to test. |
1.19.0