 |
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_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_synthetic_update |
| struct | xkb_machine |
| struct | xkb_machine_builder |
Enumerations | |
| enum | xkb_machine_builder_flags { XKB_MACHINE_BUILDER_NO_FLAGS = 0 } |
| enum | xkb_machine_flags { XKB_MACHINE_NO_FLAGS = 0 , XKB_MACHINE_SERVER_ACTIONS = (1 << 0) , XKB_MACHINE_DISABLE_LAYOUT_SWITCH_ON_MODIFIER_KEY_FIX = (1 << 1) , XKB_MACHINE_UNLOCK_MODS_ON_PRESS = (1 << 2) } |
| enum | xkb_a11y_flags { XKB_A11Y_NO_FLAGS = 0 , XKB_A11Y_STICKY_KEYS_NO_SIMULTANEOUS_KEYS = (1 << 0) , XKB_A11Y_STICKY_KEYS_LATCH_TO_LOCK = (1 << 1) , XKB_A11Y_LATCH_SIMULTANEOUS_KEYS = (1 << 2) } |
| enum | xkb_layout_out_of_range_policy { XKB_LAYOUT_OUT_OF_RANGE_WRAP = 0 , XKB_LAYOUT_OUT_OF_RANGE_CLAMP , XKB_LAYOUT_OUT_OF_RANGE_REDIRECT } |
Creating, destroying and manipulating server state machine.
| 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.
|
| XKB_MACHINE_DISABLE_LAYOUT_SWITCH_ON_MODIFIER_KEY_FIX | Disable automated fix for keys combining modifiers and layout switch. This flag is intended for debugging. See Automatic behavior fixes for further details.
|
| XKB_MACHINE_UNLOCK_MODS_ON_PRESS | Make modifier actions unlock on key press rather than the default on key release. It makes `SetMods(…, clearLocks)`, `LatchMods(…, clearLocks)` and `LockMods(…, affect=unlock)` act if `unlockOnPress=true` for actions without an explicit `unlockOnPress` parameter.
|
| 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_LATCH_TO_LOCK | If both 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
|
Policies defining how to bring out-of-range layout indices into range.
struct xkb_synthetic_update xkb_machine::xkb_machine_process_synthetic()| 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.
|
| XKB_EXPORT struct xkb_machine_builder * xkb_machine_builder_new | ( | struct xkb_keymap * | keymap, |
| const struct xkb_machine_builder_config * | config, | ||
| enum xkb_status * | status | ||
| ) |
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. Shared ownership: the returned xkb_machine takes a new reference on this parameter. |
| [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] | status | Pointer to store the resulting status code, or NULL if not needed. |
config must point to a zero-initialized struct with `config->size` set per Extensible structure ABI contract.xkb_machine builder object, or NULL on failure.status is not NULL, *status is set to XKB_SUCCESS on success or to an error code corresponding to the failure. Possible errors are:
struct xkb_machine_builder_config xkb_machine_builder_ref() xkb_machine_builder_unref() xkb_machine::xkb_machine_new()| 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_machine_builder_new() when creating this xkb_machine_builder object.xkb_machine_builder object.| XKB_EXPORT enum xkb_status 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_SUCCESS on success, otherwise an error code. Possible errors are:XKB_ERROR_UNSUPPORTED_A11Y_FLAGSstruct xkb_machine_builder_a11y_update| XKB_EXPORT enum xkb_status 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_SUCCESS on success, otherwise an error code. Possible errors are:
struct xkb_machine_builder_mods_remap_update| XKB_EXPORT enum xkb_status 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_SUCCESS on success, otherwise an error code. Possible errors are:
struct xkb_machine_builder_shortcut_override_update| XKB_EXPORT struct xkb_machine * xkb_machine_new | ( | const struct xkb_machine_builder * | builder, |
| enum xkb_status * | status | ||
| ) |
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] | status | Pointer to store the resulting status code, or NULL if not needed. |
NULL on failure. The returned xkb_machine shares ownership of the xkb_keymap associated with builder via a new reference.status is not NULL, *status is set to XKB_SUCCESS on success or to an error code corresponding to the failure. Possible errors are:
| 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_machine object, i.e. the keymap passed to xkb_machine_builder::xkb_machine_builder_new() when creating the corresponding builder used in xkb_machine_new().xkb_machine object.| XKB_EXPORT enum xkb_status 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_SUCCESS on success, otherwise an error code.xkb_machine_process_synthetic()| XKB_EXPORT enum xkb_status xkb_machine_process_synthetic | ( | struct xkb_machine * | machine, |
| const struct xkb_synthetic_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().
xkb_layout_out_of_range_policy). | [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_SUCCESS on success, otherwise an error code. Possible errors are:
struct xkb_synthetic_update struct xkb_state_components_update struct xkb_layout_policy_update xkb_machine_process_key()
1.9.8