diff options
Diffstat (limited to 'src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h')
| -rw-r--r-- | src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h | 140 |
1 files changed, 117 insertions, 23 deletions
diff --git a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h index cc9262ff89..36251db443 100644 --- a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h +++ b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h @@ -305,26 +305,60 @@ typedef uint32_t xkb_led_mask_t; /** * Names to compile a keymap with, also known as RMLVO. * - * These names together are the primary identifier for a keymap. - * If any of the members is NULL or an empty string (""), a default value is - * used. It is recommended to use the system default by passing NULL for - * unspecified values, instead of providing your own defaults. + * 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. */ 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. */ + /** + * 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. */ + /** + * 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. */ + /** + * 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. */ + /** + * A comma separated list of variants, one per layout, which may + * modify or augment the respective layout in various ways. + * + * 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. */ + /** + * 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. + */ const char *options; }; @@ -399,6 +433,11 @@ xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags); * @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. + * + * Prefer not to use this function on keysyms obtained from an + * xkb_state. In this case, use xkb_state_key_get_utf8() instead. + * + * @sa xkb_state_key_get_utf8() */ int xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size); @@ -409,6 +448,11 @@ xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size); * @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. + * + * Prefer not to use this function on keysyms obtained from an + * xkb_state. In this case, use xkb_state_key_get_utf32() instead. + * + * @sa xkb_state_key_get_utf32() */ uint32_t xkb_keysym_to_utf32(xkb_keysym_t keysym); @@ -681,9 +725,7 @@ xkb_context_set_log_fn(struct xkb_context *context, /** Flags for keymap compilation. */ enum xkb_keymap_compile_flags { /** Do not apply any flags. */ - XKB_MAP_COMPILE_NO_FLAGS = 0, - /** Apparently you can't have empty enums. What a drag. */ - XKB_MAP_COMPILE_PLACEHOLDER = 0 + XKB_KEYMAP_COMPILE_NO_FLAGS = 0 }; /** @@ -692,13 +734,8 @@ enum xkb_keymap_compile_flags { * The primary keymap entry point: creates a new XKB keymap from a set of * RMLVO (Rules + Model + Layouts + Variants + Options) names. * - * You should almost certainly be using this and nothing else to create - * keymaps. - * * @param context The context in which to create the keymap. - * @param names The RMLVO names to use. In xkbcommon versions prior - * to 0.2.1, this field must be non-NULL. In later - * versions, passing NULL will use the default keymap. + * @param names The RMLVO names to use. See xkb_rule_names. * @param flags Optional flags for the keymap, or 0. * * @returns A keymap compiled according to the RMLVO names, or NULL if @@ -1159,6 +1196,13 @@ enum xkb_state_component { * 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. * @@ -1235,6 +1279,44 @@ 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 NUL-terminated). + * + * @returns The number of bytes required for the string, excluding the + * NUL 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 NUL-byte). + * + * @memberof xkb_state + */ +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. + * + * @memberof xkb_state + */ +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. * @@ -1485,6 +1567,7 @@ xkb_state_mod_indices_are_active(struct xkb_state *state, * 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 */ int @@ -1505,6 +1588,17 @@ 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 |