From 5ba075abe04a172efe7520b51ef04b77d3a4643b Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sat, 17 Dec 2022 13:51:10 +0200 Subject: doc: clarify "server state" and "client state" distinction Add a common page for the concept and link to there from the relevant functions. Signed-off-by: Ran Benita --- include/xkbcommon/xkbcommon.h | 63 ++++++++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 21 deletions(-) diff --git a/include/xkbcommon/xkbcommon.h b/include/xkbcommon/xkbcommon.h index 7cb46f3..a7148f3 100644 --- a/include/xkbcommon/xkbcommon.h +++ b/include/xkbcommon/xkbcommon.h @@ -1342,6 +1342,33 @@ xkb_state_unref(struct xkb_state *state); struct xkb_keymap * xkb_state_get_keymap(struct xkb_state *state); +/** + * @page server-client-state Server State and Client State + * @parblock + * + * The xkb_state API is used by two distinct actors in most window-system + * architectures: + * + * 1. A *server* - for example, a Wayland compositor, an X11 server, 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. + * + * 2. A *client* - for example, a Wayland client, 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. + * + * Some entry points in the xkb_state API are only meant for servers and some + * are only meant for clients, and the two should generally not be mixed. + * + * @endparblock + */ + /** Specifies the direction of the key (press / release). */ enum xkb_key_direction { XKB_KEY_UP, /**< The key was released. */ @@ -1388,11 +1415,8 @@ enum xkb_state_component { * Update the keyboard state to reflect a given key being pressed or * released. * - * This entry point is intended for programs which track the keyboard state - * explicitly (like an evdev client). If the state is serialized to you by - * a master process (like a Wayland compositor) using functions like - * xkb_state_serialize_mods(), you should use xkb_state_update_mask() instead. - * The two functions should not generally be used together. + * This entry point is intended for *server* applications and should not be used + * by *client* applications; see @ref server-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 @@ -1420,21 +1444,16 @@ xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key, /** * Update a keyboard state from a set of explicit masks. * - * This entry point is intended for window systems and the like, where a - * master process holds an xkb_state, then serializes it over a wire - * protocol, and clients then use the serialization to feed in to their own - * xkb_state. + * This entry point is intended for *client* applications; see @ref + * server-client-state for details. *Server* applications should use + * xkb_state_update_key() instead. * * All parameters must always be passed, or the resulting state may be * incoherent. * * The serialization is lossy and will not survive round trips; it must only - * be used to feed slave state objects, and must not be used to update the - * master state. - * - * If you do not fit the description above, you should use - * xkb_state_update_key() instead. The two functions should not generally be - * used together. + * be used to feed client state objects, and must not be used to update the + * server state. * * @returns A mask of state components that have changed as a result of * the update. If nothing in the state has changed, returns 0. @@ -1612,6 +1631,10 @@ enum xkb_state_match { * The counterpart to xkb_state_update_mask for modifiers, to be used on * the server side of serialization. * + * This entry point is intended for *server* applications; see @ref + * server-client-state for details. *Client* applications should use the + * xkb_state_mod_*_is_active API. + * * @param state The keyboard state. * @param components A mask of the modifier state components to serialize. * State components other than XKB_STATE_MODS_* are ignored. @@ -1621,9 +1644,6 @@ enum xkb_state_match { * @returns A xkb_mod_mask_t representing the given components of the * modifier state. * - * This function should not be used in regular clients; please use the - * xkb_state_mod_*_is_active API instead. - * * @memberof xkb_state */ xkb_mod_mask_t @@ -1634,6 +1654,10 @@ xkb_state_serialize_mods(struct xkb_state *state, * The counterpart to xkb_state_update_mask for layouts, to be used on * the server side of serialization. * + * This entry point is intended for *server* applications; see @ref + * server-client-state for details. *Client* applications should use the + * xkb_state_layout_*_is_active API. + * * @param state The keyboard state. * @param components A mask of the layout state components to serialize. * State components other than XKB_STATE_LAYOUT_* are ignored. @@ -1643,9 +1667,6 @@ xkb_state_serialize_mods(struct xkb_state *state, * @returns A layout index representing the given components of the * layout state. * - * This function should not be used in regular clients; please use the - * xkb_state_layout_*_is_active API instead. - * * @memberof xkb_state */ xkb_layout_index_t -- cgit v1.2.1