diff options
Diffstat (limited to 'src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h')
| -rw-r--r-- | src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h | 386 |
1 files changed, 295 insertions, 91 deletions
diff --git a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h index 36251db443..c28123f95e 100644 --- a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h +++ b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h @@ -152,6 +152,10 @@ struct xkb_state; * 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 @@ -173,7 +177,7 @@ typedef uint32_t xkb_keycode_t; * somewhat more general, in that they can also represent some "function", * such as "Left" or "Right" for the arrow keys. For more information, * see: - * http://www.x.org/releases/X11R7.7/doc/xproto/x11protocol.html#keysym_encoding + * https://www.x.org/releases/current/doc/xproto/x11protocol.html#keysym_encoding * * Specifically named keysyms can be found in the * xkbcommon/xkbcommon-keysyms.h header file. Their name does not include @@ -370,6 +374,35 @@ struct xkb_rule_names { */ /** + * @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, a single + * keysym is transformed to its 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. @@ -416,6 +449,9 @@ enum xkb_keysym_flags { * 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 @@ -434,8 +470,8 @@ xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags); * terminating byte). If the keysym does not have a Unicode * representation, returns 0. If the buffer is too small, returns -1. * - * Prefer not to use this function on keysyms obtained from an - * xkb_state. In this case, use xkb_state_key_get_utf8() instead. + * This function does not perform any @ref keysym-transformations. + * Therefore, prefer to use xkb_state_key_get_utf8() if possible. * * @sa xkb_state_key_get_utf8() */ @@ -449,14 +485,34 @@ xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size); * compatible with UCS-4. If the keysym does not have a Unicode * representation, returns 0. * - * Prefer not to use this function on keysyms obtained from an - * xkb_state. In this case, use xkb_state_key_get_utf32() instead. + * This function does not perform any @ref keysym-transformations. + * Therefore, prefer to use xkb_state_key_get_utf32() if possible. * * @sa xkb_state_key_get_utf32() */ uint32_t xkb_keysym_to_utf32(xkb_keysym_t keysym); +/** + * Convert a keysym to its uppercase form. + * + * If there is no such form, the keysym is returned unchanged. + * + * The conversion rules may be incomplete; prefer to work with the Unicode + * representation instead, when possible. + */ +xkb_keysym_t +xkb_keysym_to_upper(xkb_keysym_t ks); + +/** + * Convert a keysym to its lowercase form. + * + * The conversion rules may be incomplete; prefer to work with the Unicode + * representation instead, when possible. + */ +xkb_keysym_t +xkb_keysym_to_lower(xkb_keysym_t ks); + /** @} */ /** @@ -469,14 +525,29 @@ xkb_keysym_to_utf32(xkb_keysym_t keysym); * @{ */ +/** + * @page envvars Environment Variables + * + * The user may set some environment variables which affect the library: + * + * - `XKB_CONFIG_ROOT`, `HOME` - see @ref include-path. + * - `XKB_LOG_LEVEL` - see xkb_context_set_log_level(). + * - `XKB_LOG_VERBOSITY` - see 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. */ XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0), - /** Don't take RMLVO names from the environment. */ - XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1), + /** + * Don't take RMLVO names from the environment. + * @since 0.3.0 + */ + XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1) }; /** @@ -486,10 +557,6 @@ enum xkb_context_flags { * * @returns A new context, or NULL on failure. * - * The user may set some environment variables to affect default values in - * the context. See e.g. xkb_context_set_log_level() and - * xkb_context_set_log_verbosity(). - * * @memberof xkb_context */ struct xkb_context * @@ -548,7 +615,12 @@ xkb_context_get_user_data(struct xkb_context *context); * * The include paths are the file-system paths that are searched when an * include statement is encountered during keymap compilation. - * In most cases, the default include paths are sufficient. + * + * The default include paths are: + * - The system XKB root, defined at library configuration time. + * If * the `XKB_CONFIG_ROOT` environment is defined, it is used instead. + * - The path `$HOME/.xkb`, where $HOME is the value of the environment + * variable `HOME`. * * @{ */ @@ -784,7 +856,7 @@ xkb_keymap_new_from_file(struct xkb_context *context, FILE *file, * 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_string() + * @see xkb_keymap_new_from_file() * @memberof xkb_keymap */ struct xkb_keymap * @@ -800,6 +872,7 @@ xkb_keymap_new_from_string(struct xkb_context *context, const char *string, * * @see xkb_keymap_new_from_string() * @memberof xkb_keymap + * @since 0.3.0 */ struct xkb_keymap * xkb_keymap_new_from_buffer(struct xkb_context *context, const char *buffer, @@ -842,7 +915,7 @@ xkb_keymap_unref(struct xkb_keymap *keymap); * * @returns The keymap as a NUL-terminated string, or NULL if unsuccessful. * - * The returned string may be fed back into xkb_map_new_from_string() to get + * 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 @@ -868,6 +941,7 @@ xkb_keymap_get_as_string(struct xkb_keymap *keymap, * * @sa xkb_keycode_t * @memberof xkb_keymap + * @since 0.3.1 */ xkb_keycode_t xkb_keymap_min_keycode(struct xkb_keymap *keymap); @@ -877,6 +951,7 @@ xkb_keymap_min_keycode(struct xkb_keymap *keymap); * * @sa xkb_keycode_t * @memberof xkb_keymap + * @since 0.3.1 */ xkb_keycode_t xkb_keymap_max_keycode(struct xkb_keymap *keymap); @@ -886,6 +961,7 @@ xkb_keymap_max_keycode(struct xkb_keymap *keymap); * * @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, @@ -898,12 +974,44 @@ typedef void * * @sa xkb_keymap_min_keycode() xkb_keymap_max_keycode() xkb_keycode_t * @memberof xkb_keymap + * @since 0.3.1 */ 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 + */ +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_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 @@ -969,6 +1077,41 @@ 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_led_index_is_active(). + * + * @sa xkb_led_index_t + * @memberof xkb_keymap + */ +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 + */ +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_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 @@ -1008,8 +1151,8 @@ xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t 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 must be smaller than: - * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode - * @param[out] syms_out An immutible array of keysyms corresponding to the + * @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 @@ -1031,41 +1174,6 @@ xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap, const xkb_keysym_t **syms_out); /** - * 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_led_index_is_active(). - * - * @sa xkb_led_index_t - * @memberof xkb_keymap - */ -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 - */ -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_led_index_t -xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name); - -/** * Determine whether a key should repeat or not. * * A keymap may specify different repeat behaviors for different keys. @@ -1264,9 +1372,11 @@ xkb_state_update_mask(struct xkb_state *state, * 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 should use - * xkb_state_key_get_one_sym(), which additionally performs transformations - * which are specific to the one-keysym case. + * If you do not want to handle this case, you can use + * xkb_state_key_get_one_sym() for a simpler interface. + * + * This function does not perform any @ref keysym-transformations. + * (This might change). * * @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 @@ -1298,7 +1408,11 @@ xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key, * You may safely pass NULL and 0 to @p buffer and @p size to find the * required size (without the NUL-byte). * + * This function performs Capitalization and Control @ref + * keysym-transformations. + * * @memberof xkb_state + * @since 0.4.1 */ int xkb_state_key_get_utf8(struct xkb_state *state, xkb_keycode_t key, @@ -1311,7 +1425,11 @@ xkb_state_key_get_utf8(struct xkb_state *state, xkb_keycode_t key, * @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 */ uint32_t xkb_state_key_get_utf32(struct xkb_state *state, xkb_keycode_t key); @@ -1328,6 +1446,8 @@ xkb_state_key_get_utf32(struct xkb_state *state, xkb_keycode_t key); * @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 */ @@ -1378,8 +1498,8 @@ xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key, xkb_layout_index_t layout); /** - * Match flags for xkb_state_mod_indices_are_active and - * xkb_state_mod_names_are_active, specifying how the conditions for a + * Match flags for xkb_state_mod_indices_are_active() and + * xkb_state_mod_names_are_active(), specifying the conditions for a * successful match. XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with * the other modes. */ @@ -1508,67 +1628,160 @@ xkb_state_mod_indices_are_active(struct xkb_state *state, ...); /** - * Test whether a modifier is consumed by keyboard state translation for - * a key. + * @page consumed-modifiers Consumed Modifiers + * @parblock * * Some functions, like 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 \<A\> 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 - * active, so it is not consumed by this translation. + * labeled \<A\> 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 + * 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 \<Alt\>\<Tab\> and to - * \<Alt\>\<Shift\>\<Tab\>. Further, if only \<Alt\>\<Tab\> is bound to - * an action, pressing \<Alt\>\<Shift\>\<Tab\> should not trigger the - * shortcut. + * 1. The shortcut's modifiers must match exactly to the state. For + * example, it is possible to bind separate actions to \<Alt\>\<Tab\> + * and to \<Alt\>\<Shift\>\<Tab\>. Further, if only \<Alt\>\<Tab\> is + * bound to an action, pressing \<Alt\>\<Shift\>\<Tab\> 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, + * + * 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 \<Alt\>\<Tab\> against the state, it does not matter - * whether Num Lock is active or not. These relevant, or significant, + * 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, + * + * 3. The matching must be independent of the layout/keymap. For example, * the \<Plus\> (+) symbol is found on the first level on some layouts, - * and requires holding Shift on others. If you simply bind the action + * but requires holding Shift on others. If you simply bind the action * to the \<Plus\> keysym, it would work for the unshifted kind, but - * not for the others, because the match against Shift would fail. If + * not for the others, because the match against Shift would fail. If * you bind the action to \<Shift\>\<Plus\>, only the shifted kind would - * work. So what is needed is to recognize that Shift is used up in the + * 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. * - * To summarize, this is how the matching would be performed: + * In summary, this is approximately how the matching would be performed: * @code * (keysym == shortcut_keysym) && - * ((state_modifiers & ~consumed_modifiers & significant_modifiers) == shortcut_modifiers) + * ((state_mods & ~consumed_mods & significant_mods) == shortcut_mods) * @endcode * - * @c state_modifiers are the modifiers reported by + * @c state_mods are the modifiers reported by * xkb_state_mod_index_is_active() and similar functions. - * @c consumed_modifiers are the modifiers reported by - * xkb_state_mod_index_is_consumed(). - * @c significant_modifiers are decided upon by the application/toolkit/user; + * @c consumed_mods are the modifiers reported by + * 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+<Backspace>` produces some assigned keysym, + * then when pressing just `<Backspace>`, `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 modifiers. + * + * @memberof xkb_state + * @since 0.7.0 + */ +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_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. + * + * @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 + */ +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. + * + * @memberof xkb_state + * @since 0.4.1 */ int xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key, @@ -1577,6 +1790,8 @@ xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key, /** * 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()). * @@ -1588,17 +1803,6 @@ xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t key, xkb_mod_mask_t mask); /** - * Get the mask of modifiers consumed by translating a given key. - * - * @returns a mask of the consumed modifiers. - * - * @sa xkb_state_mod_index_is_consumed() - * @memberof xkb_state - */ -xkb_mod_mask_t -xkb_state_key_get_consumed_mods(struct xkb_state *state, xkb_keycode_t key); - -/** * 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 |