/* * For MIT-open-group: * Copyright 1985, 1987, 1990, 1998 The Open Group * Copyright 2008 Dan Nicholson * * For HPND: * Copyright (c) 1993 by Silicon Graphics Computer Systems, Inc. * SPDX-License-Identifier: HPND * * For MIT: * Copyright © 2009-2012 Daniel Stone * Copyright © 2012 Intel Corporation * Copyright © 2012 Ran Benita * * SPDX-License-Identifier: MIT-open-group AND HPND AND MIT * * Author: Daniel Stone */ #ifndef _XKBCOMMON_H_ #define _XKBCOMMON_H_ #include #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif #if defined(__GNUC__) && !defined(__CYGWIN__) # define XKB_EXPORT __attribute__((visibility("default"))) #elif defined(_WIN32) # define XKB_EXPORT __declspec(dllexport) #else # define XKB_EXPORT #endif /** * @file * Main libxkbcommon API. */ /** * @struct xkb_context * Opaque top level library context object. * * The context contains various general library data and state, like * logging level and include paths. * * Objects are created in a specific context, and multiple contexts may * coexist simultaneously. Objects from different contexts are completely * separated and do not share any memory or state. */ struct xkb_context; /** * @struct xkb_keymap * Opaque compiled keymap object. * * The keymap object holds all of the static keyboard information obtained * from compiling XKB files. * * A keymap is immutable after it is created (besides reference counts, etc.); * if you need to change it, you must create a new one. */ struct xkb_keymap; /** * @struct xkb_state * Opaque keyboard state object. * * State objects contain the active state of a keyboard (or keyboards), such * as the currently effective layout and the active modifiers. It acts as a * simple state machine, wherein key presses and releases are the input, and * key symbols (keysyms) are the output. */ struct xkb_state; /** * A number used to represent a physical key on a keyboard. * * A standard PC-compatible keyboard might have 102 keys. An appropriate * keymap would assign each of them a keycode, by which the user should * refer to the key throughout the library. * * Historically, the X11 protocol, and consequentially the XKB protocol, * assign only 8 bits for keycodes. This limits the number of different * keys that can be used simultaneously in a single keymap to 256 * (disregarding other limitations). This library does not share this limit; * keycodes beyond 255 (*extended* keycodes) are not treated specially. * Keymaps and applications which are compatible with X11 should not use * these keycodes. * * The values of specific keycodes are determined by the keymap and the * underlying input system. For example, with an X11-compatible keymap * and Linux evdev scan codes (see `linux/input.h`), a fixed offset is used: * * The keymap defines a canonical name for each key, plus possible aliases. * Historically, the XKB protocol restricts these names to at most 4 (ASCII) * characters, but this library does not share this limit. * * @code * xkb_keycode_t keycode_A = KEY_A + 8; * @endcode * * @sa xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11() */ typedef uint32_t xkb_keycode_t; /** * A number used to represent the symbols generated from a key on a keyboard. * * A key, represented by a keycode, may generate different symbols according * to keyboard state. For example, on a QWERTY keyboard, pressing the key * labled \ generates the symbol ‘a’. If the Shift key is held, it * generates the symbol ‘A’. If a different layout is used, say Greek, * it generates the symbol ‘α’. And so on. * * Each such symbol is represented by a *keysym* (short for “key symbol”). * Note that keysyms are somewhat more general, in that they can also represent * some “function”, such as “Left” or “Right” for the arrow keys. For more * information, see: Appendix A [“KEYSYM Encoding”][encoding] of the X Window * System Protocol. * * Specifically named keysyms can be found in the * xkbcommon/xkbcommon-keysyms.h header file. Their name does not include * the `XKB_KEY_` prefix. * * Besides those, any Unicode/ISO 10646 character in the range U+0100 to * U+10FFFF can be represented by a keysym value in the range 0x01000100 to * 0x0110FFFF. The name of Unicode keysyms is `U`, e.g. `UA1B2`. * * The name of other unnamed keysyms is the hexadecimal representation of * their value, e.g. `0xabcd1234`. * * Keysym names are case-sensitive. * * @note **Encoding:** Keysyms are 32-bit integers with the 3 most significant * bits always set to zero. Thus valid keysyms are in the range * `0 .. 0x1fffffff` = @ref XKB_KEYSYM_MAX. * See: Appendix A [“KEYSYM Encoding”][encoding] of the X Window System Protocol. * * [encoding]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#keysym_encoding * * @ingroup keysyms * @sa `::XKB_KEYSYM_MAX` */ typedef uint32_t xkb_keysym_t; /** * Index of a keyboard layout. * * The layout index is a state component which determines which keyboard * layout is active. These may be different alphabets, different key * arrangements, etc. * * Layout indices are consecutive. The first layout has index 0. * * Each layout is not required to have a name, and the names are not * guaranteed to be unique (though they are usually provided and unique). * Therefore, it is not safe to use the name as a unique identifier for a * layout. Layout names are case-sensitive. * * Layout names are specified in the layout’s definition, for example * “English (US)”. These are different from the (conventionally) short names * which are used to locate the layout, for example `us` or `us(intl)`. These * names are not present in a compiled keymap. * * If the user selects layouts from a list generated from the XKB registry * (using libxkbregistry or directly), and this metadata is needed later on, it * is recommended to store it along with the keymap. * * Layouts are also called *groups* by XKB. * * @sa xkb_keymap::xkb_keymap_num_layouts() * @sa xkb_keymap::xkb_keymap_num_layouts_for_key() */ typedef uint32_t xkb_layout_index_t; /** A mask of layout indices. */ typedef uint32_t xkb_layout_mask_t; /** * Index of a shift level. * * Any key, in any layout, can have several shift levels. Each * shift level can assign different keysyms to the key. The shift level * to use is chosen according to the current keyboard state; for example, * if no keys are pressed, the first level may be used; if the Left Shift * key is pressed, the second; if Num Lock is pressed, the third; and * many such combinations are possible (see `xkb_mod_index_t`). * * Level indices are consecutive. The first level has index 0. */ typedef uint32_t xkb_level_index_t; /** * Index of a modifier. * * A @e modifier is a state component which changes the way keys are * interpreted. A keymap defines a set of modifiers, such as Alt, Shift, * Num Lock or Meta, and specifies which keys may @e activate which * modifiers (in a many-to-many relationship, i.e. a key can activate * several modifiers, and a modifier may be activated by several keys. * Different keymaps do this differently). * * When retrieving the keysyms for a key, the active modifier set is * consulted; this determines the correct shift level to use within the * currently active layout (see `xkb_level_index_t`). * * Modifier indices are consecutive. The first modifier has index 0. * * Each modifier must have a name, and the names are unique. Therefore, it * is safe to use the name as a unique identifier for a modifier. The names * of some common modifiers are provided in the `xkbcommon/xkbcommon-names.h` * header file. Modifier names are case-sensitive. * * @sa xkb_keymap_num_mods() */ typedef uint32_t xkb_mod_index_t; /** A mask of modifier indices. */ typedef uint32_t xkb_mod_mask_t; /** * Index of a keyboard LED. * * LEDs are logical objects which may be @e active or @e inactive. They * typically correspond to the lights on the keyboard. Their state is * determined by the current keyboard state. * * LED indices are non-consecutive. The first LED has index 0. * * Each LED must have a name, and the names are unique. Therefore, * it is safe to use the name as a unique identifier for a LED. The names * of some common LEDs are provided in the `xkbcommon/xkbcommon-names.h` * header file. LED names are case-sensitive. * * @warning A given keymap may specify an exact index for a given LED. * Therefore, LED indexing is not necessarily sequential, as opposed to * modifiers and layouts. This means that when iterating over the LEDs * in a keymap using e.g. xkb_keymap::xkb_keymap_num_leds(), some indices might * be invalid. * Given such an index, functions like xkb_keymap::xkb_keymap_led_get_name() * will return `NULL`, and `xkb_state::xkb_state_led_index_is_active()` will * return -1. * * LEDs are also called *indicators* by XKB. * * @sa `xkb_keymap::xkb_keymap_num_leds()` */ typedef uint32_t xkb_led_index_t; /** A mask of LED indices. */ typedef uint32_t xkb_led_mask_t; /** Invalid keycode */ #define XKB_KEYCODE_INVALID (0xffffffff) /** Invalid layout index */ #define XKB_LAYOUT_INVALID (0xffffffff) /** Invalid level index */ #define XKB_LEVEL_INVALID (0xffffffff) /** Invalid modifier index */ #define XKB_MOD_INVALID (0xffffffff) /** Invalid LED index */ #define XKB_LED_INVALID (0xffffffff) /** Maximum legal keycode */ #define XKB_KEYCODE_MAX (0xffffffff - 1) /** * Maximum keysym value * * @since 1.6.0 * @sa xkb_keysym_t * @ingroup keysyms */ #define XKB_KEYSYM_MAX 0x1fffffff /** * Test whether a value is a valid extended keycode. * @sa xkb_keycode_t **/ #define xkb_keycode_is_legal_ext(key) ((key) <= XKB_KEYCODE_MAX) /** * Test whether a value is a valid X11 keycode. * @sa xkb_keycode_t */ #define xkb_keycode_is_legal_x11(key) ((key) >= 8 && (key) <= 255) /** * @defgroup rules-api Rules * Utility functions related to *rules*, whose purpose is introduced in: * @ref xkb-the-config "". * * @{ */ /** * @struct xkb_rmlvo_builder * Opaque [RMLVO] configuration object. * * It denotes the configuration values by which a user picks a keymap. * * @see [Introduction to RMLVO][RMLVO] * @see @ref rules-api "" * @since 1.11.0 * * [RMLVO]: @ref RMLVO-intro */ struct xkb_rmlvo_builder; enum xkb_rmlvo_builder_flags { XKB_RMLVO_BUILDER_NO_FLAGS = 0 }; /** * Create a new [RMLVO] builder. * * @param context The context in which to create the builder. * @param rules The ruleset. * If `NULL` or the empty string `""`, a default value is used. * If the `XKB_DEFAULT_RULES` environment variable is set, it is used * as the default. Otherwise the system default is used. * @param model The keyboard model. * If `NULL` or the empty string `""`, a default value is used. * If the `XKB_DEFAULT_MODEL` environment variable is set, it is used * as the default. Otherwise the system default is used. * @param flags Optional flags for the builder, or 0. * * @returns A `xkb_rmlvo_builder`, or `NULL` if the compilation failed. * * @see `xkb_rule_names` for a detailed description of `rules` and `model`. * @since 1.11.0 * @memberof xkb_rmlvo_builder * * [RMLVO]: @ref RMLVO-intro */ XKB_EXPORT struct xkb_rmlvo_builder* xkb_rmlvo_builder_new(struct xkb_context *context, const char *rules, const char *model, enum xkb_rmlvo_builder_flags flags); /** * Append a layout to the given [RMLVO] builder. * * @param rmlvo The builder to modify. * @param layout The name of the layout. * @param variant The name of the layout variant, or `NULL` to * select the default variant. * @param options An array of options to apply only to this layout, or * `NULL` if there is no such options. * @param options_len The length of @p options. * * @note The options are only effectual if the corresponding ruleset has the * proper rules to handle them as *layout-specific* options. * @note See `rxkb_option_is_layout_specific()` to query whether an option * supports the layout-specific feature. * * @returns `true` if the call succeeded, otherwise `false`. * * @since 1.11.0 * @memberof xkb_rmlvo_builder * * [RMLVO]: @ref RMLVO-intro */ XKB_EXPORT bool xkb_rmlvo_builder_append_layout(struct xkb_rmlvo_builder *rmlvo, const char *layout, const char *variant, const char* const* options, size_t options_len); /** * Append an option to the given [RMLVO] builder. * * @param rmlvo The builder to modify. * @param option The name of the option. * * @returns `true` if the call succeeded, otherwise `false`. * * @since 1.11.0 * @memberof xkb_rmlvo_builder * * [RMLVO]: @ref RMLVO-intro */ XKB_EXPORT bool xkb_rmlvo_builder_append_option(struct xkb_rmlvo_builder *rmlvo, const char *option); /** * Take a new reference on a [RMLVO] builder. * * @param rmlvo The builder to reference. * * @returns The passed in builder. * * @since 1.11.0 * @memberof xkb_rmlvo_builder * * [RMLVO]: @ref RMLVO-intro */ XKB_EXPORT struct xkb_rmlvo_builder * xkb_rmlvo_builder_ref(struct xkb_rmlvo_builder *rmlvo); /** * Release a reference on a [RMLVO] builder, and possibly free it. * * @param rmlvo The builder. If it is `NULL`, this function does nothing. * * @since 1.11.0 * @memberof xkb_rmlvo_builder * * [RMLVO]: @ref RMLVO-intro */ XKB_EXPORT void xkb_rmlvo_builder_unref(struct xkb_rmlvo_builder *rmlvo); /** * Names to compile a keymap with, also known as [RMLVO]. * * The names are the common configuration values by which a user picks * a keymap. * * If the entire struct is `NULL`, then each field is taken to be `NULL`. * You should prefer passing `NULL` instead of choosing your own defaults. * * @see [Introduction to RMLVO][RMLVO] * @see @ref rules-api "" * * [RMLVO]: @ref RMLVO-intro */ struct xkb_rule_names { /** * The rules file to use. The rules file describes how to interpret * the values of the model, layout, variant and options fields. * * If `NULL` or the empty string `""`, a default value is used. * If the `XKB_DEFAULT_RULES` environment variable is set, it is used * as the default. Otherwise the system default is used. */ const char *rules; /** * The keyboard model by which to interpret keycodes and LEDs. * * If `NULL` or the empty string `""`, a default value is used. * If the `XKB_DEFAULT_MODEL` environment variable is set, it is used * as the default. Otherwise the system default is used. */ const char *model; /** * A comma separated list of layouts (languages) to include in the * keymap. * * If `NULL` or the empty string `""`, a default value is used. * If the `XKB_DEFAULT_LAYOUT` environment variable is set, it is used * as the default. Otherwise the system default is used. */ const char *layout; /** * A comma separated list of variants, one per layout, which may * modify or augment the respective layout in various ways. * * Generally, should either be empty or have the same number of values * as the number of layouts. You may use empty values as in `intl,,neo`. * * If `NULL` or the empty string `""`, and a default value is also used * for the layout, a default value is used. Otherwise no variant is * used. * If the `XKB_DEFAULT_VARIANT` environment variable is set, it is used * as the default. Otherwise the system default is used. */ const char *variant; /** * A comma separated list of options, through which the user specifies * non-layout related preferences, like which key combinations are used * for switching layouts, or which key is the Compose key. * * If `NULL`, a default value is used. If the empty string `""`, no * options are used. * If the `XKB_DEFAULT_OPTIONS` environment variable is set, it is used * as the default. Otherwise the system default is used. * * Each option can additionally have a *layout index specifier*, so that it * applies only if matching the given layout. The index is specified by * appending `!` immediately after the option name, then the 1-indexed * target layout in decimal format: e.g. `ns:option!2`. When no layout is * specified, it matches any layout. * * @note The layout index specifier is only effectual if the corresponding * ruleset has the proper rules to handle the option as *layout-specific*. * @note See `rxkb_option_is_layout_specific()` to query whether an option * supports the layout-specific feature. * * @since 1.11.0: Layout index specifier using `!`. */ const char *options; }; /** * Keymap components, also known as [KcCGST]. * * The components are the result of the [RMLVO] resolution. * * @see [Introduction to RMLVO][RMLVO] * @see [Introduction to KcCGST][KcCGST] * @see @ref rules-api "" * * [RMLVO]: @ref RMLVO-intro * [KcCGST]: @ref KcCGST-intro */ struct xkb_component_names { char *keycodes; char *compatibility; char *geometry; char *symbols; char *types; }; /** * Resolve [RMLVO] names to [KcCGST] components. * * This function is used primarily for *debugging*. See * `xkb_keymap::xkb_keymap_new_from_names2()` for creating keymaps from * [RMLVO] names. * * @param[in] context The context in which to resolve the names. * @param[in] rmlvo_in The [RMLVO] names to use. * @param[out] rmlvo_out The [RMLVO] names actually used after resolving * missing values. * @param[out] components_out The [KcCGST] components resulting of the [RMLVO] * resolution. * * @c rmlvo_out and @c components can be omitted by using `NULL`, but not both. * * If @c components is not `NULL`, it is filled with dynamically-allocated * strings that should be freed by the caller. * * @returns `true` if the [RMLVO] names could be resolved, `false` otherwise. * * @see [Introduction to RMLVO][RMLVO] * @see [Introduction to KcCGST][KcCGST] * @see xkb_rule_names * @see xkb_component_names * @see xkb_keymap::xkb_keymap_new_from_names2() * * @since 1.9.0 * @memberof xkb_component_names * * [RMLVO]: @ref RMLVO-intro * [KcCGST]: @ref KcCGST-intro */ XKB_EXPORT bool xkb_components_names_from_rules(struct xkb_context *context, const struct xkb_rule_names *rmlvo_in, struct xkb_rule_names *rmlvo_out, struct xkb_component_names *components_out); /** @} */ /** * @defgroup keysyms Keysyms * Utility functions related to *keysyms* (short for “key symbols”). * * @{ */ /** * @page keysym-transformations Keysym Transformations * * Keysym translation is subject to several *keysym transformations*, * as described in the XKB specification. These are: * *
*
Capitalization transformation
*
* If the Caps Lock modifier is * active and was not consumed by the translation process, keysyms * are transformed to their upper-case form (if applicable). * Similarly, the UTF-8/UTF-32 string produced is capitalized. * * This is described in: * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Lock_Modifier *
*
Control transformation
*
* If the Control modifier is active and * was not consumed by the translation process, the string produced * is transformed to its matching ASCII control character (if * applicable). Keysyms are not affected. * * This is described in: * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier *
*
* * Each relevant function discusses which transformations it performs. * * These transformations are not applicable when a key produces multiple * keysyms. */ /** * Get the name of a keysym. * * For a description of how keysyms are named, see @ref xkb_keysym_t. * * @param[in] keysym The keysym. * @param[out] buffer A string buffer to write the name into. * @param[in] size Size of the buffer. * * @warning If the buffer passed is too small, the string is truncated * (though still `NULL`-terminated); a size of at least 64 bytes is recommended. * * @returns The number of bytes in the name, excluding the `NULL` byte. If * the keysym is invalid, returns -1. * * You may check if truncation has occurred by comparing the return value * with the length of buffer, similarly to the `snprintf(3)` function. * * @sa `xkb_keysym_t` */ XKB_EXPORT int xkb_keysym_get_name(xkb_keysym_t keysym, char *buffer, size_t size); /** Flags for xkb_keysym_from_name(). */ enum xkb_keysym_flags { /** Do not apply any flags. */ XKB_KEYSYM_NO_FLAGS = 0, /** Find keysym by case-insensitive search. */ XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0) }; /** * Get a keysym from its name. * * @param name The name of a keysym. See remarks in `xkb_keysym_get_name()`; * this function will accept any name returned by that function. * @param flags A set of flags controlling how the search is done. If * invalid flags are passed, this will fail with `XKB_KEY_NoSymbol`. * * If you use the `::XKB_KEYSYM_CASE_INSENSITIVE` flag and two keysym names * differ only by case, then the lower-case keysym name is returned. For * instance, for KEY_a and KEY_A, this function would return KEY_a for the * case-insensitive search. If this functionality is needed, it is * recommended to first call this function without this flag; and if that * fails, only then to try with this flag, while possibly warning the user * he had misspelled the name, and might get wrong results. * * Case folding is done according to the C locale; the current locale is not * consulted. * * @returns The keysym. If the name is invalid, returns `XKB_KEY_NoSymbol`. * * @sa xkb_keysym_t * @since 1.9.0: Enable support for C0 and C1 control characters in the Unicode * notation. */ XKB_EXPORT xkb_keysym_t xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags); /** * Get the Unicode/UTF-8 representation of a keysym. * * @param[in] keysym The keysym. * @param[out] buffer A buffer to write the UTF-8 string into. * @param[in] size The size of buffer. Must be at least 5. * * @returns The number of bytes written to the buffer (including the * terminating byte). If the keysym does not have a Unicode * representation, returns 0. If the buffer is too small, returns -1. * * This function does not perform any @ref keysym-transformations. * Therefore, prefer to use `xkb_state::xkb_state_key_get_utf8()` if possible. * * @sa `xkb_state::xkb_state_key_get_utf8()` */ XKB_EXPORT int xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size); /** * Get the Unicode/UTF-32 representation of a keysym. * * @returns The Unicode/UTF-32 representation of keysym, which is also * compatible with UCS-4. If the keysym does not have a Unicode * representation, returns 0. * * This function does not perform any @ref keysym-transformations. * Therefore, prefer to use xkb_state_key_get_utf32() if possible. * * @sa `xkb_state::xkb_state_key_get_utf32()` */ XKB_EXPORT uint32_t xkb_keysym_to_utf32(xkb_keysym_t keysym); /** * Get the keysym corresponding to a Unicode/UTF-32 codepoint. * * @returns The keysym corresponding to the specified Unicode * codepoint, or XKB_KEY_NoSymbol if there is none. * * This function is the inverse of @ref xkb_keysym_to_utf32. In cases * where a single codepoint corresponds to multiple keysyms, returns * the keysym with the lowest value. * * Unicode codepoints which do not have a special (legacy) keysym * encoding use a direct encoding scheme. These keysyms don’t usually * have an associated keysym constant (`XKB_KEY_*`). * * @sa `xkb_keysym_to_utf32()` * @since 1.0.0 * @since 1.9.0: Enable support for all noncharacters. */ XKB_EXPORT xkb_keysym_t xkb_utf32_to_keysym(uint32_t ucs); /** * Convert a keysym to its uppercase form. * * If there is no such form, the keysym is returned unchanged. * * The conversion rules are the *simple* (i.e. one-to-one) Unicode case * mappings (with some exceptions, see hereinafter) and do not depend * on the locale. If you need the special case mappings (i.e. not * one-to-one or locale-dependent), prefer to work with the Unicode * representation instead, when possible. * * Exceptions to the Unicode mappings: * * | Lower keysym | Lower letter | Upper keysym | Upper letter | Comment | * | ------------ | ------------ | ------------ | ------------ | ------- | * | `ssharp` | `U+00DF`: ß | `U1E9E` | `U+1E9E`: ẞ | [Council for German Orthography] | * * [Council for German Orthography]: https://www.rechtschreibrat.com/regeln-und-woerterverzeichnis/ * * @since 0.8.0: Initial implementation, based on `libX11`. * @since 1.8.0: Use Unicode 16.0 mappings for complete Unicode coverage. * @since 1.12.0: Update to Unicode 17.0. */ XKB_EXPORT xkb_keysym_t xkb_keysym_to_upper(xkb_keysym_t ks); /** * Convert a keysym to its lowercase form. * * If there is no such form, the keysym is returned unchanged. * * The conversion rules are the *simple* (i.e. one-to-one) Unicode case * mappings and do not depend on the locale. If you need the special * case mappings (i.e. not one-to-one or locale-dependent), prefer to * work with the Unicode representation instead, when possible. * * @since 0.8.0: Initial implementation, based on `libX11`. * @since 1.8.0: Use Unicode 16.0 mappings for complete Unicode coverage. * @since 1.12.0: Update to Unicode 17.0. */ XKB_EXPORT xkb_keysym_t xkb_keysym_to_lower(xkb_keysym_t ks); /** @} */ /** * @defgroup context Library Context * Creating, destroying and using library contexts. * * Every keymap compilation request must have a context associated with * it. The context keeps around state such as the include path. * * @{ */ /** * @page envvars Environment Variables * * The user may set some environment variables which affect the library: * * - `XKB_CONFIG_ROOT`, `XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH`, * `XKB_CONFIG_VERSIONED_EXTENSIONS_PATH`, `XKB_CONFIG_EXTRA_PATH`, * `XDG_CONFIG_DIR`, `HOME` - see @ref include-path. * - `XKB_LOG_LEVEL` - see `xkb_context::xkb_context_set_log_level()`. * - `XKB_LOG_VERBOSITY` - see `xkb_context::xkb_context_set_log_verbosity()`. * - `XKB_DEFAULT_RULES`, `XKB_DEFAULT_MODEL`, `XKB_DEFAULT_LAYOUT`, * `XKB_DEFAULT_VARIANT`, `XKB_DEFAULT_OPTIONS` - see `xkb_rule_names`. */ /** Flags for context creation. */ enum xkb_context_flags { /** Do not apply any context flags. */ XKB_CONTEXT_NO_FLAGS = 0, /** * Create this context with an empty include path. * * This may be useful e.g.: * - to have full control over the included paths; * - for clients that do not need to access the XKB directories, e.g. * if only retrieving keymap from the Wayland or X server. It avoids * potential issues with directory access permissions. */ XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0), /** * Don’t take RMLVO names from the environment. * * @since 0.3.0 */ XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1), /** * Disable the use of secure_getenv for this context, so that privileged * processes can use environment variables. Client uses at their own risk. * * @since 1.5.0 */ XKB_CONTEXT_NO_SECURE_GETENV = (1 << 2) }; /** * Create a new context. * * @param flags Optional flags for the context, or 0. * * @returns A new context, or `NULL` on failure. * * @memberof xkb_context */ XKB_EXPORT struct xkb_context * xkb_context_new(enum xkb_context_flags flags); /** * Take a new reference on a context. * * @returns The passed in context. * * @memberof xkb_context */ XKB_EXPORT struct xkb_context * xkb_context_ref(struct xkb_context *context); /** * Release a reference on a context, and possibly free it. * * @param context The context. If it is `NULL`, this function does nothing. * * @memberof xkb_context */ XKB_EXPORT void xkb_context_unref(struct xkb_context *context); /** * Store custom user data in the context. * * This may be useful in conjunction with `xkb_context::xkb_context_set_log_fn()` * or other callbacks. * * @memberof xkb_context */ XKB_EXPORT void xkb_context_set_user_data(struct xkb_context *context, void *user_data); /** * Retrieves stored user data from the context. * * @returns The stored user data. If the user data wasn’t set, or the * passed in context is `NULL`, returns `NULL`. * * This may be useful to access private user data from callbacks like a * custom logging function. * * @memberof xkb_context **/ XKB_EXPORT void * xkb_context_get_user_data(struct xkb_context *context); /** @} */ /** * @defgroup include-path Include Paths * Manipulating the include paths in a context. * * The include paths are the file-system paths that are searched when an * include statement is encountered during keymap compilation. * * The default include paths are, in that lookup order: * *
*
User
*
* - The path `$XDG_CONFIG_HOME/xkb`, where `$XDG_CONFIG_HOME` is the value of * the environment variable `XDG_CONFIG_HOME`, with the usual fallback to * `$HOME/.config/` if unset. * * See @ref custom-configuration "" for further information. * - @deprecated The *legacy* path `$HOME/.xkb`, where `$HOME` is the value of * the environment variable `HOME`. * * *
*
System
*
* - The `XKB_CONFIG_EXTRA_PATH` environment variable, if defined, otherwise the * system configuration directory, defined at library configuration time * (usually `/etc/xkb`). * * One can adapt the @ref custom-configuration "" instructions by replacing * `$XDG_CONFIG_HOME` with the system configuration directory in the * file locations. * - Each subdirectory of each XKB extensions directory (versioned, then * unversioned if no corresponding versioned subdirectory), listed in * lexicographic order. The extensions directories are defined by the * environment variables `XKB_CONFIG_VERSIONED_EXTENSIONS_PATH` and * `XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH` and default to the system XKB * root extensions directories, defined at library configuration time (usually * `/usr/share/xkeyboard-config-.d` and * `/usr/share/xkeyboard-config.d`). * * See @ref packaging-keyboard-layouts "" for further information. * - The `XKB_CONFIG_ROOT` environment variable, if defined, otherwise * the system XKB root, defined at library configuration time * (usually `/usr/share/xkeyboard-config-` or `/usr/share/X11/xkb`). * * @warning Do not modify the system XKB root files, because they will be * overwritten by any update of the `xkeyboard-config`/`xkb-data` package. * - Since 1.12.2: if the previous path failed, it fallbacks to the *legacy X11 * path* defined at compilation time (usually `/usr/share/X11/xkb`). This * fallback is skipped is `XKB_CONFIG_ROOT` is explicitly set to an empty * string. *
*
* * @{ */ /** * Append a new entry to the context’s include path. * * @returns 1 on success, or 0 if the include path could not be added or is * inaccessible. * * @memberof xkb_context */ XKB_EXPORT int xkb_context_include_path_append(struct xkb_context *context, const char *path); /** * Append the default include paths to the context’s include path. * * @returns 1 on success, or 0 if no default include path could be added. * * @memberof xkb_context */ XKB_EXPORT int xkb_context_include_path_append_default(struct xkb_context *context); /** * Reset the context’s include path to the default. * * Removes all entries from the context’s include path, and inserts the * default paths. * * @returns 1 on success, or 0 if the primary include path could not be added. * * @memberof xkb_context */ XKB_EXPORT int xkb_context_include_path_reset_defaults(struct xkb_context *context); /** * Remove all entries from the context’s include path. * * @memberof xkb_context */ XKB_EXPORT void xkb_context_include_path_clear(struct xkb_context *context); /** * Get the number of paths in the context’s include path. * * @memberof xkb_context */ XKB_EXPORT unsigned int xkb_context_num_include_paths(struct xkb_context *context); /** * Get a specific include path from the context’s include path. * * @returns The include path at the specified index. If the index is * invalid, returns NULL. * * @memberof xkb_context */ XKB_EXPORT const char * xkb_context_include_path_get(struct xkb_context *context, unsigned int index); /** @} */ /** * @defgroup logging Logging Handling * Manipulating how logging from this library is handled. * * @{ */ /** Specifies a logging level. */ enum xkb_log_level { XKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */ XKB_LOG_LEVEL_ERROR = 20, /**< Log all errors. */ XKB_LOG_LEVEL_WARNING = 30, /**< Log warnings and errors. */ XKB_LOG_LEVEL_INFO = 40, /**< Log information, warnings, and errors. */ XKB_LOG_LEVEL_DEBUG = 50 /**< Log everything. */ }; /** * Set the current logging level. * * @param context The context in which to set the logging level. * @param level The logging level to use. Only messages from this level * and below will be logged. * * The default level is `::XKB_LOG_LEVEL_ERROR`. The environment variable * `XKB_LOG_LEVEL`, if set in the time the context was created, overrides the * default value. It may be specified as a level number or name. * * @memberof xkb_context */ XKB_EXPORT void xkb_context_set_log_level(struct xkb_context *context, enum xkb_log_level level); /** * Get the current logging level. * * @memberof xkb_context */ XKB_EXPORT enum xkb_log_level xkb_context_get_log_level(struct xkb_context *context); /** * Sets the current logging verbosity. * * The library can generate a number of warnings which are not helpful to * ordinary users of the library. The verbosity may be increased if more * information is desired (e.g. when developing a new keymap). * * The default verbosity is 0. The environment variable `XKB_LOG_VERBOSITY`, * if set in the time the context was created, overrides the default value. * * @param context The context in which to use the set verbosity. * @param verbosity The verbosity to use. Currently used values are * 1 to 10, higher values being more verbose. 0 would result in no verbose * messages being logged. * * Most verbose messages are of level `::XKB_LOG_LEVEL_WARNING` or lower. * * @memberof xkb_context */ XKB_EXPORT void xkb_context_set_log_verbosity(struct xkb_context *context, int verbosity); /** * Get the current logging verbosity of the context. * * @memberof xkb_context */ XKB_EXPORT int xkb_context_get_log_verbosity(struct xkb_context *context); /** * Set a custom function to handle logging messages. * * @param context The context in which to use the set logging function. * @param log_fn The function that will be called for logging messages. * Passing `NULL` restores the default function, which logs to stderr. * * By default, log messages from this library are printed to stderr. This * function allows you to replace the default behavior with a custom * handler. The handler is only called with messages which match the * current logging level and verbosity settings for the context. * level is the logging level of the message. @a format and @a args are * the same as in the `vprintf(3)` function. * * You may use `xkb_context::xkb_context_set_user_data()` on the context, and * then call `xkb_context::xkb_context_get_user_data()` from within the logging * function to provide it with additional private context. * * @memberof xkb_context */ XKB_EXPORT void xkb_context_set_log_fn(struct xkb_context *context, void (*log_fn)(struct xkb_context *context, enum xkb_log_level level, const char *format, va_list args)); /** @} */ /** * @defgroup keymap Keymap Creation * Creating and destroying keymaps. * * @{ */ /** Flags for keymap compilation. */ enum xkb_keymap_compile_flags { /** Do not apply any flags. */ XKB_KEYMAP_COMPILE_NO_FLAGS = 0 }; /** * The possible keymap formats. * * See @ref keymap-text-format-v1-v2 "" for the complete description of the * formats and @ref keymap-support "" for detailed differences between the * formats. * * @remark A keymap can be parsed in one format and serialized in another, * thanks to automatic fallback mechanisms. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Keymap format to use depending on the target protocol *
Protocollibxkbcommon keymap format
NameKeymap formatParsingSerialization
X11XKB * `::XKB_KEYMAP_FORMAT_TEXT_V1` * * *Always* use `::XKB_KEYMAP_FORMAT_TEXT_V1`, since the other formats are * incompatible. *
Wayland[xkb_v1] *
*
Wayland compositors
*
* The format depends on the keyboard layout database (usually [xkeyboard-config]). * Note that since v2 is a superset of v1, compositors are encouraged to use * `::XKB_KEYMAP_FORMAT_TEXT_V2` whenever possible. *
*
Client apps
*
* Clients should use `::XKB_KEYMAP_FORMAT_TEXT_V1` to parse the keymap sent * by a Wayland compositor, at least until `::XKB_KEYMAP_FORMAT_TEXT_V2` * stabilizes. *
*
* At the time of writing (July 2025), the Wayland [xkb_v1] keymap * format is only defined as “libxkbcommon compatible”. In theory it enables * flexibility, but the set of supported features varies depending on the * libxkbcommon version and libxkbcommon keymap format used. Unfortunately there * is currently no Wayland API for keymap format *negotiation*. * * Therefore the **recommended** serialization format is * `::XKB_KEYMAP_FORMAT_TEXT_V1`, in order to ensure maximum compatibility for * interchange. * * Serializing using `::XKB_KEYMAP_FORMAT_TEXT_V2` should be considered * **experimental**, as some clients may fail to parse the resulting string. *
* * [xkb_v1]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard-enum-keymap_format * [xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config */ enum xkb_keymap_format { /** * The classic XKB text format, as generated by `xkbcomp -xkb`. * * @important This format should *always* be used when *serializing* a * keymap for **X11**. * * @important For the **Wayland** [xkb_v1] format, it is * advised to use this format as well for serializing, in order to ensure * maximum compatibility for interchange. * * [xkb_v1]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard-enum-keymap_format */ XKB_KEYMAP_FORMAT_TEXT_V1 = 1, /** * Xkbcommon extensions of the classic XKB text format, **incompatible with * X11**. * * @important Do *not* use when *serializing* a keymap for **X11** * (incompatible). * * @important Considered *experimental* when *serializing* for **Wayland**: * at the time of writing (July 2025), there is only one XKB keymap format * [xkb_v1] in Wayland and no Wayland API for keymap format * *negotiation*, so the clients may not be able to parse the keymap if it * uses v2-specific features. Therefore a compositor may *parse* keymaps * using `::XKB_KEYMAP_FORMAT_TEXT_V2` but it should serialize them using * `::XKB_KEYMAP_FORMAT_TEXT_V1` and rely on the automatic *fallback* * mechanisms. * * @since 1.11.0 * * [xkb_v1]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard-enum-keymap_format */ XKB_KEYMAP_FORMAT_TEXT_V2 = 2 }; /** * Create a keymap from a [RMLVO] builder. * * The primary keymap entry point: creates a new XKB keymap from a set of * [RMLVO] \(Rules + Model + Layouts + Variants + Options) names. * * @param rmlvo The [RMLVO] builder to use. See `xkb_rmlvo_builder`. * @param format The text format of the keymap file to compile. * @param flags Optional flags for the keymap, or 0. * * @returns A keymap compiled according to the [RMLVO] names, or `NULL` if * the compilation failed. * * @since 1.11.0 * @sa `xkb_keymap_new_from_names2()` * @sa `xkb_rmlvo_builder` * @memberof xkb_keymap * * [RMLVO]: @ref RMLVO-intro */ XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_rmlvo(const struct xkb_rmlvo_builder *rmlvo, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags); /** * Create a keymap from [RMLVO] names. * * Same as `xkb_keymap_new_from_names2()`, but with the keymap format fixed to: * `::XKB_KEYMAP_FORMAT_TEXT_V2`. * * @deprecated Use `xkb_keymap_new_from_names2()` instead. * @since 1.11.0: Deprecated * @since 1.11.0: Use internally `::XKB_KEYMAP_FORMAT_TEXT_V2` instead of * `::XKB_KEYMAP_FORMAT_TEXT_V1` * @sa `xkb_keymap_new_from_names2()` * @sa `xkb_rule_names` * @sa `xkb_keymap_new_from_rmlvo()` * @memberof xkb_keymap * * [RMLVO]: @ref RMLVO-intro */ XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_names(struct xkb_context *context, const struct xkb_rule_names *names, enum xkb_keymap_compile_flags flags); /** * Create a keymap from [RMLVO] names. * * The primary keymap entry point: creates a new XKB keymap from a set of * [RMLVO] \(Rules + Model + Layouts + Variants + Options) names. * * @param context The context in which to create the keymap. * @param names The [RMLVO] names to use. See xkb_rule_names. * @param format The text format of the keymap file to compile. * @param flags Optional flags for the keymap, or 0. * * @returns A keymap compiled according to the [RMLVO] names, or `NULL` if * the compilation failed. * * @sa `xkb_rule_names` * @sa `xkb_keymap_new_from_rmlvo()` * @memberof xkb_keymap * @since 1.11.0 * * [RMLVO]: @ref RMLVO-intro */ XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_names2(struct xkb_context *context, const struct xkb_rule_names *names, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags); /** * Create a keymap from a keymap file. * * @param context The context in which to create the keymap. * @param file The keymap file to compile. * @param format The text format of the keymap file to compile. * @param flags Optional flags for the keymap, or 0. * * @returns A keymap compiled from the given XKB keymap file, or `NULL` if * the compilation failed. * * The file must contain a complete keymap. For example, in the * `::XKB_KEYMAP_FORMAT_TEXT_V1` format, this means the file must contain one * top level `%xkb_keymap` section, which in turn contains other required * sections. * * @memberof xkb_keymap */ XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_file(struct xkb_context *context, FILE *file, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags); /** * Create a keymap from a keymap string. * * This is just like `xkb_keymap_new_from_file()`, but instead of a file, gets * the keymap as one enormous string. * * @see `xkb_keymap_new_from_file()` * @memberof xkb_keymap */ XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_string(struct xkb_context *context, const char *string, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags); /** * Create a keymap from a memory buffer. * * This is just like `xkb_keymap_new_from_string()`, but takes a length argument * so the input string does not have to be zero-terminated. * * @see `xkb_keymap_new_from_string()` * @memberof xkb_keymap * @since 0.3.0 */ XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_buffer(struct xkb_context *context, const char *buffer, size_t length, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags); /** * Take a new reference on a keymap. * * @returns The passed in keymap. * * @memberof xkb_keymap */ XKB_EXPORT struct xkb_keymap * xkb_keymap_ref(struct xkb_keymap *keymap); /** * Release a reference on a keymap, and possibly free it. * * @param keymap The keymap. If it is `NULL`, this function does nothing. * * @memberof xkb_keymap */ XKB_EXPORT void xkb_keymap_unref(struct xkb_keymap *keymap); /** * Get the keymap as a string in the format from which it was created. * @sa `xkb_keymap::xkb_keymap_get_as_string()` **/ #define XKB_KEYMAP_USE_ORIGINAL_FORMAT ((enum xkb_keymap_format) -1) /** * Flags to control keymap serialization. * * @since 1.12.0 */ enum xkb_keymap_serialize_flags { /** Do not apply any flags. */ XKB_KEYMAP_SERIALIZE_NO_FLAGS = 0, /** Enable pretty-printing */ XKB_KEYMAP_SERIALIZE_PRETTY = (1 << 0), /** Do not drop unused bits (key types, compatibility entries) */ XKB_KEYMAP_SERIALIZE_KEEP_UNUSED = (1 << 1), }; /** * Get the compiled keymap as a string. * * Same as `xkb_keymap::xkb_keymap_get_as_string2()` using * `::XKB_KEYMAP_SERIALIZE_NO_FLAGS`. * * @since 1.12.0: Drop unused types and compatibility entries and do not * pretty-print. * * @sa `xkb_keymap::xkb_keymap_get_as_string2()` * @memberof xkb_keymap */ XKB_EXPORT char * xkb_keymap_get_as_string(struct xkb_keymap *keymap, enum xkb_keymap_format format); /** * Get the compiled keymap as a string. * * @param keymap The keymap to get as a string. * @param format The keymap format to use for the string. You can pass * in the special value `::XKB_KEYMAP_USE_ORIGINAL_FORMAT` to use the format * from which the keymap was originally created. When used as an *interchange* * format such as Wayland [xkb_v1], the format should be explicit. * @param flags Optional flags to control the serialization, or 0. * * @returns The keymap as a `NULL`-terminated string, or `NULL` if unsuccessful. * * The returned string may be fed back into `xkb_keymap_new_from_string()` * to get the exact same keymap (possibly in another process, etc.). * * The returned string is *dynamically allocated* and should be freed by the * caller. * * @since 1.12.0 * * @sa `xkb_keymap_get_as_string()` * @sa `xkb_keymap_new_from_string()` * @memberof xkb_keymap * * [xkb_v1]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard-enum-keymap_format */ XKB_EXPORT char * xkb_keymap_get_as_string2(struct xkb_keymap *keymap, enum xkb_keymap_format format, enum xkb_keymap_serialize_flags flags); /** @} */ /** * @defgroup components Keymap Components * Enumeration of state components in a keymap. * * @{ */ /** * Get the minimum keycode in the keymap. * * @sa xkb_keycode_t * @memberof xkb_keymap * @since 0.3.1 */ XKB_EXPORT xkb_keycode_t xkb_keymap_min_keycode(struct xkb_keymap *keymap); /** * Get the maximum keycode in the keymap. * * @sa xkb_keycode_t * @memberof xkb_keymap * @since 0.3.1 */ XKB_EXPORT xkb_keycode_t xkb_keymap_max_keycode(struct xkb_keymap *keymap); /** * The iterator used by `xkb_keymap_key_for_each()`. * * @sa xkb_keymap_key_for_each * @memberof xkb_keymap * @since 0.3.1 */ typedef void (*xkb_keymap_key_iter_t)(struct xkb_keymap *keymap, xkb_keycode_t key, void *data); /** * Run a specified function for every valid keycode in the keymap. If a * keymap is sparse, this function may be called fewer than * (max_keycode - min_keycode + 1) times. * * @sa xkb_keymap_min_keycode() * @sa xkb_keymap_max_keycode() * @sa xkb_keycode_t * @memberof xkb_keymap * @since 0.3.1 */ XKB_EXPORT void xkb_keymap_key_for_each(struct xkb_keymap *keymap, xkb_keymap_key_iter_t iter, void *data); /** * Find the name of the key with the given keycode. * * This function always returns the canonical name of the key (see * description in `xkb_keycode_t`). * * @returns The key name. If no key with this keycode exists, * returns `NULL`. * * @sa xkb_keycode_t * @memberof xkb_keymap * @since 0.6.0 */ XKB_EXPORT const char * xkb_keymap_key_get_name(struct xkb_keymap *keymap, xkb_keycode_t key); /** * Find the keycode of the key with the given name. * * The name can be either a canonical name or an alias. * * @returns The keycode. If no key with this name exists, * returns `::XKB_KEYCODE_INVALID`. * * @sa xkb_keycode_t * @memberof xkb_keymap * @since 0.6.0 */ XKB_EXPORT xkb_keycode_t xkb_keymap_key_by_name(struct xkb_keymap *keymap, const char *name); /** * Get the number of modifiers in the keymap. * * @sa xkb_mod_index_t * @memberof xkb_keymap */ XKB_EXPORT xkb_mod_index_t xkb_keymap_num_mods(struct xkb_keymap *keymap); /** * Get the name of a modifier by index. * * @returns The name. If the index is invalid, returns `NULL`. * * @sa xkb_mod_index_t * @memberof xkb_keymap */ XKB_EXPORT const char * xkb_keymap_mod_get_name(struct xkb_keymap *keymap, xkb_mod_index_t idx); /** * Get the index of a modifier by name. * * @returns The index. If no modifier with this name exists, returns * `::XKB_MOD_INVALID`. * * @sa xkb_mod_index_t * @memberof xkb_keymap */ XKB_EXPORT xkb_mod_index_t xkb_keymap_mod_get_index(struct xkb_keymap *keymap, const char *name); /** * Get the encoding of a modifier by name. * * In X11 terminology it corresponds to the mapping to the *[real modifiers]*. * * @returns The encoding of a modifier. Note that it may be 0 if the name does * not exist or if the modifier is not mapped. * * @since 1.10.0 * @sa `xkb_keymap_mod_get_mask2()` * @memberof xkb_keymap * * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT xkb_mod_mask_t xkb_keymap_mod_get_mask(struct xkb_keymap *keymap, const char *name); /** * Get the encoding of a modifier by index. * * In X11 terminology it corresponds to the mapping to the *[real modifiers]*. * * @returns The encoding of a modifier. Note that it may be 0 if the modifier is * not mapped. * * @since 1.11.0 * @sa `xkb_keymap_mod_get_mask()` * @memberof xkb_keymap * * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT xkb_mod_mask_t xkb_keymap_mod_get_mask2(struct xkb_keymap *keymap, xkb_mod_index_t idx); /** * Get the number of layouts in the keymap. * * @sa `xkb_layout_index_t` * @sa `xkb_rule_names` * @sa `xkb_keymap_num_layouts_for_key()` * @memberof xkb_keymap */ XKB_EXPORT xkb_layout_index_t xkb_keymap_num_layouts(struct xkb_keymap *keymap); /** * Get the name of a layout by index. * * @returns The name. If the index is invalid, or the layout does not have * a name, returns `NULL`. * * @sa xkb_layout_index_t * For notes on layout names. * @memberof xkb_keymap */ XKB_EXPORT const char * xkb_keymap_layout_get_name(struct xkb_keymap *keymap, xkb_layout_index_t idx); /** * Get the index of a layout by name. * * @returns The index. If no layout exists with this name, returns * `::XKB_LAYOUT_INVALID`. If more than one layout in the keymap has this name, * returns the lowest index among them. * * @sa `xkb_layout_index_t` for notes on layout names. * @memberof xkb_keymap */ XKB_EXPORT xkb_layout_index_t xkb_keymap_layout_get_index(struct xkb_keymap *keymap, const char *name); /** * Get the number of LEDs in the keymap. * * @warning The range [ 0...`xkb_keymap_num_leds()` ) includes all of the LEDs * in the keymap, but may also contain inactive LEDs. When iterating over * this range, you need the handle this case when calling functions such as * `xkb_keymap_led_get_name()` or `xkb_state::xkb_state_led_index_is_active()`. * * @sa xkb_led_index_t * @memberof xkb_keymap */ XKB_EXPORT xkb_led_index_t xkb_keymap_num_leds(struct xkb_keymap *keymap); /** * Get the name of a LED by index. * * @returns The name. If the index is invalid, returns `NULL`. * * @memberof xkb_keymap */ XKB_EXPORT const char * xkb_keymap_led_get_name(struct xkb_keymap *keymap, xkb_led_index_t idx); /** * Get the index of a LED by name. * * @returns The index. If no LED with this name exists, returns * `::XKB_LED_INVALID`. * * @memberof xkb_keymap */ XKB_EXPORT xkb_led_index_t xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name); /** * Get the number of layouts for a specific key. * * This number can be different from `xkb_keymap_num_layouts()`, but is always * smaller. It is the appropriate value to use when iterating over the * layouts of a key. * * @sa xkb_layout_index_t * @memberof xkb_keymap */ XKB_EXPORT xkb_layout_index_t xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key); /** * Get the number of shift levels for a specific key and layout. * * If @c layout is out of range for this key (that is, larger or equal to * the value returned by `xkb_keymap_num_layouts_for_key()`), it is brought * back into range in a manner consistent with * `xkb_state::xkb_state_key_get_layout()`. * * @sa xkb_level_index_t * @memberof xkb_keymap */ XKB_EXPORT xkb_level_index_t xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key, xkb_layout_index_t layout); /** * Retrieves every possible modifier mask that produces the specified * shift level for a specific key and layout. * * This API is useful for inverse key transformation; i.e. finding out * which modifiers need to be active in order to be able to type the * keysym(s) corresponding to the specific key code, layout and level. * * @warning It returns only up to masks_size modifier masks. If the * buffer passed is too small, some of the possible modifier combinations * will not be returned. * * @param[in] keymap The keymap. * @param[in] key The keycode of the key. * @param[in] layout The layout for which to get modifiers. * @param[in] level The shift level in the layout for which to get the * modifiers. This should be smaller than: * @code xkb_keymap_num_levels_for_key(keymap, key) @endcode * @param[out] masks_out A buffer in which the requested masks should be * stored. * @param[out] masks_size The number of elements in the buffer pointed to by * masks_out. * * If @c layout is out of range for this key (that is, larger or equal to * the value returned by `xkb_keymap_num_layouts_for_key()`), it is brought * back into range in a manner consistent with * `xkb_state::xkb_state_key_get_layout()`. * * @returns The number of modifier masks stored in the masks_out array. * If the key is not in the keymap or if the specified shift level cannot * be reached it returns 0 and does not modify the masks_out buffer. * * @sa xkb_level_index_t * @sa xkb_mod_mask_t * @memberof xkb_keymap * @since 1.0.0 */ XKB_EXPORT size_t xkb_keymap_key_get_mods_for_level(struct xkb_keymap *keymap, xkb_keycode_t key, xkb_layout_index_t layout, xkb_level_index_t level, xkb_mod_mask_t *masks_out, size_t masks_size); /** * Get the keysyms obtained from pressing a key in a given layout and * shift level. * * This function is like `xkb_state::xkb_state_key_get_syms()`, only the layout * and shift level are not derived from the keyboard state but are instead * specified explicitly. * * @param[in] keymap The keymap. * @param[in] key The keycode of the key. * @param[in] layout The layout for which to get the keysyms. * @param[in] level The shift level in the layout for which to get the * keysyms. This should be smaller than: * @code xkb_keymap_num_levels_for_key(keymap, key) @endcode * @param[out] syms_out An immutable array of keysyms corresponding to the * key in the given layout and shift level. * * If @c layout is out of range for this key (that is, larger or equal to * the value returned by `xkb_keymap_num_layouts_for_key()`), it is brought * back into range in a manner consistent with * `xkb_state::xkb_state_key_get_layout()`. * * @returns The number of keysyms in the syms_out array. If no keysyms * are produced by the key in the given layout and shift level, returns 0 * and sets @p syms_out to `NULL`. * * @sa `xkb_state::xkb_state_key_get_syms()` * @memberof xkb_keymap */ XKB_EXPORT int xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap, xkb_keycode_t key, xkb_layout_index_t layout, xkb_level_index_t level, const xkb_keysym_t **syms_out); /** * Determine whether a key should repeat or not. * * A keymap may specify different repeat behaviors for different keys. * Most keys should generally exhibit repeat behavior; for example, holding * the `a` key down in a text editor should normally insert a single ‘a’ * character every few milliseconds, until the key is released. However, * there are keys which should not or do not need to be repeated. For * example, repeating modifier keys such as Left/Right Shift or Caps Lock * is not generally useful or desired. * * @returns 1 if the key should repeat, 0 otherwise. * * @memberof xkb_keymap */ XKB_EXPORT int xkb_keymap_key_repeats(struct xkb_keymap *keymap, xkb_keycode_t key); /** @} */ /** * @defgroup state Keyboard State * Creating, destroying and manipulating keyboard state objects. * * @{ */ /** * Create a new keyboard state object. * * @param keymap The keymap which the state will use. * * @returns A new keyboard state object, or `NULL` on failure. * * @memberof xkb_state */ XKB_EXPORT struct xkb_state * xkb_state_new(struct xkb_keymap *keymap); /** * Take a new reference on a keyboard state object. * * @returns The passed in object. * * @memberof xkb_state */ XKB_EXPORT struct xkb_state * xkb_state_ref(struct xkb_state *state); /** * Release a reference on a keyboard state object, and possibly free it. * * @param state The state. If it is `NULL`, this function does nothing. * * @memberof xkb_state */ XKB_EXPORT void xkb_state_unref(struct xkb_state *state); /** * Get the keymap which a keyboard state object is using. * * @returns The keymap which was passed to `xkb_state_new()` when creating * this state object. * * This function does not take a new reference on the keymap; you must * explicitly reference it yourself if you plan to use it beyond the * lifetime of the state. * * @memberof xkb_state */ XKB_EXPORT 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. */ XKB_KEY_DOWN /**< The key was pressed. */ }; /** * Modifier and layout types for state objects. 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*. */ enum xkb_state_component { /** Depressed modifiers, i.e. a key is physically holding them. */ XKB_STATE_MODS_DEPRESSED = (1 << 0), /** Latched modifiers, i.e. will be unset after the next non-modifier * key press. */ XKB_STATE_MODS_LATCHED = (1 << 1), /** Locked modifiers, i.e. will be unset after the key provoking the * lock has been pressed again. */ XKB_STATE_MODS_LOCKED = (1 << 2), /** 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_MODS_EFFECTIVE = (1 << 3), /** Depressed layout, i.e. a key is physically holding it. */ XKB_STATE_LAYOUT_DEPRESSED = (1 << 4), /** Latched layout, i.e. will be unset after the next non-modifier * key press. */ XKB_STATE_LAYOUT_LATCHED = (1 << 5), /** Locked layout, i.e. will be unset after the key provoking the lock * has been pressed again. */ XKB_STATE_LAYOUT_LOCKED = (1 << 6), /** 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_LAYOUT_EFFECTIVE = (1 << 7), /** LEDs (derived from the other state components). */ XKB_STATE_LEDS = (1 << 8) }; /** * 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 @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 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. * * @returns A mask of state components that have changed as a result of * the update. If nothing in the state has changed, returns 0. * * @memberof xkb_state * * @sa `xkb_state_update_mask()` */ 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 change the latched and locked state of * the modifiers and layout. * * This entry point is intended for *server* applications and should not be used * by *client* applications; see @ref server-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. * * @par Layout out of range * @parblock * * 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 * may be made configurable in the future. * * @endparblock * * @param state The keyboard state object. * @param affect_latched_mods * @param latched_mods * Modifiers to set as latched or unlatched. Only modifiers in * @p affect_latched_mods are considered. * @param affect_latched_layout * @param latched_layout * Layout to latch. Only considered if @p affect_latched_layout is true. * Maybe be out of range (including negative) -- see note above. * @param affect_locked_mods * @param locked_mods * Modifiers to set as locked or unlocked. Only modifiers in * @p affect_locked_mods are considered. * @param affect_locked_layout * @param locked_layout * Layout to lock. Only considered if @p affect_locked_layout is true. * Maybe be out of range (including negative) -- see note above. * * @returns A mask of state components that have changed as a result of * the update. If nothing in the state has changed, returns 0. * * @memberof xkb_state * * @sa xkb_state_update_mask() */ 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 a keyboard state from a set of explicit masks. * * 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. * * @warning The serialization is lossy and will not survive round trips; it must * only 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. * * @memberof xkb_state * * @sa `xkb_state_component` * @sa `xkb_state_update_key()` */ XKB_EXPORT enum xkb_state_component xkb_state_update_mask(struct xkb_state *state, xkb_mod_mask_t depressed_mods, xkb_mod_mask_t latched_mods, xkb_mod_mask_t locked_mods, xkb_layout_index_t depressed_layout, xkb_layout_index_t latched_layout, xkb_layout_index_t locked_layout); /** * Get the keysyms obtained from pressing a particular key in a given * keyboard state. * * Get the keysyms for a key according to the current active layout, * modifiers and shift level for the key, as determined by a keyboard * state. * * @param[in] state The keyboard state object. * @param[in] key The keycode of the key. * @param[out] syms_out An immutable array of keysyms corresponding the * key in the given keyboard state. * * As an extension to XKB, this function can return more than one keysym. * If you do not want to handle this case, you can use * `xkb_state_key_get_one_sym()` for a simpler interface. * * @returns The number of keysyms in the syms_out array. If no keysyms * are produced by the key in the given keyboard state, returns 0 and sets * syms_out to `NULL`. * * This function performs Capitalization @ref keysym-transformations. * * @memberof xkb_state * * @since 1.9.0 This function now performs @ref keysym-transformations. */ XKB_EXPORT int xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key, const xkb_keysym_t **syms_out); /** * Get the Unicode/UTF-8 string obtained from pressing a particular key * in a given keyboard state. * * @param[in] state The keyboard state object. * @param[in] key The keycode of the key. * @param[out] buffer A buffer to write the string into. * @param[in] size Size of the buffer. * * @warning If the buffer passed is too small, the string is truncated * (though still `NULL`-terminated). * * @returns The number of bytes required for the string, excluding the * `NULL` byte. If there is nothing to write, returns 0. * * You may check if truncation has occurred by comparing the return value * with the size of @p buffer, similarly to the `snprintf(3)` function. * You may safely pass `NULL` and 0 to @p buffer and @p size to find the * required size (without the `NULL`-byte). * * This function performs Capitalization and Control @ref * keysym-transformations. * * @memberof xkb_state * @since 0.4.1 */ XKB_EXPORT int xkb_state_key_get_utf8(struct xkb_state *state, xkb_keycode_t key, char *buffer, size_t size); /** * Get the Unicode/UTF-32 codepoint obtained from pressing a particular * key in a a given keyboard state. * * @returns The UTF-32 representation for the key, if it consists of only * a single codepoint. Otherwise, returns 0. * * This function performs Capitalization and Control @ref * keysym-transformations. * * @memberof xkb_state * @since 0.4.1 */ XKB_EXPORT uint32_t xkb_state_key_get_utf32(struct xkb_state *state, xkb_keycode_t key); /** * Get the single keysym obtained from pressing a particular key in a * given keyboard state. * * This function is similar to `xkb_state_key_get_syms()`, but intended * for users which cannot or do not want to handle the case where * multiple keysyms are returned (in which case this function is * preferred). * * @returns The keysym. If the key does not have exactly one keysym, * returns `XKB_KEY_NoSymbol`. * * This function performs Capitalization @ref keysym-transformations. * * @sa xkb_state_key_get_syms() * @memberof xkb_state */ XKB_EXPORT xkb_keysym_t xkb_state_key_get_one_sym(struct xkb_state *state, xkb_keycode_t key); /** * Get the effective layout index for a key in a given keyboard state. * * @returns The layout index for the key in the given keyboard state. If * the given keycode is invalid, or if the key is not included in any * layout at all, returns `::XKB_LAYOUT_INVALID`. * * @invariant If the returned layout is valid, the following always holds: * @code * xkb_state_key_get_layout(state, key) < xkb_keymap_num_layouts_for_key(keymap, key) * @endcode * * @memberof xkb_state */ XKB_EXPORT xkb_layout_index_t xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t key); /** * Get the effective shift level for a key in a given keyboard state and * layout. * * @param state The keyboard state. * @param key The keycode of the key. * @param layout The layout for which to get the shift level. This must be * smaller than: * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode * usually it would be: * @code xkb_state_key_get_layout(state, key) @endcode * * @return The shift level index. If the key or layout are invalid, * returns `::XKB_LEVEL_INVALID`. * * @invariant If the returned level is valid, the following always holds: * @code * xkb_state_key_get_level(state, key, layout) < xkb_keymap_num_levels_for_key(keymap, key, layout) * @endcode * * @memberof xkb_state */ XKB_EXPORT xkb_level_index_t xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key, xkb_layout_index_t layout); /** * Match flags for `xkb_state::xkb_state_mod_indices_are_active()` and * `xkb_state::xkb_state_mod_names_are_active()`, specifying the conditions for a * successful match. `::XKB_STATE_MATCH_NON_EXCLUSIVE` is bitmaskable with * the other modes. */ enum xkb_state_match { /** Returns true if any of the modifiers are active. */ XKB_STATE_MATCH_ANY = (1 << 0), /** Returns true if all of the modifiers are active. */ XKB_STATE_MATCH_ALL = (1 << 1), /** Makes matching non-exclusive, i.e. will not return false if a * modifier not specified in the arguments is active. */ XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16) }; /** * The counterpart to `xkb_state::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. * If `::XKB_STATE_MODS_EFFECTIVE` is included, all other state components are * ignored. * * @returns A `xkb_mod_mask_t` representing the given components of the * modifier state. * * @memberof xkb_state */ XKB_EXPORT xkb_mod_mask_t xkb_state_serialize_mods(struct xkb_state *state, enum xkb_state_component components); /** * The counterpart to `xkb_state::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. * If `::XKB_STATE_LAYOUT_EFFECTIVE` is included, all other state components are * ignored. * * @returns A layout index representing the given components of the * layout state. * * @memberof xkb_state */ XKB_EXPORT xkb_layout_index_t xkb_state_serialize_layout(struct xkb_state *state, enum xkb_state_component components); /** * Test whether a modifier is active in a given keyboard state by name. * * @warning For [virtual modifiers], this function may *overmatch* in case * there are virtual modifiers with overlapping mappings to [real modifiers]. * * @returns 1 if the modifier is active, 0 if it is not. If the modifier * name does not exist in the keymap, returns -1. * * @memberof xkb_state * * @since 0.1.0: Works only with *real* modifiers * @since 1.8.0: Works also with *virtual* modifiers * * [virtual modifiers]: @ref virtual-modifier-def * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT int xkb_state_mod_name_is_active(struct xkb_state *state, const char *name, enum xkb_state_component type); /** * Test whether a set of modifiers are active in a given keyboard state by * name. * * @warning For [virtual modifiers], this function may *overmatch* in case * there are virtual modifiers with overlapping mappings to [real modifiers]. * * @param state The keyboard state. * @param type The component of the state against which to match the * given modifiers. * @param match The manner by which to match the state against the * given modifiers. * @param ... The set of of modifier names to test, terminated by a NULL * argument (sentinel). * * @returns 1 if the modifiers are active, 0 if they are not. If any of * the modifier names do not exist in the keymap, returns -1. * * @memberof xkb_state * * @since 0.1.0: Works only with *real* modifiers * @since 1.8.0: Works also with *virtual* modifiers * * [virtual modifiers]: @ref virtual-modifier-def * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT int xkb_state_mod_names_are_active(struct xkb_state *state, enum xkb_state_component type, enum xkb_state_match match, ...); /** * Test whether a modifier is active in a given keyboard state by index. * * @warning For [virtual modifiers], this function may *overmatch* in case * there are virtual modifiers with overlapping mappings to [real modifiers]. * * @returns 1 if the modifier is active, 0 if it is not. If the modifier * index is invalid in the keymap, returns -1. * * @memberof xkb_state * * @since 0.1.0: Works only with *real* modifiers * @since 1.8.0: Works also with *virtual* modifiers * * [virtual modifiers]: @ref virtual-modifier-def * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT int xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx, enum xkb_state_component type); /** * Test whether a set of modifiers are active in a given keyboard state by * index. * * @warning For [virtual modifiers], this function may *overmatch* in case * there are virtual modifiers with overlapping mappings to [real modifiers]. * * @param state The keyboard state. * @param type The component of the state against which to match the * given modifiers. * @param match The manner by which to match the state against the * given modifiers. * @param ... The set of of modifier indices to test, terminated by a * `::XKB_MOD_INVALID` argument (sentinel). * * @returns 1 if the modifiers are active, 0 if they are not. If any of * the modifier indices are invalid in the keymap, returns -1. * * @memberof xkb_state * * @since 0.1.0: Works only with *real* modifiers * @since 1.8.0: Works also with *virtual* modifiers * * [virtual modifiers]: @ref virtual-modifier-def * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT int xkb_state_mod_indices_are_active(struct xkb_state *state, enum xkb_state_component type, enum xkb_state_match match, ...); /** * @page consumed-modifiers Consumed Modifiers * @parblock * * Some functions, like `xkb_state::xkb_state_key_get_syms()`, look at the state * of the modifiers in the keymap and derive from it the correct shift level * to use for the key. For example, in a US layout, pressing the key * labeled `` while the Shift modifier is active, generates the keysym * `A`. In this case, the Shift modifier is said to be *consumed*. * However, the Num Lock modifier does not affect this translation at all, * even if it is active, so it is not consumed by this translation. * * It may be desirable for some application to not reuse consumed modifiers * for further processing, e.g. for hotkeys or keyboard shortcuts. To * understand why, consider some requirements from a standard shortcut * mechanism, and how they are implemented: * * 1. The shortcut’s modifiers must match exactly to the state. For * example, it is possible to bind separate actions to `` * and to ``. Further, if only `` is * bound to an action, pressing `` should not * trigger the shortcut. * Effectively, this means that the modifiers are compared using the * equality operator (`==`). * * 2. Only relevant modifiers are considered for the matching. For example, * Caps Lock and Num Lock should not generally affect the matching, e.g. * when matching `` against the state, it does not matter * whether Num Lock is active or not. These relevant, or *significant*, * modifiers usually include Alt, Control, Shift, Super and similar. * Effectively, this means that non-significant modifiers are masked out, * before doing the comparison as described above. * * 3. The matching must be independent of the layout/keymap. For example, * the `` (+) symbol is found on the first level on some layouts, * but requires holding Shift on others. If you simply bind the action * to the `` keysym, it would work for the unshifted kind, but * not for the others, because the match against Shift would fail. If * you bind the action to ``, only the shifted kind would * work. So what is needed is to recognize that Shift is used up in the * translation of the keysym itself, and therefore should not be included * in the matching. * Effectively, this means that consumed modifiers (Shift in this example) * are masked out as well, before doing the comparison. * * In summary, this is approximately how the matching would be performed: * * ```c * (keysym == shortcut_keysym) && * ((state_mods & ~consumed_mods & significant_mods) == shortcut_mods) * ``` * * @c state_mods are the modifiers reported by * `xkb_state::xkb_state_mod_index_is_active()` and similar functions. * @c consumed_mods are the modifiers reported by * `xkb_state::xkb_state_mod_index_is_consumed()` and similar functions. * @c significant_mods are decided upon by the application/toolkit/user; * it is up to them to decide whether these are configurable or hard-coded. * * @endparblock */ /** * Consumed modifiers mode. * * There are several possible methods for deciding which modifiers are * consumed and which are not, each applicable for different systems or * situations. The mode selects the method to use. * * Keep in mind that in all methods, the keymap may decide to *preserve* * a modifier, meaning it is not reported as consumed even if it would * have otherwise. */ enum xkb_consumed_mode { /** * This is the mode defined in the XKB specification and used by libX11. * * A modifier is consumed if and only if it *may affect* key translation. * * For example, if `Control+Alt+` produces some assigned keysym, * then when pressing just ``, `Control` and `Alt` are consumed, * even though they are not active, since if they *were* active they would * have affected key translation. */ XKB_CONSUMED_MODE_XKB, /** * This is the mode used by the GTK+ toolkit. * * The mode consists of the following two independent heuristics: * * - The currently active set of modifiers, excluding modifiers which do * not affect the key (as described for @ref XKB_CONSUMED_MODE_XKB), are * considered consumed, if the keysyms produced when all of them are * active are different from the keysyms produced when no modifiers are * active. * * - A single modifier is considered consumed if the keysyms produced for * the key when it is the only active modifier are different from the * keysyms produced when no modifiers are active. */ XKB_CONSUMED_MODE_GTK }; /** * Get the mask of modifiers consumed by translating a given key. * * @param state The keyboard state. * @param key The keycode of the key. * @param mode The consumed modifiers mode to use; see enum description. * * @returns a mask of the consumed [real modifiers] modifiers. * * @memberof xkb_state * @since 0.7.0 * * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT xkb_mod_mask_t xkb_state_key_get_consumed_mods2(struct xkb_state *state, xkb_keycode_t key, enum xkb_consumed_mode mode); /** * Same as `xkb_state_key_get_consumed_mods2()` with mode `::XKB_CONSUMED_MODE_XKB`. * * @memberof xkb_state * @since 0.4.1 */ XKB_EXPORT xkb_mod_mask_t xkb_state_key_get_consumed_mods(struct xkb_state *state, xkb_keycode_t key); /** * Test whether a modifier is consumed by keyboard state translation for * a key. * * @warning For [virtual modifiers], this function may *overmatch* in case * there are virtual modifiers with overlapping mappings to [real modifiers]. * * @param state The keyboard state. * @param key The keycode of the key. * @param idx The index of the modifier to check. * @param mode The consumed modifiers mode to use; see enum description. * * @returns 1 if the modifier is consumed, 0 if it is not. If the modifier * index is not valid in the keymap, returns -1. * * @sa xkb_state_mod_mask_remove_consumed() * @sa xkb_state_key_get_consumed_mods() * @memberof xkb_state * @since 0.7.0: Works only with *real* modifiers * @since 1.8.0: Works also with *virtual* modifiers * * [virtual modifiers]: @ref virtual-modifier-def * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT int xkb_state_mod_index_is_consumed2(struct xkb_state *state, xkb_keycode_t key, xkb_mod_index_t idx, enum xkb_consumed_mode mode); /** * Same as `xkb_state_mod_index_is_consumed2()` with mode `::XKB_CONSUMED_MOD_XKB`. * * @warning For [virtual modifiers], this function may *overmatch* in case * there are virtual modifiers with overlapping mappings to [real modifiers]. * * @memberof xkb_state * @since 0.4.1: Works only with *real* modifiers * @since 1.8.0: Works also with *virtual* modifiers * * [virtual modifiers]: @ref virtual-modifier-def * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT int xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key, xkb_mod_index_t idx); /** * Remove consumed modifiers from a modifier mask for a key. * * @deprecated Use `xkb_state_key_get_consumed_mods2()` instead. * * Takes the given modifier mask, and removes all modifiers which are * consumed for that particular key (as in `xkb_state_mod_index_is_consumed()`). * * @returns a mask of [real modifiers] modifiers. * * @sa xkb_state_mod_index_is_consumed() * @memberof xkb_state * @since 0.5.0: Works only with *real* modifiers * @since 1.8.0: Works also with *virtual* modifiers * * [real modifiers]: @ref real-modifier-def */ XKB_EXPORT xkb_mod_mask_t xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t key, xkb_mod_mask_t mask); /** * Test whether a layout is active in a given keyboard state by name. * * @returns 1 if the layout is active, 0 if it is not. If no layout with * this name exists in the keymap, return -1. * * If multiple layouts in the keymap have this name, the one with the lowest * index is tested. * * @sa xkb_layout_index_t * @memberof xkb_state */ XKB_EXPORT int xkb_state_layout_name_is_active(struct xkb_state *state, const char *name, enum xkb_state_component type); /** * Test whether a layout is active in a given keyboard state by index. * * @returns 1 if the layout is active, 0 if it is not. If the layout index * is not valid in the keymap, returns -1. * * @sa xkb_layout_index_t * @memberof xkb_state */ XKB_EXPORT int xkb_state_layout_index_is_active(struct xkb_state *state, xkb_layout_index_t idx, enum xkb_state_component type); /** * Test whether a LED is active in a given keyboard state by name. * * @returns 1 if the LED is active, 0 if it not. If no LED with this name * exists in the keymap, returns -1. * * @sa xkb_led_index_t * @memberof xkb_state */ XKB_EXPORT int xkb_state_led_name_is_active(struct xkb_state *state, const char *name); /** * Test whether a LED is active in a given keyboard state by index. * * @returns 1 if the LED is active, 0 if it not. If the LED index is not * valid in the keymap, returns -1. * * @sa xkb_led_index_t * @memberof xkb_state */ XKB_EXPORT int xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx); /** @} */ /* Leave this include last, so it can pick up our types, etc. */ #include #ifdef __cplusplus } /* extern "C" */ #endif #endif /* _XKBCOMMON_H_ */