xkb_machine Struct Reference

#include <xkbcommon.h>

Public Member Functions
XKB_EXPORT struct xkb_machine *	xkb_machine_new (const struct xkb_machine_builder *builder, enum xkb_status *status)
XKB_EXPORT struct xkb_machine *	xkb_machine_ref (struct xkb_machine *machine)
XKB_EXPORT void	xkb_machine_unref (struct xkb_machine *machine)
XKB_EXPORT struct xkb_keymap *	xkb_machine_get_keymap (const struct xkb_machine *machine)
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)
XKB_EXPORT enum xkb_status	xkb_machine_process_synthetic (struct xkb_machine *machine, const struct xkb_synthetic_update *update, struct xkb_events *events)

Detailed Description

Opaque XKB state machine object.

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. Output depends on both the input and the current internal state (active modifiers, current layout, etc.).

This is the authoritative object for server-side XKB processing.

Automatic behavior fixes

xkbcommon automatically fixes some usual shortcomings of classic XKB:

Automatic behavior fixes

Title

Description

Layout switch on modifier key

Enables modifier-based layout switching (such as Alt+Shift) to function both as a standalone switch when pressed and released alone, and as a modifier in keyboard shortcuts when combined with other keys. Note This feature requires the xkb_machine API. Under the hood, this performs the following adjustments: Add `lockOnRelease=true` to `LockGroup` actions that satisfy the following conditions: it has no explicit `lockOnRelease`; it is located on a level ≥ 2 (1-indexed); it is the sole action of the level; it is located on a key with [SetMods][SetMods] as the sole action of its level 1. Append the modifier action of level 1 after the `LockGroup` action modified hereinbefore. It may be deactivated using: XKB_MACHINE_DISABLE_LAYOUT_SWITCH_ON_MODIFIER_KEY_FIX.

Query the keyboard state

Note

To query the resulting keyboard state (active modifiers, current layout, LED states, etc.), pair this object with an xkb_state created via xkb_state::xkb_state_new_from_machine() and updated via xkb_state::xkb_state_update_event(). The xkb_state object is the observable state of the machine and provides the full query API.

See Server State and Client State for details.

Examples

See the example for a Wayland server in the quick guide.

Ownership:

_Shared_ ownership using reference counting. Heap-allocated by xkb_machine_new(), which creates the first reference. Take additional references with xkb_machine_ref() and release each of them with exactly one xkb_machine_unref() call. The object is destroyed once its last reference has been released.

Owns a reference to the xkb_keymap passed during initialization, kept for the entire lifetime of the xkb_machine instance and released when calling xkb_machine_unref().

Invariant

The referenced xkb_keymap remains valid for the entire lifetime of an xkb_machine instance thanks to reference counting on xkb_keymap. You may release your own reference as soon as the xkb_machine is created.

Since

1.14.0

---

The documentation for this struct was generated from the following file:

• include/xkbcommon/xkbcommon.h