 |
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
|
Modules | |
| Events | |
| Keyboard server state machine | |
| Keyboard state objects | |
Enumerations | |
| enum | xkb_key_direction { XKB_KEY_UP , XKB_KEY_DOWN , XKB_KEY_REPEATED } |
| enum | xkb_state_component { XKB_STATE_NO_COMPONENT = 0 , 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) , XKB_STATE_CONTROLS_EFFECTIVE = (1 << 12) } |
| enum | xkb_keyboard_control_flags { XKB_KEYBOARD_CONTROL_NO_FLAGS = 0 , XKB_KEYBOARD_CONTROL_A11Y_STICKY_KEYS = (1 << 0) , XKB_KEYBOARD_CONTROL_MOUSE_KEYS = (1 << 1) } |
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:
xkb_machine: the server API 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:
xkb_state::xkb_state_new_from_machine().xkb_state::xkb_state_update_event().xkb_state query API.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.
xkb_state: the client API (and legacy server API) This is the API for client applications and the legacy API for server applications.
xkb_state::xkb_state_new_with_mode() using XKB_STATE_MODE_CLIENT, then update it via xkb_state::xkb_state_update_mask() from server serializations. xkb_machine xkb_state::xkb_state_new_with_mode() using XKB_STATE_MODE_SERVER, or with the legacy xkb_state::xkb_state_new() constructor, then update it via xkb_state::xkb_state_update_key() for key events and xkb_state::xkb_state_update_synthetic() for out-of-band inputs such as layout switchers. xkb_state API are only meant for servers and some are only meant for clients. Thus it is recommended to use xkb_state::xkb_state_new_with_mode() because it enforces correct usage at runtime and logs misuse as XKB_ERROR_UNEXPECTED_STATE_MODE. Using xkb_state::xkb_state_new() does not enforce this: mixing entry points may lead to incorrect state.xkb_machine API, which supports more features.See the examples for clients in the quick guide.
| 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.
0x200..0x800 are reserved for future use. | 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_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.
|
1.9.8