diff options
Diffstat (limited to 'src/3rdparty/xkbcommon/xkbcommon')
| -rw-r--r-- | src/3rdparty/xkbcommon/xkbcommon/xkbcommon-compose.h | 493 | ||||
| -rw-r--r-- | src/3rdparty/xkbcommon/xkbcommon/xkbcommon-keysyms.h | 40 | ||||
| -rw-r--r-- | src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h | 78 | ||||
| -rw-r--r-- | src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h | 386 |
4 files changed, 878 insertions, 119 deletions
diff --git a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-compose.h b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-compose.h new file mode 100644 index 0000000000..25894b9394 --- /dev/null +++ b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-compose.h @@ -0,0 +1,493 @@ +/* + * Copyright © 2013 Ran Benita + * + * Permission is hereby granted, free of charge, to any person obtaining a + * copy of this software and associated documentation files (the "Software"), + * to deal in the Software without restriction, including without limitation + * the rights to use, copy, modify, merge, publish, distribute, sublicense, + * and/or sell copies of the Software, and to permit persons to whom the + * Software is furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice (including the next + * paragraph) shall be included in all copies or substantial portions of the + * Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + * DEALINGS IN THE SOFTWARE. + */ + +#ifndef _XKBCOMMON_COMPOSE_H +#define _XKBCOMMON_COMPOSE_H + +#include <xkbcommon/xkbcommon.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @file + * libxkbcommon Compose API - support for Compose and dead-keys. + */ + +/** + * @defgroup compose Compose and dead-keys support + * Support for Compose and dead-keys. + * @since 0.5.0 + * + * @{ + */ + +/** + * @page compose-overview Overview + * @parblock + * + * Compose and dead-keys are a common feature of many keyboard input + * systems. They extend the range of the keysysm that can be produced + * directly from a keyboard by using a sequence of key strokes, instead + * of just one. + * + * Here are some example sequences, in the libX11 Compose file format: + * + * <dead_acute> <a> : "á" aacute # LATIN SMALL LETTER A WITH ACUTE + * <Multi_key> <A> <T> : "@" at # COMMERCIAL AT + * + * When the user presses a key which produces the `<dead_acute>` keysym, + * nothing initially happens (thus the key is dubbed a "dead-key"). But + * when the user enters `<a>`, "á" is "composed", in place of "a". If + * instead the user had entered a keysym which does not follow + * `<dead_acute>` in any compose sequence, the sequence is said to be + * "cancelled". + * + * Compose files define many such sequences. For a description of the + * common file format for Compose files, see the Compose(5) man page. + * + * A successfuly-composed sequence has two results: a keysym and a UTF-8 + * string. At least one of the two is defined for each sequence. If only + * a keysym is given, the keysym's string representation is used for the + * result string (using xkb_keysym_to_utf8()). + * + * This library provides low-level support for Compose file parsing and + * processing. Higher-level APIs (such as libX11's `Xutf8LookupString`(3)) + * may be built upon it, or it can be used directly. + * + * @endparblock + */ + +/** + * @page compose-conflicting Conflicting Sequences + * @parblock + * + * To avoid ambiguity, a sequence is not allowed to be a prefix of another. + * In such a case, the conflict is resolved thus: + * + * 1. A longer sequence overrides a shorter one. + * 2. An equal sequence overrides an existing one. + * 3. A shorter sequence does not override a longer one. + * + * Sequences of length 1 are allowed. + * + * @endparblock + */ + +/** + * @page compose-cancellation Cancellation Behavior + * @parblock + * + * What should happen when a sequence is cancelled? For example, consider + * there are only the above sequences, and the input keysyms are + * `<dead_acute> <b>`. There are a few approaches: + * + * 1. Swallow the cancelling keysym; that is, no keysym is produced. + * This is the approach taken by libX11. + * 2. Let the cancelling keysym through; that is, `<b>` is produced. + * 3. Replay the entire sequence; that is, `<dead_acute> <b>` is produced. + * This is the approach taken by Microsoft Windows (approximately; + * instead of `<dead_acute>`, the underlying key is used. This is + * difficult to simulate with XKB keymaps). + * + * You can program whichever approach best fits users' expectations. + * + * @endparblock + */ + +/** + * @struct xkb_compose_table + * Opaque Compose table object. + * + * The compose table holds the definitions of the Compose sequences, as + * gathered from Compose files. It is immutable. + */ +struct xkb_compose_table; + +/** + * @struct xkb_compose_state + * Opaque Compose state object. + * + * The compose state maintains state for compose sequence matching, such + * as which possible sequences are being matched, and the position within + * these sequences. It acts as a simple state machine wherein keysyms are + * the input, and composed keysyms and strings are the output. + * + * The compose state is usually associated with a keyboard device. + */ +struct xkb_compose_state; + +/** Flags affecting Compose file compilation. */ +enum xkb_compose_compile_flags { + /** Do not apply any flags. */ + XKB_COMPOSE_COMPILE_NO_FLAGS = 0 +}; + +/** The recognized Compose file formats. */ +enum xkb_compose_format { + /** The classic libX11 Compose text format, described in Compose(5). */ + XKB_COMPOSE_FORMAT_TEXT_V1 = 1 +}; + +/** + * @page compose-locale Compose Locale + * @parblock + * + * Compose files are locale dependent: + * - Compose files are written for a locale, and the locale is used when + * searching for the appropriate file to use. + * - Compose files may reference the locale internally, with directives + * such as \%L. + * + * As such, functions like xkb_compose_table_new_from_locale() require + * a `locale` parameter. This will usually be the current locale (see + * locale(7) for more details). You may also want to allow the user to + * explicitly configure it, so he can use the Compose file of a given + * locale, but not use that locale for other things. + * + * You may query the current locale as follows: + * @code + * const char *locale; + * locale = setlocale(LC_CTYPE, NULL); + * @endcode + * + * This will only give useful results if the program had previously set + * the current locale using setlocale(3), with `LC_CTYPE` or `LC_ALL` + * and a non-NULL argument. + * + * If you prefer not to use the locale system of the C runtime library, + * you may nevertheless obtain the user's locale directly using + * environment variables, as described in locale(7). For example, + * @code + * const char *locale; + * locale = getenv("LC_ALL"); + * if (!locale || !*locale) + * locale = getenv("LC_CTYPE"); + * if (!locale || !*locale) + * locale = getenv("LANG"); + * if (!locale || !*locale) + * locale = "C"; + * @endcode + * + * Note that some locales supported by the C standard library may not + * have a Compose file assigned. + * + * @endparblock + */ + +/** + * Create a compose table for a given locale. + * + * The locale is used for searching the file-system for an appropriate + * Compose file. The search order is described in Compose(5). It is + * affected by the following environment variables: + * + * 1. `XCOMPOSEFILE` - see Compose(5). + * 2. `HOME` - see Compose(5). + * 3. `XLOCALEDIR` - if set, used as the base directory for the system's + * X locale files, e.g. `/usr/share/X11/locale`, instead of the + * preconfigured directory. + * + * @param context + * The library context in which to create the compose table. + * @param locale + * The current locale. See @ref compose-locale.\n + * + * The value is copied, so it is safe to pass the result of getenv(3) + * (or similar) without fear of it being invalidated by a subsequent + * setenv(3) (or similar). + * @param flags + * Optional flags for the compose table, or 0. + * + * @returns A compose table for the given locale, or NULL if the + * compilation failed or a Compose file was not found. + * + * @memberof xkb_compose_table + */ +struct xkb_compose_table * +xkb_compose_table_new_from_locale(struct xkb_context *context, + const char *locale, + enum xkb_compose_compile_flags flags); + +/** + * Create a new compose table from a Compose file. + * + * @param context + * The library context in which to create the compose table. + * @param file + * The Compose file to compile. + * @param locale + * The current locale. See @ref compose-locale. + * @param format + * The text format of the Compose file to compile. + * @param flags + * Optional flags for the compose table, or 0. + * + * @returns A compose table compiled from the given file, or NULL if + * the compilation failed. + * + * @memberof xkb_compose_table + */ +struct xkb_compose_table * +xkb_compose_table_new_from_file(struct xkb_context *context, + FILE *file, + const char *locale, + enum xkb_compose_format format, + enum xkb_compose_compile_flags flags); + +/** + * Create a new compose table from a memory buffer. + * + * This is just like xkb_compose_table_new_from_file(), but instead of + * a file, gets the table as one enormous string. + * + * @see xkb_compose_table_new_from_file() + * @memberof xkb_compose_table + */ +struct xkb_compose_table * +xkb_compose_table_new_from_buffer(struct xkb_context *context, + const char *buffer, size_t length, + const char *locale, + enum xkb_compose_format format, + enum xkb_compose_compile_flags flags); + +/** + * Take a new reference on a compose table. + * + * @returns The passed in object. + * + * @memberof xkb_compose_table + */ +struct xkb_compose_table * +xkb_compose_table_ref(struct xkb_compose_table *table); + +/** + * Release a reference on a compose table, and possibly free it. + * + * @param table The object. If it is NULL, this function does nothing. + * + * @memberof xkb_compose_table + */ +void +xkb_compose_table_unref(struct xkb_compose_table *table); + +/** Flags for compose state creation. */ +enum xkb_compose_state_flags { + /** Do not apply any flags. */ + XKB_COMPOSE_STATE_NO_FLAGS = 0 +}; + +/** + * Create a new compose state object. + * + * @param table + * The compose table the state will use. + * @param flags + * Optional flags for the compose state, or 0. + * + * @returns A new compose state, or NULL on failure. + * + * @memberof xkb_compose_state + */ +struct xkb_compose_state * +xkb_compose_state_new(struct xkb_compose_table *table, + enum xkb_compose_state_flags flags); + +/** + * Take a new reference on a compose state object. + * + * @returns The passed in object. + * + * @memberof xkb_compose_state + */ +struct xkb_compose_state * +xkb_compose_state_ref(struct xkb_compose_state *state); + +/** + * Release a reference on a compose state object, and possibly free it. + * + * @param state The object. If NULL, do nothing. + * + * @memberof xkb_compose_state + */ +void +xkb_compose_state_unref(struct xkb_compose_state *state); + +/** + * Get the compose table which a compose state object is using. + * + * @returns The compose table which was passed to xkb_compose_state_new() + * when creating this state object. + * + * This function does not take a new reference on the compose table; you + * must explicitly reference it yourself if you plan to use it beyond the + * lifetime of the state. + * + * @memberof xkb_compose_state + */ +struct xkb_compose_table * +xkb_compose_state_get_compose_table(struct xkb_compose_state *state); + +/** Status of the Compose sequence state machine. */ +enum xkb_compose_status { + /** The initial state; no sequence has started yet. */ + XKB_COMPOSE_NOTHING, + /** In the middle of a sequence. */ + XKB_COMPOSE_COMPOSING, + /** A complete sequence has been matched. */ + XKB_COMPOSE_COMPOSED, + /** The last sequence was cancelled due to an unmatched keysym. */ + XKB_COMPOSE_CANCELLED +}; + +/** The effect of a keysym fed to xkb_compose_state_feed(). */ +enum xkb_compose_feed_result { + /** The keysym had no effect - it did not affect the status. */ + XKB_COMPOSE_FEED_IGNORED, + /** The keysym started, advanced or cancelled a sequence. */ + XKB_COMPOSE_FEED_ACCEPTED +}; + +/** + * Feed one keysym to the Compose sequence state machine. + * + * This function can advance into a compose sequence, cancel a sequence, + * start a new sequence, or do nothing in particular. The resulting + * status may be observed with xkb_compose_state_get_status(). + * + * Some keysyms, such as keysyms for modifier keys, are ignored - they + * have no effect on the status or otherwise. + * + * The following is a description of the possible status transitions, in + * the format CURRENT STATUS => NEXT STATUS, given a non-ignored input + * keysym `keysym`: + * + @verbatim + NOTHING or CANCELLED or COMPOSED => + NOTHING if keysym does not start a sequence. + COMPOSING if keysym starts a sequence. + COMPOSED if keysym starts and terminates a single-keysym sequence. + + COMPOSING => + COMPOSING if keysym advances any of the currently possible + sequences but does not terminate any of them. + COMPOSED if keysym terminates one of the currently possible + sequences. + CANCELLED if keysym does not advance any of the currently + possible sequences. + @endverbatim + * + * The current Compose formats do not support multiple-keysyms. + * Therefore, if you are using a function such as xkb_state_key_get_syms() + * and it returns more than one keysym, consider feeding XKB_KEY_NoSymbol + * instead. + * + * @param state + * The compose state object. + * @param keysym + * A keysym, usually obtained after a key-press event, with a + * function such as xkb_state_key_get_one_sym(). + * + * @returns Whether the keysym was ignored. This is useful, for example, + * if you want to keep a record of the sequence matched thus far. + * + * @memberof xkb_compose_state + */ +enum xkb_compose_feed_result +xkb_compose_state_feed(struct xkb_compose_state *state, + xkb_keysym_t keysym); + +/** + * Reset the Compose sequence state machine. + * + * The status is set to XKB_COMPOSE_NOTHING, and the current sequence + * is discarded. + * + * @memberof xkb_compose_state + */ +void +xkb_compose_state_reset(struct xkb_compose_state *state); + +/** + * Get the current status of the compose state machine. + * + * @see xkb_compose_status + * @memberof xkb_compose_state + **/ +enum xkb_compose_status +xkb_compose_state_get_status(struct xkb_compose_state *state); + +/** + * Get the result Unicode/UTF-8 string for a composed sequence. + * + * See @ref compose-overview for more details. This function is only + * useful when the status is XKB_COMPOSE_COMPOSED. + * + * @param[in] state + * The compose state. + * @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 the sequence is not complete, or does not have a viable result + * string, returns 0, and sets `buffer` to the empty string (if possible). + * @returns + * You may check if truncation has occurred by comparing the return value + * with the size of `buffer`, similarly to the `snprintf`(3) function. + * You may safely pass NULL and 0 to `buffer` and `size` to find the + * required size (without the NUL-byte). + * + * @memberof xkb_compose_state + **/ +int +xkb_compose_state_get_utf8(struct xkb_compose_state *state, + char *buffer, size_t size); + +/** + * Get the result keysym for a composed sequence. + * + * See @ref compose-overview for more details. This function is only + * useful when the status is XKB_COMPOSE_COMPOSED. + * + * @returns The result keysym. If the sequence is not complete, or does + * not specify a result keysym, returns XKB_KEY_NoSymbol. + * + * @memberof xkb_compose_state + **/ +xkb_keysym_t +xkb_compose_state_get_one_sym(struct xkb_compose_state *state); + +/** @} */ + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _XKBCOMMON_COMPOSE_H */ diff --git a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-keysyms.h b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-keysyms.h index 69c582e45f..bd172a6efc 100644 --- a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-keysyms.h +++ b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-keysyms.h @@ -1,7 +1,7 @@ #ifndef _XKBCOMMON_KEYSYMS_H #define _XKBCOMMON_KEYSYMS_H -/* This file is autogenerated from Makefile.am; please do not commit directly. */ +/* This file is autogenerated; please do not commit directly. */ #define XKB_KEY_NoSymbol 0x000000 /* Special KeySym */ @@ -2451,29 +2451,6 @@ SOFTWARE. * * The XFree86 keysym range is 0x10080001 - 0x1008FFFF. * - * When adding new entries, the xc/lib/XKeysymDB file should also be - * updated to make the new entries visible to Xlib. - */ - -/* - * ModeLock - * - * This one is old, and not really used any more since XKB offers this - * functionality. - */ - -#define XKB_KEY_XF86ModeLock 0x1008FF01 /* Mode Switch Lock */ - -/* - * Note, 0x1008FF07 - 0x1008FF0F are free and should be used for misc new - * keysyms that don't fit into any of the groups below. - * - * 0x1008FF64, 0x1008FF6F, 0x1008FF71, 0x1008FF83 are no longer used, - * and should be used first for new keysyms. - * - * Check in keysymdef.h for generic symbols before adding new XFree86-specific - * symbols here. - * * X.Org will not be adding to the XF86 set of keysyms, though they have * been adopted and are considered a "standard" part of X keysym definitions. * XFree86 never properly commented these keysyms, so we have done our @@ -2484,6 +2461,14 @@ SOFTWARE. * these archives, these are from memory and usage. */ +/* + * ModeLock + * + * This one is old, and not really used any more since XKB offers this + * functionality. + */ + +#define XKB_KEY_XF86ModeLock 0x1008FF01 /* Mode Switch Lock */ /* Backlight controls. */ #define XKB_KEY_XF86MonBrightnessUp 0x1008FF02 /* Monitor/panel brightness */ @@ -2660,6 +2645,13 @@ SOFTWARE. #define XKB_KEY_XF86AudioMicMute 0x1008FFB2 /* Mute the Mic from the system */ +#define XKB_KEY_XF86Keyboard 0x1008FFB3 /* User defined keyboard related action */ + +#define XKB_KEY_XF86WWAN 0x1008FFB4 /* Toggle WWAN (LTE, UMTS, etc.) radio */ +#define XKB_KEY_XF86RFKill 0x1008FFB5 /* Toggle radios on/off */ + +#define XKB_KEY_XF86AudioPreset 0x1008FFB6 /* Select equalizer preset, e.g. theatre-mode */ + /* Keys for special action keys (hot keys) */ /* Virtual terminals on some operating systems */ #define XKB_KEY_XF86Switch_VT_1 0x1008FE01 diff --git a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h index d9e2a4f11a..cf244d2559 100644 --- a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h +++ b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h @@ -39,11 +39,76 @@ extern "C" { /** * @defgroup x11 X11 support * Additional X11 support for xkbcommon. + * @since 0.4.0 * * @{ */ /** + * @page x11-overview Overview + * @parblock + * + * The xkbcommon-x11 module provides a means for creating an xkb_keymap + * corresponding to the currently active keymap on the X server. To do + * so, it queries the XKB X11 extension using the xcb-xkb library. It + * can be used as a replacement for Xlib's keyboard handling. + * + * Following is an example workflow using xkbcommon-x11. A complete + * example may be found in the test/interactive-x11.c file in the + * xkbcommon source repository. On startup: + * + * 1. Connect to the X server using xcb_connect(). + * 2. Setup the XKB X11 extension. You can do this either by using the + * xcb_xkb_use_extension() request directly, or by using the + * xkb_x11_setup_xkb_extension() helper function. + * + * The XKB extension supports using separate keymaps and states for + * different keyboard devices. The devices are identified by an integer + * device ID and are managed by another X11 extension, XInput. The + * original X11 protocol only had one keyboard device, called the "core + * keyboard", which is still supported as a "virtual device". + * + * 3. We will use the core keyboard as an example. To get its device ID, + * use either the xcb_xkb_get_device_info() request directly, or the + * xkb_x11_get_core_keyboard_device_id() helper function. + * 4. Create an initial xkb_keymap for this device, using the + * xkb_x11_keymap_new_from_device() function. + * 5. Create an initial xkb_state for this device, using the + * xkb_x11_state_new_from_device() function. + * + * @note At this point, you may consider setting various XKB controls and + * XKB per-client flags. For example, enabling detectable autorepeat: \n + * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Detectable_Autorepeat + * + * Next, you need to react to state changes (e.g. a modifier was pressed, + * the layout was changed) and to keymap changes (e.g. a tool like xkbcomp, + * setxkbmap or xmodmap was used): + * + * 6. Select to listen to at least the following XKB events: + * NewKeyboardNotify, MapNotify, StateNotify; using the + * xcb_xkb_select_events_aux() request. + * 7. When NewKeyboardNotify or MapNotify are received, recreate the + * xkb_keymap and xkb_state as described above. + * 8. When StateNotify is received, update the xkb_state accordingly + * using the xkb_state_update_mask() function. + * + * @note It is also possible to use the KeyPress/KeyRelease @p state + * field to find the effective modifier and layout state, instead of + * using XkbStateNotify: \n + * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Computing_A_State_Field_from_an_XKB_State + * \n However, XkbStateNotify is more accurate. + * + * @note There is no need to call xkb_state_update_key(); the state is + * already synchronized. + * + * Finally, when a key event is received, you can use ordinary xkbcommon + * functions, like xkb_state_key_get_one_sym() and xkb_state_key_get_utf8(), + * as you normally would. + * + * @endparblock + */ + +/** * The minimal compatible major version of the XKB X11 extension which * this library can use. */ @@ -75,14 +140,18 @@ enum xkb_x11_setup_xkb_extension_flags { * * @param connection * An XCB connection to the X server. - * @param major_xkb_version, minor_xkb_version + * @param major_xkb_version + * See @p minor_xkb_version. + * @param minor_xkb_version * The XKB extension version to request. To operate correctly, you * must have (major_xkb_version, minor_xkb_version) >= * (XKB_X11_MIN_MAJOR_XKB_VERSION, XKB_X11_MIN_MINOR_XKB_VERSION), * though this is not enforced. * @param flags * Optional flags, or 0. - * @param[out] major_xkb_version_out, minor_xkb_version_out + * @param[out] major_xkb_version_out + * See @p minor_xkb_version_out. + * @param[out] minor_xkb_version_out * Backfilled with the compatible XKB extension version numbers picked * by the server. Can be NULL. * @param[out] base_event_out @@ -127,8 +196,9 @@ xkb_x11_get_core_keyboard_device_id(xcb_connection_t *connection); * @param connection * An XCB connection to the X server. * @param device_id - * An XInput 1 device ID (in the range 0-255) with input class KEY. - * Passing values outside of this range is an error. + * An XInput device ID (in the range 0-127) with input class KEY. + * Passing values outside of this range is an error (the XKB protocol + * predates the XInput2 protocol, which first allowed IDs > 127). * @param flags * Optional flags for the keymap, or 0. * 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 |