Collaboration diagram for Events:

Data Structures
struct	xkb_event_components

struct	xkb_event_pointer_motion

struct	xkb_event_pointer_button

struct	xkb_events_config

struct	xkb_event

struct	xkb_events

Enumerations
enum	xkb_event_type { XKB_EVENT_TYPE_INVALID = 0 , XKB_EVENT_TYPE_FRAME , XKB_EVENT_TYPE_KEY , XKB_EVENT_TYPE_STATE_COMPONENTS , XKB_EVENT_TYPE_POINTER_MOTION , XKB_EVENT_TYPE_POINTER_BUTTON , XKB_EVENT_TYPE_TERMINATE_DISPLAY_SERVER , XKB_EVENT_TYPE_SWITCH_VIRTUAL_CONSOLE }

enum	xkb_pointer_motion_flags { XKB_POINTER_MOTION_NO_FLAGS = 0 , XKB_POINTER_MOTION_REPEATS = (1 << 0) , XKB_POINTER_MOTION_ABSOLUTE_X = (1 << 1) , XKB_POINTER_MOTION_ABSOLUTE_Y = (1 << 2) }

enum	xkb_pointer_button_state { XKB_POINTER_BUTTON_RELEASED , XKB_POINTER_BUTTON_PRESSED }

enum	xkb_events_flags { XKB_EVENTS_NO_FLAGS = 0 }

Functions
XKB_EXPORT enum xkb_event_type	xkb_event::xkb_event_get_type (const struct xkb_event *event)

XKB_EXPORT enum xkb_status	xkb_event::xkb_event_get_keycode (const struct xkb_event event, xkb_keycode_t keycode, enum xkb_key_direction *direction)

XKB_EXPORT enum xkb_status	xkb_event::xkb_event_get_components (const struct xkb_event event, struct xkb_event_components components)

XKB_EXPORT enum xkb_status	xkb_event::xkb_event_get_pointer_motion (const struct xkb_event event, struct xkb_event_pointer_motion motion)

XKB_EXPORT enum xkb_status	xkb_event::xkb_event_get_pointer_button (const struct xkb_event event, struct xkb_event_pointer_button button)

XKB_EXPORT enum xkb_status	xkb_event::xkb_event_get_virtual_console (const struct xkb_event event, int8_t index_or_offset, bool *is_offset)

XKB_EXPORT struct xkb_events *	xkb_events::xkb_events_new (struct xkb_context context, const struct xkb_events_config config, enum xkb_status *status)

XKB_EXPORT void	xkb_events::xkb_events_destroy (struct xkb_events *events)

XKB_EXPORT const struct xkb_event *	xkb_events::xkb_events_next (struct xkb_events *events)

Detailed Description

Events and frames produced by the XKB state machine.

Overview

Keyboard events are the outputs of the state machine‌: they describe every observable change resulting from processing a raw key event or a synthetic update.

Events are produced by an xkb_machine via its process_* functions and collected into an xkb_events batch. The batch is a flat sequence of xkb_event entries, consumed sequentially with xkb_events::xkb_events_next().

Event pipeline

xkb_machine_process_key(machine, keycode, direction, events);
while ((event = xkb_events_next(events)) != NULL) {
    switch (xkb_event_get_type(event)) {
    case XKB_EVENT_TYPE_INVALID: ...          // error marker
    case XKB_EVENT_TYPE_FRAME: ...            // frame boundary
    case XKB_EVENT_TYPE_KEY: ...              // key event
    case XKB_EVENT_TYPE_STATE_COMPONENTS: ... // state change
    ...
    }
}

Events and frames

Two levels of atomicity apply:

Event: An atomic record: a single, indivisible state change, hardware event, or frame boundary. Each event is self-contained and consistent.
Frame: An atomic transaction: the sequence of events between two XKB_EVENT_TYPE_FRAME boundaries is applied as a whole. Querying the keyboard state within a frame is not guaranteed to be consistent with the events delivered so far; only the state after the complete frame is. A frame is thus the commit point of the event pipeline.

Guarantees

A process_* call produces zero or more complete frames; a batch never ends mid-frame. A key event may produce no frame at all for some configurations.
Every frame is terminated by a XKB_EVENT_TYPE_FRAME event; the first frame of a batch begins at its start.
Events are consumed in order. A returned event is frame-borrowed‌:
The batch is reset on each process_* call.

Remarks: The frame semantics match the Wayland wl_pointer::frame and the upcoming wl_keyboard::frame request, so that a Wayland compositor may forward event grouping without reinterpretation.

See also: struct xkb_machine: the event producer.; xkb_events::xkb_events_new(), xkb_events::xkb_events_next(): the event collection.; struct xkb_event: the atomic record.; enum xkb_event_type; Server State and Client State.; Ownership model.

Since: 1.14.0

Enumeration Type Documentation

◆ xkb_event_type

enum xkb_event_type

Denotes the type of a state event.

See also: xkb_event::xkb_event_get_type()

Since: 1.14.0

Enumerator
XKB_EVENT_TYPE_INVALID	Invalid event. This is not a real event type but an error indicator. Since 1.14.0
XKB_EVENT_TYPE_FRAME	Frame boundary. This is not a real event type but an indicator for the consumer (a server) to commit current transaction. See also Frame definition Frame-borrowed Since 1.14.0
XKB_EVENT_TYPE_KEY	Key event See also `xkb_event::xkb_event_get_keycode()` Since 1.14.0
XKB_EVENT_TYPE_STATE_COMPONENTS	State components change event See also `xkb_event::xkb_event_get_components()` Since 1.14.0
XKB_EVENT_TYPE_POINTER_MOTION	Pointer motion event See also `xkb_event::xkb_event_get_pointer_motion()` Since 1.14.0
XKB_EVENT_TYPE_POINTER_BUTTON	Pointer button event See also `xkb_event::xkb_event_get_pointer_button()` Since 1.14.0
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. Since 1.14.0
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. Since 1.14.0

◆ xkb_pointer_motion_flags

enum xkb_pointer_motion_flags

Pointer motion flags for xkb_event_pointer_motion.

Since: 1.14.0

Enumerator
XKB_POINTER_MOTION_NO_FLAGS	Do not apply any flags; the corresponding pointer motion‌: has relative coordinates, does not repeat. Since 1.14.0
XKB_POINTER_MOTION_REPEATS	The pointer motion repeats. Since 1.14.0
XKB_POINTER_MOTION_ABSOLUTE_X	The x coordinate is absolute. Since 1.14.0
XKB_POINTER_MOTION_ABSOLUTE_Y	The y coordinate is absolute. Since 1.14.0

◆ xkb_pointer_button_state

enum xkb_pointer_button_state

Specifies the state of a button (pressed/released).

See also: struct xkb_event_pointer_button

Since: 1.14.0

Enumerator

XKB_POINTER_BUTTON_RELEASED

The pointer button was released.

Since: 1.14.0

XKB_POINTER_BUTTON_PRESSED

The pointer button was pressed.

Since: 1.14.0

◆ xkb_events_flags

enum xkb_events_flags

Flags for xkb_events_config::flags.

See also: xkb_events::xkb_events_new().

Since: 1.14.0

Enumerator

XKB_EVENTS_NO_FLAGS

Do not apply any flags: the corresponding event collection will behave as a batch of events.

Since: 1.14.0

Function Documentation

◆ xkb_event_get_type()

XKB_EXPORT enum xkb_event_type xkb_event_get_type ( const struct xkb_event * event )

Get the type of an event.

Parameters

[in] event The event to process.

Returns: The event’s type on success, otherwise XKB_EVENT_TYPE_INVALID.

Since: 1.14.0

◆ xkb_event_get_keycode()

XKB_EXPORT enum xkb_status 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.

Parameters

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

Precondition: The event must be XKB_EVENT_TYPE_KEY. Otherwise keycode and direction are not updated.

Returns

XKB_SUCCESS on success, otherwise an error code‌:

XKB_ERROR_EVENT_TYPE_MISMATCH if the event type is incorrect.

See also: xkb_machine::xkb_machine_process_key()

Since: 1.14.0

◆ xkb_event_get_components()

XKB_EXPORT enum xkb_status 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.

Parameters

[in]	event	The event object to process.
[in,out]	components	A pointer to an event components object to update with the event.

Precondition: The event must be of type XKB_EVENT_TYPE_STATE_COMPONENTS. Otherwise components is not updated.; components must point to a zero-initialized struct with `components->size` set per Extensible structure ABI contract.

Invariant: The library writes only to fields of components that fall within `components->size`.

Returns

XKB_SUCCESS on success, otherwise an error code‌:

Errors from ABI Version resolution.
XKB_ERROR_EVENT_TYPE_MISMATCH if the event type is incorrect.

See also: XKB_EVENT_TYPE_STATE_COMPONENTS; struct xkb_event_components

Since: 1.14.0

◆ xkb_event_get_pointer_motion()

XKB_EXPORT enum xkb_status 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.

Parameters

[in]	event	The event object to process.
[in,out]	motion	A pointer to a pointer motion object to update with the event.

Precondition: The event must have the type XKB_EVENT_TYPE_POINTER_MOTION. Otherwise motion is not updated.; motion must point to a zero-initialized struct with `motion->size` set per Extensible structure ABI contract.

Invariant: The library writes only to fields of motion that fall within `motion->size`.

Returns

XKB_SUCCESS on success, otherwise an error code‌:

Errors from ABI Version resolution.
XKB_ERROR_EVENT_TYPE_MISMATCH if the event type is incorrect.

See also: XKB_EVENT_TYPE_POINTER_MOTION; struct xkb_event_pointer_motion

Since: 1.14.0

◆ xkb_event_get_pointer_button()

XKB_EXPORT enum xkb_status 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.

Parameters

[in]	event	The event object to process.
[in,out]	button	A pointer to a pointer button object to update with the event.

Precondition: The event must have the type XKB_EVENT_TYPE_POINTER_BUTTON. Otherwise button is not updated.; button must point to a zero-initialized struct with `button->size` set per Extensible structure ABI contract.

Invariant: The library writes only to fields of button that fall within `button->size`.

Returns

XKB_SUCCESS on success, otherwise an error code‌:

Errors from ABI Version resolution.
XKB_ERROR_EVENT_TYPE_MISMATCH if the event type is incorrect.

See also: XKB_EVENT_TYPE_POINTER_BUTTON.; struct xkb_event_pointer_button

Since: 1.14.0

◆ xkb_event_get_virtual_console()

XKB_EXPORT enum xkb_status 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.

Parameters

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

Precondition: The event must be XKB_EVENT_TYPE_SWITCH_VIRTUAL_CONSOLE. Otherwise index_or_offset and is_offset are not updated.

Returns

XKB_SUCCESS on success, otherwise an error code‌:

XKB_ERROR_EVENT_TYPE_MISMATCH if the event type is incorrect.

See also: xkb_machine::xkb_machine_process_key()

Since: 1.14.0

◆ xkb_events_new()

XKB_EXPORT struct xkb_events * xkb_events_new	(	struct xkb_context *	context,
		const struct xkb_events_config *	config,
		enum xkb_status *	status
	)

Create a new event collection object.

Parameters

[in]	context	The context in which to create the object. Shared ownership: the returned `xkb_events` takes a new reference on this parameter.
[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]	status	Pointer to store the resulting status code, or `NULL` if not needed.

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

Returns: A newly allocated event collection, or NULL on failure. The caller owns the returned object and must release it with xkb_events_destroy().

Postcondition

if status is not NULL, *status is set to XKB_SUCCESS on success or to an error code corresponding to the failure. Possible errors are:

See also: struct xkb_events_config; xkb_events_destroy(); xkb_events_next(); xkb_machine::xkb_machine_process_key()

Since: 1.14.0

◆ xkb_events_destroy()

XKB_EXPORT void xkb_events_destroy ( struct xkb_events * events )

Free an event collection object.

Parameters

[in] events The event collection object. If it is NULL, this function does nothing.

See also: xkb_events_new()

Since: 1.14.0

◆ xkb_events_next()

XKB_EXPORT const struct xkb_event * xkb_events_next ( struct xkb_events * events )

Get the next event from an event collection.

Parameters

[in] events The event collection.

Returns: The borrowed next event, or NULL if there are no more events to read.

Since: 1.14.0

Data Structures

Enumerations

Functions

Detailed Description

Overview

Events and frames

Guarantees

Enumeration Type Documentation

◆ xkb_event_type

◆ xkb_pointer_motion_flags

◆ xkb_pointer_button_state

◆ xkb_events_flags

Function Documentation

◆ xkb_event_get_type()

◆ xkb_event_get_keycode()

◆ xkb_event_get_components()

◆ xkb_event_get_pointer_motion()

◆ xkb_event_get_pointer_button()

◆ xkb_event_get_virtual_console()

◆ xkb_events_new()

◆ xkb_events_destroy()

◆ xkb_events_next()