Collaboration diagram for Legacy keyboard state machine:

Functions
XKB_EXPORT enum xkb_state_component	xkb_state::xkb_state_update_key (struct xkb_state *state, xkb_keycode_t key, enum xkb_key_direction direction)

XKB_EXPORT enum xkb_status	xkb_state::xkb_state_update_synthetic (struct xkb_state state, const struct xkb_synthetic_update update, enum xkb_state_component *changed)

XKB_EXPORT enum xkb_state_component	xkb_state::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)

Detailed Description

Server-specific API.

Function Documentation

◆ xkb_state_update_key()

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.

Note: This is the legacy server entry point and only supports a restricted set of xkbcommon features. Since 1.14.0, prefer xkb_machine for new server applications to enable the full feature set.

Parameters

[in,out]	state	The keyboard state object.
[in]	key	The key being operated.
[in]	direction	The direction of the key operation.

@important If 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.

Returns: A mask of state components that have changed as a result of the update. If nothing in the state has changed, returns 0 (XKB_STATE_NO_COMPONENT).

See also: xkb_state_update_mask()

Since: 1.14.0: Reject call if the state mode is incorrect.

◆ xkb_state_update_synthetic()

XKB_EXPORT enum xkb_status xkb_state_update_synthetic	(	struct xkb_state *	state,
		const struct xkb_synthetic_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.

Use this function to update the keyboard state in response to out-of-band (non-device) inputs, such as UI layout switchers or accessibility settings changes.
Use xkb_state_update_key() instead for in-band (device) inputs.
Use xkb_state_update_event() instead when updating from an event produced by xkb_machine.

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().

Layout out of range: If the effective layout, after taking into account the depressed, latched and locked layout, is out of range (negative or greater than the maximum layout index), it is brought into range according to the current out-of-range layout policy (see xkb_layout_out_of_range_policy).

Note: This entry point serves the legacy server use case and only supports a restricted set of xkbcommon features. Since 1.14.0, prefer xkb_machine for new server applications to enable the full feature set.

Parameters

[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`).

@important If 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.

Precondition: update must point to a zero-initialized struct with `update->size` set per Extensible structure ABI contract.

Returns

XKB_SUCCESS on success;
XKB_ERROR_UNEXPECTED_STATE_MODE without updating the state if state was not created with XKB_STATE_MODE_SERVER or xkb_state_new().
Otherwise another error code.

Note: This function returns an error code rather than a state component delta (unlike other xkb_state_update_*() functions), in order to align with the xkb_machine::xkb_machine_process_synthetic() API. The delta is optionally available via the changed parameter.

See also: struct xkb_synthetic_update; xkb_state_update_key(); xkb_machine::xkb_machine_process_synthetic()

Since: 1.14.0

◆ xkb_state_update_latched_locked()

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.

Deprecated:: Use xkb_state_update_synthetic() instead.

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.

Layout out of range: If the effective layout, after taking into account the depressed, latched and locked layout, is out of range (negative or greater than the maximum layout), it is brought into range. Currently, the layout is wrapped using integer modulus (with negative values wrapping from the end). The wrapping behavior can be configured using xkb_state_update_synthetic().

Parameters

[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.

@important If 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.

Returns: A mask of state components that have changed as a result of the update. If nothing in the state has changed, returns 0 (XKB_STATE_NO_COMPONENT).

See also: xkb_state_update_synthetic()

Since: 1.14.0: Reject call if the state mode is incorrect.

Functions

Detailed Description

Function Documentation

◆ xkb_state_update_key()

◆ xkb_state_update_synthetic()

◆ xkb_state_update_latched_locked()