summaryrefslogtreecommitdiffstats
path: root/src/3rdparty/xkbcommon/xkbcommon
diff options
context:
space:
mode:
authorGatis Paeglis <gatis.paeglis@qt.io>2018-10-16 12:09:10 +0200
committerGatis Paeglis <gatis.paeglis@qt.io>2018-10-17 08:49:53 +0000
commit76c762558a4f31d030cf55dacf0e1913db5c6d60 (patch)
treeb97b13a026bd798706a820d5fa4d90ee5408cc79 /src/3rdparty/xkbcommon/xkbcommon
parentaa633ff276e593af227d7c4a84db230382185490 (diff)
3rdparty/xkbcommon: update bundled version 0.4.1 -> 0.8.2
0.8.2 + subsequent commits up to 31f1f355700870c6615399fbfa7934934b3a9a57. There were couple commits after 0.8.2. Mostly minor stuff, with 2 exceptions: fix off-by-one error in xkb_file_type_to_string() and undefined behavior in src/x11/keymap.c We currently don't use any of the features added in later releases of libxkbcommon, therefore the minimal required version in src/gui/configure.json remains the same. [ChangeLog][Third-Party Code] updated bundled libxkbcommon 0.4.1 -> 0.8.2 (up to 31f1f355700870c6615399fbfa7934934b3a9a57) Task-number: QTBUG-71109 Change-Id: Ia03c3dc31c5f39e78dcb5915a45e82797b065ccb Reviewed-by: Lars Knoll <lars.knoll@qt.io>
Diffstat (limited to 'src/3rdparty/xkbcommon/xkbcommon')
-rw-r--r--src/3rdparty/xkbcommon/xkbcommon/xkbcommon-compose.h493
-rw-r--r--src/3rdparty/xkbcommon/xkbcommon/xkbcommon-keysyms.h40
-rw-r--r--src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h78
-rw-r--r--src/3rdparty/xkbcommon/xkbcommon/xkbcommon.h386
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