2 * Copyright 1985, 1987, 1990, 1998 The Open Group
3 * Copyright 2008 Dan Nicholson
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the "Software"),
7 * to deal in the Software without restriction, including without limitation
8 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 * and/or sell copies of the Software, and to permit persons to whom the
10 * Software is furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
19 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 * Except as contained in this notice, the names of the authors or their
23 * institutions shall not be used in advertising or otherwise to promote the
24 * sale, use or other dealings in this Software without prior written
25 * authorization from the authors.
28 /************************************************************
29 * Copyright (c) 1993 by Silicon Graphics Computer Systems, Inc.
31 * Permission to use, copy, modify, and distribute this
32 * software and its documentation for any purpose and without
33 * fee is hereby granted, provided that the above copyright
34 * notice appear in all copies and that both that copyright
35 * notice and this permission notice appear in supporting
36 * documentation, and that the name of Silicon Graphics not be
37 * used in advertising or publicity pertaining to distribution
38 * of the software without specific prior written permission.
39 * Silicon Graphics makes no representation about the suitability
40 * of this software for any purpose. It is provided "as is"
41 * without any express or implied warranty.
43 * SILICON GRAPHICS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
44 * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
45 * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SILICON
46 * GRAPHICS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
47 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
48 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
49 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH
50 * THE USE OR PERFORMANCE OF THIS SOFTWARE.
52 ********************************************************/
55 * Copyright © 2009-2012 Daniel Stone
56 * Copyright © 2012 Intel Corporation
57 * Copyright © 2012 Ran Benita
59 * Permission is hereby granted, free of charge, to any person obtaining a
60 * copy of this software and associated documentation files (the "Software"),
61 * to deal in the Software without restriction, including without limitation
62 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
63 * and/or sell copies of the Software, and to permit persons to whom the
64 * Software is furnished to do so, subject to the following conditions:
66 * The above copyright notice and this permission notice (including the next
67 * paragraph) shall be included in all copies or substantial portions of the
70 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
71 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
72 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
73 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
74 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
75 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
76 * DEALINGS IN THE SOFTWARE.
78 * Author: Daniel Stone <daniel@fooishbar.org>
88 #include <xkbcommon/xkbcommon-names.h>
89 #include <xkbcommon/xkbcommon-keysyms.h>
97 * Main libxkbcommon API.
101 * @struct xkb_context
102 * Opaque top level library context object.
104 * The context contains various general library data and state, like
105 * logging level and include paths.
107 * Objects are created in a specific context, and multiple contexts may
108 * coexist simultaneously. Objects from different contexts are completely
109 * separated and do not share any memory or state.
115 * Opaque compiled keymap object.
117 * The keymap object holds all of the static keyboard information obtained
118 * from compiling XKB files.
120 * A keymap is immutable after it is created (besides reference counts, etc.);
121 * if you need to change it, you must create a new one.
127 * Opaque keyboard state object.
129 * State objects contain the active state of a keyboard (or keyboards), such
130 * as the currently effective layout and the active modifiers. It acts as a
131 * simple state machine, wherein key presses and releases are the input, and
132 * key symbols (keysyms) are the output.
137 * A number used to represent a physical key on a keyboard.
139 * A standard PC-compatible keyboard might have 102 keys. An appropriate
140 * keymap would assign each of them a keycode, by which the user should
141 * refer to the key throughout the library.
143 * Historically, the X11 protocol, and consequentially the XKB protocol,
144 * assign only 8 bits for keycodes. This limits the number of different
145 * keys that can be used simultaneously in a single keymap to 256
146 * (disregarding other limitations). This library does not share this limit;
147 * keycodes beyond 255 ('extended keycodes') are not treated specially.
148 * Keymaps and applications which are compatible with X11 should not use
151 * The values of specific keycodes are determined by the keymap and the
152 * underlying input system. For example, with an X11-compatible keymap
153 * and Linux evdev scan codes (see linux/input.h), a fixed offset is used:
155 * The keymap defines a canonical name for each key, plus possible aliases.
156 * Historically, the XKB protocol restricts these names to at most 4 (ASCII)
157 * characters, but this library does not share this limit.
160 * xkb_keycode_t keycode_A = KEY_A + 8;
163 * @sa xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11()
165 typedef uint32_t xkb_keycode_t;
168 * A number used to represent the symbols generated from a key on a keyboard.
170 * A key, represented by a keycode, may generate different symbols according
171 * to keyboard state. For example, on a QWERTY keyboard, pressing the key
172 * labled \<A\> generates the symbol ‘a’. If the Shift key is held, it
173 * generates the symbol ‘A’. If a different layout is used, say Greek,
174 * it generates the symbol ‘α’. And so on.
176 * Each such symbol is represented by a *keysym* (short for “key symbol”).
177 * Note that keysyms are somewhat more general, in that they can also represent
178 * some “function”, such as “Left” or “Right” for the arrow keys. For more
179 * information, see: Appendix A [“KEYSYM Encoding”][encoding] of the X Window
182 * Specifically named keysyms can be found in the
183 * xkbcommon/xkbcommon-keysyms.h header file. Their name does not include
184 * the `XKB_KEY_` prefix.
186 * Besides those, any Unicode/ISO 10646 character in the range U+0100 to
187 * U+10FFFF can be represented by a keysym value in the range 0x01000100 to
188 * 0x0110FFFF. The name of Unicode keysyms is `U<codepoint>`, e.g. `UA1B2`.
190 * The name of other unnamed keysyms is the hexadecimal representation of
191 * their value, e.g. `0xabcd1234`.
193 * Keysym names are case-sensitive.
195 * @note **Encoding:** Keysyms are 32-bit integers with the 3 most significant
196 * bits always set to zero. See: Appendix A [“KEYSYM Encoding”][encoding] of
197 * the X Window System Protocol.
199 * [encoding]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#keysym_encoding
204 typedef uint32_t xkb_keysym_t;
207 * Index of a keyboard layout.
209 * The layout index is a state component which detemines which <em>keyboard
210 * layout</em> is active. These may be different alphabets, different key
213 * Layout indices are consecutive. The first layout has index 0.
215 * Each layout is not required to have a name, and the names are not
216 * guaranteed to be unique (though they are usually provided and unique).
217 * Therefore, it is not safe to use the name as a unique identifier for a
218 * layout. Layout names are case-sensitive.
220 * Layout names are specified in the layout's definition, for example
221 * "English (US)". These are different from the (conventionally) short names
222 * which are used to locate the layout, for example "us" or "us(intl)". These
223 * names are not present in a compiled keymap.
225 * If the user selects layouts from a list generated from the XKB registry
226 * (using libxkbregistry or directly), and this metadata is needed later on, it
227 * is recommended to store it along with the keymap.
229 * Layouts are also called "groups" by XKB.
231 * @sa xkb_keymap_num_layouts() xkb_keymap_num_layouts_for_key()
233 typedef uint32_t xkb_layout_index_t;
234 /** A mask of layout indices. */
235 typedef uint32_t xkb_layout_mask_t;
238 * Index of a shift level.
240 * Any key, in any layout, can have several <em>shift levels</em>. Each
241 * shift level can assign different keysyms to the key. The shift level
242 * to use is chosen according to the current keyboard state; for example,
243 * if no keys are pressed, the first level may be used; if the Left Shift
244 * key is pressed, the second; if Num Lock is pressed, the third; and
245 * many such combinations are possible (see xkb_mod_index_t).
247 * Level indices are consecutive. The first level has index 0.
249 typedef uint32_t xkb_level_index_t;
252 * Index of a modifier.
254 * A @e modifier is a state component which changes the way keys are
255 * interpreted. A keymap defines a set of modifiers, such as Alt, Shift,
256 * Num Lock or Meta, and specifies which keys may @e activate which
257 * modifiers (in a many-to-many relationship, i.e. a key can activate
258 * several modifiers, and a modifier may be activated by several keys.
259 * Different keymaps do this differently).
261 * When retrieving the keysyms for a key, the active modifier set is
262 * consulted; this detemines the correct shift level to use within the
263 * currently active layout (see xkb_level_index_t).
265 * Modifier indices are consecutive. The first modifier has index 0.
267 * Each modifier must have a name, and the names are unique. Therefore, it
268 * is safe to use the name as a unique identifier for a modifier. The names
269 * of some common modifiers are provided in the xkbcommon/xkbcommon-names.h
270 * header file. Modifier names are case-sensitive.
272 * @sa xkb_keymap_num_mods()
274 typedef uint32_t xkb_mod_index_t;
275 /** A mask of modifier indices. */
276 typedef uint32_t xkb_mod_mask_t;
279 * Index of a keyboard LED.
281 * LEDs are logical objects which may be @e active or @e inactive. They
282 * typically correspond to the lights on the keyboard. Their state is
283 * determined by the current keyboard state.
285 * LED indices are non-consecutive. The first LED has index 0.
287 * Each LED must have a name, and the names are unique. Therefore,
288 * it is safe to use the name as a unique identifier for a LED. The names
289 * of some common LEDs are provided in the xkbcommon/xkbcommon-names.h
290 * header file. LED names are case-sensitive.
292 * @warning A given keymap may specify an exact index for a given LED.
293 * Therefore, LED indexing is not necessarily sequential, as opposed to
294 * modifiers and layouts. This means that when iterating over the LEDs
295 * in a keymap using e.g. xkb_keymap_num_leds(), some indices might be
296 * invalid. Given such an index, functions like xkb_keymap_led_get_name()
297 * will return NULL, and xkb_state_led_index_is_active() will return -1.
299 * LEDs are also called "indicators" by XKB.
301 * @sa xkb_keymap_num_leds()
303 typedef uint32_t xkb_led_index_t;
304 /** A mask of LED indices. */
305 typedef uint32_t xkb_led_mask_t;
307 #define XKB_KEYCODE_INVALID (0xffffffff)
308 #define XKB_LAYOUT_INVALID (0xffffffff)
309 #define XKB_LEVEL_INVALID (0xffffffff)
310 #define XKB_MOD_INVALID (0xffffffff)
311 #define XKB_LED_INVALID (0xffffffff)
313 #define XKB_KEYCODE_MAX (0xffffffff - 1)
316 * Maximum keysym value
322 #define XKB_KEYSYM_MAX 0x1fffffff
325 * Test whether a value is a valid extended keycode.
328 #define xkb_keycode_is_legal_ext(key) (key <= XKB_KEYCODE_MAX)
331 * Test whether a value is a valid X11 keycode.
334 #define xkb_keycode_is_legal_x11(key) (key >= 8 && key <= 255)
337 * Names to compile a keymap with, also known as RMLVO.
339 * The names are the common configuration values by which a user picks
342 * If the entire struct is NULL, then each field is taken to be NULL.
343 * You should prefer passing NULL instead of choosing your own defaults.
345 struct xkb_rule_names {
347 * The rules file to use. The rules file describes how to interpret
348 * the values of the model, layout, variant and options fields.
350 * If NULL or the empty string "", a default value is used.
351 * If the XKB_DEFAULT_RULES environment variable is set, it is used
352 * as the default. Otherwise the system default is used.
356 * The keyboard model by which to interpret keycodes and LEDs.
358 * If NULL or the empty string "", a default value is used.
359 * If the XKB_DEFAULT_MODEL environment variable is set, it is used
360 * as the default. Otherwise the system default is used.
364 * A comma separated list of layouts (languages) to include in the
367 * If NULL or the empty string "", a default value is used.
368 * If the XKB_DEFAULT_LAYOUT environment variable is set, it is used
369 * as the default. Otherwise the system default is used.
373 * A comma separated list of variants, one per layout, which may
374 * modify or augment the respective layout in various ways.
376 * Generally, should either be empty or have the same number of values
377 * as the number of layouts. You may use empty values as in "intl,,neo".
379 * If NULL or the empty string "", and a default value is also used
380 * for the layout, a default value is used. Otherwise no variant is
382 * If the XKB_DEFAULT_VARIANT environment variable is set, it is used
383 * as the default. Otherwise the system default is used.
387 * A comma separated list of options, through which the user specifies
388 * non-layout related preferences, like which key combinations are used
389 * for switching layouts, or which key is the Compose key.
391 * If NULL, a default value is used. If the empty string "", no
393 * If the XKB_DEFAULT_OPTIONS environment variable is set, it is used
394 * as the default. Otherwise the system default is used.
400 * @defgroup keysyms Keysyms
401 * Utility functions related to *keysyms* (short for “key symbols”).
407 * @page keysym-transformations Keysym Transformations
409 * Keysym translation is subject to several "keysym transformations",
410 * as described in the XKB specification. These are:
412 * - Capitalization transformation. If the Caps Lock modifier is
413 * active and was not consumed by the translation process, a single
414 * keysym is transformed to its upper-case form (if applicable).
415 * Similarly, the UTF-8/UTF-32 string produced is capitalized.
417 * This is described in:
418 * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Lock_Modifier
420 * - Control transformation. If the Control modifier is active and
421 * was not consumed by the translation process, the string produced
422 * is transformed to its matching ASCII control character (if
423 * applicable). Keysyms are not affected.
425 * This is described in:
426 * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier
428 * Each relevant function discusses which transformations it performs.
430 * These transformations are not applicable when a key produces multiple
436 * Get the name of a keysym.
438 * For a description of how keysyms are named, see @ref xkb_keysym_t.
440 * @param[in] keysym The keysym.
441 * @param[out] buffer A string buffer to write the name into.
442 * @param[in] size Size of the buffer.
444 * @warning If the buffer passed is too small, the string is truncated
445 * (though still NUL-terminated); a size of at least 64 bytes is recommended.
447 * @returns The number of bytes in the name, excluding the NUL byte. If
448 * the keysym is invalid, returns -1.
450 * You may check if truncation has occurred by comparing the return value
451 * with the length of buffer, similarly to the snprintf(3) function.
456 xkb_keysym_get_name(xkb_keysym_t keysym, char *buffer, size_t size);
458 /** Flags for xkb_keysym_from_name(). */
459 enum xkb_keysym_flags {
460 /** Do not apply any flags. */
461 XKB_KEYSYM_NO_FLAGS = 0,
462 /** Find keysym by case-insensitive search. */
463 XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0)
467 * Get a keysym from its name.
469 * @param name The name of a keysym. See remarks in xkb_keysym_get_name();
470 * this function will accept any name returned by that function.
471 * @param flags A set of flags controlling how the search is done. If
472 * invalid flags are passed, this will fail with XKB_KEY_NoSymbol.
474 * If you use the XKB_KEYSYM_CASE_INSENSITIVE flag and two keysym names
475 * differ only by case, then the lower-case keysym is returned. For
476 * instance, for KEY_a and KEY_A, this function would return KEY_a for the
477 * case-insensitive search. If this functionality is needed, it is
478 * recommended to first call this function without this flag; and if that
479 * fails, only then to try with this flag, while possibly warning the user
480 * he had misspelled the name, and might get wrong results.
482 * Case folding is done according to the C locale; the current locale is not
485 * @returns The keysym. If the name is invalid, returns XKB_KEY_NoSymbol.
490 xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags);
493 * Get the Unicode/UTF-8 representation of a keysym.
495 * @param[in] keysym The keysym.
496 * @param[out] buffer A buffer to write the UTF-8 string into.
497 * @param[in] size The size of buffer. Must be at least 7.
499 * @returns The number of bytes written to the buffer (including the
500 * terminating byte). If the keysym does not have a Unicode
501 * representation, returns 0. If the buffer is too small, returns -1.
503 * This function does not perform any @ref keysym-transformations.
504 * Therefore, prefer to use xkb_state_key_get_utf8() if possible.
506 * @sa xkb_state_key_get_utf8()
509 xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size);
512 * Get the Unicode/UTF-32 representation of a keysym.
514 * @returns The Unicode/UTF-32 representation of keysym, which is also
515 * compatible with UCS-4. If the keysym does not have a Unicode
516 * representation, returns 0.
518 * This function does not perform any @ref keysym-transformations.
519 * Therefore, prefer to use xkb_state_key_get_utf32() if possible.
521 * @sa xkb_state_key_get_utf32()
524 xkb_keysym_to_utf32(xkb_keysym_t keysym);
527 * Get the keysym corresponding to a Unicode/UTF-32 codepoint.
529 * @returns The keysym corresponding to the specified Unicode
530 * codepoint, or XKB_KEY_NoSymbol if there is none.
532 * This function is the inverse of @ref xkb_keysym_to_utf32. In cases
533 * where a single codepoint corresponds to multiple keysyms, returns
534 * the keysym with the lowest value.
536 * Unicode codepoints which do not have a special (legacy) keysym
537 * encoding use a direct encoding scheme. These keysyms don't usually
538 * have an associated keysym constant (XKB_KEY_*).
540 * For noncharacter Unicode codepoints and codepoints outside of the
541 * defined Unicode planes this function returns XKB_KEY_NoSymbol.
543 * @sa xkb_keysym_to_utf32()
547 xkb_utf32_to_keysym(uint32_t ucs);
550 * Convert a keysym to its uppercase form.
552 * If there is no such form, the keysym is returned unchanged.
554 * The conversion rules may be incomplete; prefer to work with the Unicode
555 * representation instead, when possible.
558 xkb_keysym_to_upper(xkb_keysym_t ks);
561 * Convert a keysym to its lowercase form.
563 * The conversion rules may be incomplete; prefer to work with the Unicode
564 * representation instead, when possible.
567 xkb_keysym_to_lower(xkb_keysym_t ks);
572 * @defgroup context Library Context
573 * Creating, destroying and using library contexts.
575 * Every keymap compilation request must have a context associated with
576 * it. The context keeps around state such as the include path.
582 * @page envvars Environment Variables
584 * The user may set some environment variables which affect the library:
586 * - `XKB_CONFIG_ROOT`, `XKB_CONFIG_EXTRA_PATH`, `XDG_CONFIG_DIR`, `HOME` - see @ref include-path.
587 * - `XKB_LOG_LEVEL` - see xkb_context_set_log_level().
588 * - `XKB_LOG_VERBOSITY` - see xkb_context_set_log_verbosity().
589 * - `XKB_DEFAULT_RULES`, `XKB_DEFAULT_MODEL`, `XKB_DEFAULT_LAYOUT`,
590 * `XKB_DEFAULT_VARIANT`, `XKB_DEFAULT_OPTIONS` - see xkb_rule_names.
593 /** Flags for context creation. */
594 enum xkb_context_flags {
595 /** Do not apply any context flags. */
596 XKB_CONTEXT_NO_FLAGS = 0,
597 /** Create this context with an empty include path. */
598 XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
600 * Don't take RMLVO names from the environment.
604 XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1),
606 * Disable the use of secure_getenv for this context, so that privileged
607 * processes can use environment variables. Client uses at their own risk.
611 XKB_CONTEXT_NO_SECURE_GETENV = (1 << 2)
615 * Create a new context.
617 * @param flags Optional flags for the context, or 0.
619 * @returns A new context, or NULL on failure.
621 * @memberof xkb_context
624 xkb_context_new(enum xkb_context_flags flags);
627 * Take a new reference on a context.
629 * @returns The passed in context.
631 * @memberof xkb_context
634 xkb_context_ref(struct xkb_context *context);
637 * Release a reference on a context, and possibly free it.
639 * @param context The context. If it is NULL, this function does nothing.
641 * @memberof xkb_context
644 xkb_context_unref(struct xkb_context *context);
647 * Store custom user data in the context.
649 * This may be useful in conjunction with xkb_context_set_log_fn() or other
652 * @memberof xkb_context
655 xkb_context_set_user_data(struct xkb_context *context, void *user_data);
658 * Retrieves stored user data from the context.
660 * @returns The stored user data. If the user data wasn't set, or the
661 * passed in context is NULL, returns NULL.
663 * This may be useful to access private user data from callbacks like a
664 * custom logging function.
666 * @memberof xkb_context
669 xkb_context_get_user_data(struct xkb_context *context);
674 * @defgroup include-path Include Paths
675 * Manipulating the include paths in a context.
677 * The include paths are the file-system paths that are searched when an
678 * include statement is encountered during keymap compilation.
680 * The default include paths are, in that lookup order:
681 * - The path `$XDG_CONFIG_HOME/xkb`, with the usual `XDG_CONFIG_HOME`
682 * fallback to `$HOME/.config/` if unset.
683 * - The path `$HOME/.xkb`, where $HOME is the value of the environment
685 * - The `XKB_CONFIG_EXTRA_PATH` environment variable, if defined, otherwise the
686 * system configuration directory, defined at library configuration time
687 * (usually `/etc/xkb`).
688 * - The `XKB_CONFIG_ROOT` environment variable, if defined, otherwise
689 * the system XKB root, defined at library configuration time.
695 * Append a new entry to the context's include path.
697 * @returns 1 on success, or 0 if the include path could not be added or is
700 * @memberof xkb_context
703 xkb_context_include_path_append(struct xkb_context *context, const char *path);
706 * Append the default include paths to the context's include path.
708 * @returns 1 on success, or 0 if the primary include path could not be added.
710 * @memberof xkb_context
713 xkb_context_include_path_append_default(struct xkb_context *context);
716 * Reset the context's include path to the default.
718 * Removes all entries from the context's include path, and inserts the
721 * @returns 1 on success, or 0 if the primary include path could not be added.
723 * @memberof xkb_context
726 xkb_context_include_path_reset_defaults(struct xkb_context *context);
729 * Remove all entries from the context's include path.
731 * @memberof xkb_context
734 xkb_context_include_path_clear(struct xkb_context *context);
737 * Get the number of paths in the context's include path.
739 * @memberof xkb_context
742 xkb_context_num_include_paths(struct xkb_context *context);
745 * Get a specific include path from the context's include path.
747 * @returns The include path at the specified index. If the index is
748 * invalid, returns NULL.
750 * @memberof xkb_context
753 xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
758 * @defgroup logging Logging Handling
759 * Manipulating how logging from this library is handled.
764 /** Specifies a logging level. */
766 XKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
767 XKB_LOG_LEVEL_ERROR = 20, /**< Log all errors. */
768 XKB_LOG_LEVEL_WARNING = 30, /**< Log warnings and errors. */
769 XKB_LOG_LEVEL_INFO = 40, /**< Log information, warnings, and errors. */
770 XKB_LOG_LEVEL_DEBUG = 50 /**< Log everything. */
774 * Set the current logging level.
776 * @param context The context in which to set the logging level.
777 * @param level The logging level to use. Only messages from this level
778 * and below will be logged.
780 * The default level is XKB_LOG_LEVEL_ERROR. The environment variable
781 * XKB_LOG_LEVEL, if set in the time the context was created, overrides the
782 * default value. It may be specified as a level number or name.
784 * @memberof xkb_context
787 xkb_context_set_log_level(struct xkb_context *context,
788 enum xkb_log_level level);
791 * Get the current logging level.
793 * @memberof xkb_context
796 xkb_context_get_log_level(struct xkb_context *context);
799 * Sets the current logging verbosity.
801 * The library can generate a number of warnings which are not helpful to
802 * ordinary users of the library. The verbosity may be increased if more
803 * information is desired (e.g. when developing a new keymap).
805 * The default verbosity is 0. The environment variable XKB_LOG_VERBOSITY,
806 * if set in the time the context was created, overrides the default value.
808 * @param context The context in which to use the set verbosity.
809 * @param verbosity The verbosity to use. Currently used values are
810 * 1 to 10, higher values being more verbose. 0 would result in no verbose
811 * messages being logged.
813 * Most verbose messages are of level XKB_LOG_LEVEL_WARNING or lower.
815 * @memberof xkb_context
818 xkb_context_set_log_verbosity(struct xkb_context *context, int verbosity);
821 * Get the current logging verbosity of the context.
823 * @memberof xkb_context
826 xkb_context_get_log_verbosity(struct xkb_context *context);
829 * Set a custom function to handle logging messages.
831 * @param context The context in which to use the set logging function.
832 * @param log_fn The function that will be called for logging messages.
833 * Passing NULL restores the default function, which logs to stderr.
835 * By default, log messages from this library are printed to stderr. This
836 * function allows you to replace the default behavior with a custom
837 * handler. The handler is only called with messages which match the
838 * current logging level and verbosity settings for the context.
839 * level is the logging level of the message. @a format and @a args are
840 * the same as in the vprintf(3) function.
842 * You may use xkb_context_set_user_data() on the context, and then call
843 * xkb_context_get_user_data() from within the logging function to provide
844 * it with additional private context.
846 * @memberof xkb_context
849 xkb_context_set_log_fn(struct xkb_context *context,
850 void (*log_fn)(struct xkb_context *context,
851 enum xkb_log_level level,
852 const char *format, va_list args));
857 * @defgroup keymap Keymap Creation
858 * Creating and destroying keymaps.
863 /** Flags for keymap compilation. */
864 enum xkb_keymap_compile_flags {
865 /** Do not apply any flags. */
866 XKB_KEYMAP_COMPILE_NO_FLAGS = 0
870 * Create a keymap from RMLVO names.
872 * The primary keymap entry point: creates a new XKB keymap from a set of
873 * RMLVO (Rules + Model + Layouts + Variants + Options) names.
875 * @param context The context in which to create the keymap.
876 * @param names The RMLVO names to use. See xkb_rule_names.
877 * @param flags Optional flags for the keymap, or 0.
879 * @returns A keymap compiled according to the RMLVO names, or NULL if
880 * the compilation failed.
883 * @memberof xkb_keymap
886 xkb_keymap_new_from_names(struct xkb_context *context,
887 const struct xkb_rule_names *names,
888 enum xkb_keymap_compile_flags flags);
890 /** The possible keymap formats. */
891 enum xkb_keymap_format {
892 /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
893 XKB_KEYMAP_FORMAT_TEXT_V1 = 1
897 * Create a keymap from a keymap file.
899 * @param context The context in which to create the keymap.
900 * @param file The keymap file to compile.
901 * @param format The text format of the keymap file to compile.
902 * @param flags Optional flags for the keymap, or 0.
904 * @returns A keymap compiled from the given XKB keymap file, or NULL if
905 * the compilation failed.
907 * The file must contain a complete keymap. For example, in the
908 * XKB_KEYMAP_FORMAT_TEXT_V1 format, this means the file must contain one
909 * top level '%xkb_keymap' section, which in turn contains other required
912 * @memberof xkb_keymap
915 xkb_keymap_new_from_file(struct xkb_context *context, FILE *file,
916 enum xkb_keymap_format format,
917 enum xkb_keymap_compile_flags flags);
920 * Create a keymap from a keymap string.
922 * This is just like xkb_keymap_new_from_file(), but instead of a file, gets
923 * the keymap as one enormous string.
925 * @see xkb_keymap_new_from_file()
926 * @memberof xkb_keymap
929 xkb_keymap_new_from_string(struct xkb_context *context, const char *string,
930 enum xkb_keymap_format format,
931 enum xkb_keymap_compile_flags flags);
934 * Create a keymap from a memory buffer.
936 * This is just like xkb_keymap_new_from_string(), but takes a length argument
937 * so the input string does not have to be zero-terminated.
939 * @see xkb_keymap_new_from_string()
940 * @memberof xkb_keymap
944 xkb_keymap_new_from_buffer(struct xkb_context *context, const char *buffer,
945 size_t length, enum xkb_keymap_format format,
946 enum xkb_keymap_compile_flags flags);
949 * Take a new reference on a keymap.
951 * @returns The passed in keymap.
953 * @memberof xkb_keymap
956 xkb_keymap_ref(struct xkb_keymap *keymap);
959 * Release a reference on a keymap, and possibly free it.
961 * @param keymap The keymap. If it is NULL, this function does nothing.
963 * @memberof xkb_keymap
966 xkb_keymap_unref(struct xkb_keymap *keymap);
969 * Get the keymap as a string in the format from which it was created.
970 * @sa xkb_keymap_get_as_string()
972 #define XKB_KEYMAP_USE_ORIGINAL_FORMAT ((enum xkb_keymap_format) -1)
975 * Get the compiled keymap as a string.
977 * @param keymap The keymap to get as a string.
978 * @param format The keymap format to use for the string. You can pass
979 * in the special value XKB_KEYMAP_USE_ORIGINAL_FORMAT to use the format
980 * from which the keymap was originally created.
982 * @returns The keymap as a NUL-terminated string, or NULL if unsuccessful.
984 * The returned string may be fed back into xkb_keymap_new_from_string() to get
985 * the exact same keymap (possibly in another process, etc.).
987 * The returned string is dynamically allocated and should be freed by the
990 * @memberof xkb_keymap
993 xkb_keymap_get_as_string(struct xkb_keymap *keymap,
994 enum xkb_keymap_format format);
999 * @defgroup components Keymap Components
1000 * Enumeration of state components in a keymap.
1006 * Get the minimum keycode in the keymap.
1009 * @memberof xkb_keymap
1013 xkb_keymap_min_keycode(struct xkb_keymap *keymap);
1016 * Get the maximum keycode in the keymap.
1019 * @memberof xkb_keymap
1023 xkb_keymap_max_keycode(struct xkb_keymap *keymap);
1026 * The iterator used by xkb_keymap_key_for_each().
1028 * @sa xkb_keymap_key_for_each
1029 * @memberof xkb_keymap
1033 (*xkb_keymap_key_iter_t)(struct xkb_keymap *keymap, xkb_keycode_t key,
1037 * Run a specified function for every valid keycode in the keymap. If a
1038 * keymap is sparse, this function may be called fewer than
1039 * (max_keycode - min_keycode + 1) times.
1041 * @sa xkb_keymap_min_keycode() xkb_keymap_max_keycode() xkb_keycode_t
1042 * @memberof xkb_keymap
1046 xkb_keymap_key_for_each(struct xkb_keymap *keymap, xkb_keymap_key_iter_t iter,
1050 * Find the name of the key with the given keycode.
1052 * This function always returns the canonical name of the key (see
1053 * description in xkb_keycode_t).
1055 * @returns The key name. If no key with this keycode exists,
1059 * @memberof xkb_keymap
1063 xkb_keymap_key_get_name(struct xkb_keymap *keymap, xkb_keycode_t key);
1066 * Find the keycode of the key with the given name.
1068 * The name can be either a canonical name or an alias.
1070 * @returns The keycode. If no key with this name exists,
1071 * returns XKB_KEYCODE_INVALID.
1074 * @memberof xkb_keymap
1078 xkb_keymap_key_by_name(struct xkb_keymap *keymap, const char *name);
1081 * Get the number of modifiers in the keymap.
1083 * @sa xkb_mod_index_t
1084 * @memberof xkb_keymap
1087 xkb_keymap_num_mods(struct xkb_keymap *keymap);
1090 * Get the name of a modifier by index.
1092 * @returns The name. If the index is invalid, returns NULL.
1094 * @sa xkb_mod_index_t
1095 * @memberof xkb_keymap
1098 xkb_keymap_mod_get_name(struct xkb_keymap *keymap, xkb_mod_index_t idx);
1101 * Get the index of a modifier by name.
1103 * @returns The index. If no modifier with this name exists, returns
1106 * @sa xkb_mod_index_t
1107 * @memberof xkb_keymap
1110 xkb_keymap_mod_get_index(struct xkb_keymap *keymap, const char *name);
1113 * Get the number of layouts in the keymap.
1115 * @sa xkb_layout_index_t xkb_rule_names xkb_keymap_num_layouts_for_key()
1116 * @memberof xkb_keymap
1119 xkb_keymap_num_layouts(struct xkb_keymap *keymap);
1122 * Get the name of a layout by index.
1124 * @returns The name. If the index is invalid, or the layout does not have
1125 * a name, returns NULL.
1127 * @sa xkb_layout_index_t
1128 * For notes on layout names.
1129 * @memberof xkb_keymap
1132 xkb_keymap_layout_get_name(struct xkb_keymap *keymap, xkb_layout_index_t idx);
1135 * Get the index of a layout by name.
1137 * @returns The index. If no layout exists with this name, returns
1138 * XKB_LAYOUT_INVALID. If more than one layout in the keymap has this name,
1139 * returns the lowest index among them.
1141 * @sa xkb_layout_index_t
1142 * For notes on layout names.
1143 * @memberof xkb_keymap
1146 xkb_keymap_layout_get_index(struct xkb_keymap *keymap, const char *name);
1149 * Get the number of LEDs in the keymap.
1151 * @warning The range [ 0...xkb_keymap_num_leds() ) includes all of the LEDs
1152 * in the keymap, but may also contain inactive LEDs. When iterating over
1153 * this range, you need the handle this case when calling functions such as
1154 * xkb_keymap_led_get_name() or xkb_state_led_index_is_active().
1156 * @sa xkb_led_index_t
1157 * @memberof xkb_keymap
1160 xkb_keymap_num_leds(struct xkb_keymap *keymap);
1163 * Get the name of a LED by index.
1165 * @returns The name. If the index is invalid, returns NULL.
1167 * @memberof xkb_keymap
1170 xkb_keymap_led_get_name(struct xkb_keymap *keymap, xkb_led_index_t idx);
1173 * Get the index of a LED by name.
1175 * @returns The index. If no LED with this name exists, returns
1178 * @memberof xkb_keymap
1181 xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name);
1184 * Get the number of layouts for a specific key.
1186 * This number can be different from xkb_keymap_num_layouts(), but is always
1187 * smaller. It is the appropriate value to use when iterating over the
1190 * @sa xkb_layout_index_t
1191 * @memberof xkb_keymap
1194 xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key);
1197 * Get the number of shift levels for a specific key and layout.
1199 * If @c layout is out of range for this key (that is, larger or equal to
1200 * the value returned by xkb_keymap_num_layouts_for_key()), it is brought
1201 * back into range in a manner consistent with xkb_state_key_get_layout().
1203 * @sa xkb_level_index_t
1204 * @memberof xkb_keymap
1207 xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key,
1208 xkb_layout_index_t layout);
1211 * Retrieves every possible modifier mask that produces the specified
1212 * shift level for a specific key and layout.
1214 * This API is useful for inverse key transformation; i.e. finding out
1215 * which modifiers need to be active in order to be able to type the
1216 * keysym(s) corresponding to the specific key code, layout and level.
1218 * @warning It returns only up to masks_size modifier masks. If the
1219 * buffer passed is too small, some of the possible modifier combinations
1220 * will not be returned.
1222 * @param[in] keymap The keymap.
1223 * @param[in] key The keycode of the key.
1224 * @param[in] layout The layout for which to get modifiers.
1225 * @param[in] level The shift level in the layout for which to get the
1226 * modifiers. This should be smaller than:
1227 * @code xkb_keymap_num_levels_for_key(keymap, key) @endcode
1228 * @param[out] masks_out A buffer in which the requested masks should be
1230 * @param[out] masks_size The number of elements in the buffer pointed to by
1233 * If @c layout is out of range for this key (that is, larger or equal to
1234 * the value returned by xkb_keymap_num_layouts_for_key()), it is brought
1235 * back into range in a manner consistent with xkb_state_key_get_layout().
1237 * @returns The number of modifier masks stored in the masks_out array.
1238 * If the key is not in the keymap or if the specified shift level cannot
1239 * be reached it returns 0 and does not modify the masks_out buffer.
1241 * @sa xkb_level_index_t
1242 * @sa xkb_mod_mask_t
1243 * @memberof xkb_keymap
1247 xkb_keymap_key_get_mods_for_level(struct xkb_keymap *keymap,
1249 xkb_layout_index_t layout,
1250 xkb_level_index_t level,
1251 xkb_mod_mask_t *masks_out,
1255 * Get the keysyms obtained from pressing a key in a given layout and
1258 * This function is like xkb_state_key_get_syms(), only the layout and
1259 * shift level are not derived from the keyboard state but are instead
1260 * specified explicitly.
1262 * @param[in] keymap The keymap.
1263 * @param[in] key The keycode of the key.
1264 * @param[in] layout The layout for which to get the keysyms.
1265 * @param[in] level The shift level in the layout for which to get the
1266 * keysyms. This should be smaller than:
1267 * @code xkb_keymap_num_levels_for_key(keymap, key) @endcode
1268 * @param[out] syms_out An immutable array of keysyms corresponding to the
1269 * key in the given layout and shift level.
1271 * If @c layout is out of range for this key (that is, larger or equal to
1272 * the value returned by xkb_keymap_num_layouts_for_key()), it is brought
1273 * back into range in a manner consistent with xkb_state_key_get_layout().
1275 * @returns The number of keysyms in the syms_out array. If no keysyms
1276 * are produced by the key in the given layout and shift level, returns 0
1277 * and sets syms_out to NULL.
1279 * @sa xkb_state_key_get_syms()
1280 * @memberof xkb_keymap
1283 xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap,
1285 xkb_layout_index_t layout,
1286 xkb_level_index_t level,
1287 const xkb_keysym_t **syms_out);
1290 * Determine whether a key should repeat or not.
1292 * A keymap may specify different repeat behaviors for different keys.
1293 * Most keys should generally exhibit repeat behavior; for example, holding
1294 * the 'a' key down in a text editor should normally insert a single 'a'
1295 * character every few milliseconds, until the key is released. However,
1296 * there are keys which should not or do not need to be repeated. For
1297 * example, repeating modifier keys such as Left/Right Shift or Caps Lock
1298 * is not generally useful or desired.
1300 * @returns 1 if the key should repeat, 0 otherwise.
1302 * @memberof xkb_keymap
1305 xkb_keymap_key_repeats(struct xkb_keymap *keymap, xkb_keycode_t key);
1308 xkb_keymap_key_set_repeats(struct xkb_keymap *keymap, xkb_keycode_t kc, int enable);
1314 * @defgroup state Keyboard State
1315 * Creating, destroying and manipulating keyboard state objects.
1321 * Create a new keyboard state object.
1323 * @param keymap The keymap which the state will use.
1325 * @returns A new keyboard state object, or NULL on failure.
1327 * @memberof xkb_state
1330 xkb_state_new(struct xkb_keymap *keymap);
1333 * Take a new reference on a keyboard state object.
1335 * @returns The passed in object.
1337 * @memberof xkb_state
1340 xkb_state_ref(struct xkb_state *state);
1343 * Release a reference on a keybaord state object, and possibly free it.
1345 * @param state The state. If it is NULL, this function does nothing.
1347 * @memberof xkb_state
1350 xkb_state_unref(struct xkb_state *state);
1353 * Get the keymap which a keyboard state object is using.
1355 * @returns The keymap which was passed to xkb_state_new() when creating
1356 * this state object.
1358 * This function does not take a new reference on the keymap; you must
1359 * explicitly reference it yourself if you plan to use it beyond the
1360 * lifetime of the state.
1362 * @memberof xkb_state
1365 xkb_state_get_keymap(struct xkb_state *state);
1368 * @page server-client-state Server State and Client State
1371 * The xkb_state API is used by two distinct actors in most window-system
1374 * 1. A *server* - for example, a Wayland compositor, an X11 server, an evdev
1377 * Servers maintain the XKB state for a device according to input events from
1378 * the device, such as key presses and releases, and out-of-band events from
1379 * the user, like UI layout switchers.
1381 * 2. A *client* - for example, a Wayland client, an X11 client.
1383 * Clients do not listen to input from the device; instead, whenever the
1384 * server state changes, the server serializes the state and notifies the
1385 * clients that the state has changed; the clients then update the state
1386 * from the serialization.
1388 * Some entry points in the xkb_state API are only meant for servers and some
1389 * are only meant for clients, and the two should generally not be mixed.
1394 /** Specifies the direction of the key (press / release). */
1395 enum xkb_key_direction {
1396 XKB_KEY_UP, /**< The key was released. */
1397 XKB_KEY_DOWN /**< The key was pressed. */
1401 * Modifier and layout types for state objects. This enum is bitmaskable,
1402 * e.g. (XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED) is valid to
1403 * exclude locked modifiers.
1405 * In XKB, the DEPRESSED components are also known as 'base'.
1407 enum xkb_state_component {
1408 /** Depressed modifiers, i.e. a key is physically holding them. */
1409 XKB_STATE_MODS_DEPRESSED = (1 << 0),
1410 /** Latched modifiers, i.e. will be unset after the next non-modifier
1412 XKB_STATE_MODS_LATCHED = (1 << 1),
1413 /** Locked modifiers, i.e. will be unset after the key provoking the
1414 * lock has been pressed again. */
1415 XKB_STATE_MODS_LOCKED = (1 << 2),
1416 /** Effective modifiers, i.e. currently active and affect key
1417 * processing (derived from the other state components).
1418 * Use this unless you explicitly care how the state came about. */
1419 XKB_STATE_MODS_EFFECTIVE = (1 << 3),
1420 /** Depressed layout, i.e. a key is physically holding it. */
1421 XKB_STATE_LAYOUT_DEPRESSED = (1 << 4),
1422 /** Latched layout, i.e. will be unset after the next non-modifier
1424 XKB_STATE_LAYOUT_LATCHED = (1 << 5),
1425 /** Locked layout, i.e. will be unset after the key provoking the lock
1426 * has been pressed again. */
1427 XKB_STATE_LAYOUT_LOCKED = (1 << 6),
1428 /** Effective layout, i.e. currently active and affects key processing
1429 * (derived from the other state components).
1430 * Use this unless you explicitly care how the state came about. */
1431 XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7),
1432 /** LEDs (derived from the other state components). */
1433 XKB_STATE_LEDS = (1 << 8)
1437 * Update the keyboard state to reflect a given key being pressed or
1440 * This entry point is intended for *server* applications and should not be used
1441 * by *client* applications; see @ref server-client-state for details.
1443 * A series of calls to this function should be consistent; that is, a call
1444 * with XKB_KEY_DOWN for a key should be matched by an XKB_KEY_UP; if a key
1445 * is pressed twice, it should be released twice; etc. Otherwise (e.g. due
1446 * to missed input events), situations like "stuck modifiers" may occur.
1448 * This function is often used in conjunction with the function
1449 * xkb_state_key_get_syms() (or xkb_state_key_get_one_sym()), for example,
1450 * when handling a key event. In this case, you should prefer to get the
1451 * keysyms *before* updating the key, such that the keysyms reported for
1452 * the key event are not affected by the event itself. This is the
1453 * conventional behavior.
1455 * @returns A mask of state components that have changed as a result of
1456 * the update. If nothing in the state has changed, returns 0.
1458 * @memberof xkb_state
1460 * @sa xkb_state_update_mask()
1462 enum xkb_state_component
1463 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
1464 enum xkb_key_direction direction);
1467 * Update a keyboard state from a set of explicit masks.
1469 * This entry point is intended for *client* applications; see @ref
1470 * server-client-state for details. *Server* applications should use
1471 * xkb_state_update_key() instead.
1473 * All parameters must always be passed, or the resulting state may be
1476 * The serialization is lossy and will not survive round trips; it must only
1477 * be used to feed client state objects, and must not be used to update the
1480 * @returns A mask of state components that have changed as a result of
1481 * the update. If nothing in the state has changed, returns 0.
1483 * @memberof xkb_state
1485 * @sa xkb_state_component
1486 * @sa xkb_state_update_key
1488 enum xkb_state_component
1489 xkb_state_update_mask(struct xkb_state *state,
1490 xkb_mod_mask_t depressed_mods,
1491 xkb_mod_mask_t latched_mods,
1492 xkb_mod_mask_t locked_mods,
1493 xkb_layout_index_t depressed_layout,
1494 xkb_layout_index_t latched_layout,
1495 xkb_layout_index_t locked_layout);
1498 * Get the keysyms obtained from pressing a particular key in a given
1501 * Get the keysyms for a key according to the current active layout,
1502 * modifiers and shift level for the key, as determined by a keyboard
1505 * @param[in] state The keyboard state object.
1506 * @param[in] key The keycode of the key.
1507 * @param[out] syms_out An immutable array of keysyms corresponding the
1508 * key in the given keyboard state.
1510 * As an extension to XKB, this function can return more than one keysym.
1511 * If you do not want to handle this case, you can use
1512 * xkb_state_key_get_one_sym() for a simpler interface.
1514 * This function does not perform any @ref keysym-transformations.
1515 * (This might change).
1517 * @returns The number of keysyms in the syms_out array. If no keysyms
1518 * are produced by the key in the given keyboard state, returns 0 and sets
1521 * @memberof xkb_state
1524 xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
1525 const xkb_keysym_t **syms_out);
1528 * Get the Unicode/UTF-8 string obtained from pressing a particular key
1529 * in a given keyboard state.
1531 * @param[in] state The keyboard state object.
1532 * @param[in] key The keycode of the key.
1533 * @param[out] buffer A buffer to write the string into.
1534 * @param[in] size Size of the buffer.
1536 * @warning If the buffer passed is too small, the string is truncated
1537 * (though still NUL-terminated).
1539 * @returns The number of bytes required for the string, excluding the
1540 * NUL byte. If there is nothing to write, returns 0.
1542 * You may check if truncation has occurred by comparing the return value
1543 * with the size of @p buffer, similarly to the snprintf(3) function.
1544 * You may safely pass NULL and 0 to @p buffer and @p size to find the
1545 * required size (without the NUL-byte).
1547 * This function performs Capitalization and Control @ref
1548 * keysym-transformations.
1550 * @memberof xkb_state
1554 xkb_state_key_get_utf8(struct xkb_state *state, xkb_keycode_t key,
1555 char *buffer, size_t size);
1558 * Get the Unicode/UTF-32 codepoint obtained from pressing a particular
1559 * key in a a given keyboard state.
1561 * @returns The UTF-32 representation for the key, if it consists of only
1562 * a single codepoint. Otherwise, returns 0.
1564 * This function performs Capitalization and Control @ref
1565 * keysym-transformations.
1567 * @memberof xkb_state
1571 xkb_state_key_get_utf32(struct xkb_state *state, xkb_keycode_t key);
1574 * Get the single keysym obtained from pressing a particular key in a
1575 * given keyboard state.
1577 * This function is similar to xkb_state_key_get_syms(), but intended
1578 * for users which cannot or do not want to handle the case where
1579 * multiple keysyms are returned (in which case this function is
1582 * @returns The keysym. If the key does not have exactly one keysym,
1583 * returns XKB_KEY_NoSymbol
1585 * This function performs Capitalization @ref keysym-transformations.
1587 * @sa xkb_state_key_get_syms()
1588 * @memberof xkb_state
1591 xkb_state_key_get_one_sym(struct xkb_state *state, xkb_keycode_t key);
1594 * Get the effective layout index for a key in a given keyboard state.
1596 * @returns The layout index for the key in the given keyboard state. If
1597 * the given keycode is invalid, or if the key is not included in any
1598 * layout at all, returns XKB_LAYOUT_INVALID.
1600 * @invariant If the returned layout is valid, the following always holds:
1602 * xkb_state_key_get_layout(state, key) < xkb_keymap_num_layouts_for_key(keymap, key)
1605 * @memberof xkb_state
1608 xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t key);
1611 * Get the effective shift level for a key in a given keyboard state and
1614 * @param state The keyboard state.
1615 * @param key The keycode of the key.
1616 * @param layout The layout for which to get the shift level. This must be
1618 * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
1619 * usually it would be:
1620 * @code xkb_state_key_get_layout(state, key) @endcode
1622 * @return The shift level index. If the key or layout are invalid,
1623 * returns XKB_LEVEL_INVALID.
1625 * @invariant If the returned level is valid, the following always holds:
1627 * xkb_state_key_get_level(state, key, layout) < xkb_keymap_num_levels_for_key(keymap, key, layout)
1630 * @memberof xkb_state
1633 xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key,
1634 xkb_layout_index_t layout);
1637 * Match flags for xkb_state_mod_indices_are_active() and
1638 * xkb_state_mod_names_are_active(), specifying the conditions for a
1639 * successful match. XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with
1642 enum xkb_state_match {
1643 /** Returns true if any of the modifiers are active. */
1644 XKB_STATE_MATCH_ANY = (1 << 0),
1645 /** Returns true if all of the modifiers are active. */
1646 XKB_STATE_MATCH_ALL = (1 << 1),
1647 /** Makes matching non-exclusive, i.e. will not return false if a
1648 * modifier not specified in the arguments is active. */
1649 XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16)
1653 * The counterpart to xkb_state_update_mask for modifiers, to be used on
1654 * the server side of serialization.
1656 * This entry point is intended for *server* applications; see @ref
1657 * server-client-state for details. *Client* applications should use the
1658 * xkb_state_mod_*_is_active API.
1660 * @param state The keyboard state.
1661 * @param components A mask of the modifier state components to serialize.
1662 * State components other than XKB_STATE_MODS_* are ignored.
1663 * If XKB_STATE_MODS_EFFECTIVE is included, all other state components are
1666 * @returns A xkb_mod_mask_t representing the given components of the
1669 * @memberof xkb_state
1672 xkb_state_serialize_mods(struct xkb_state *state,
1673 enum xkb_state_component components);
1676 * The counterpart to xkb_state_update_mask for layouts, to be used on
1677 * the server side of serialization.
1679 * This entry point is intended for *server* applications; see @ref
1680 * server-client-state for details. *Client* applications should use the
1681 * xkb_state_layout_*_is_active API.
1683 * @param state The keyboard state.
1684 * @param components A mask of the layout state components to serialize.
1685 * State components other than XKB_STATE_LAYOUT_* are ignored.
1686 * If XKB_STATE_LAYOUT_EFFECTIVE is included, all other state components are
1689 * @returns A layout index representing the given components of the
1692 * @memberof xkb_state
1695 xkb_state_serialize_layout(struct xkb_state *state,
1696 enum xkb_state_component components);
1699 * Test whether a modifier is active in a given keyboard state by name.
1701 * @returns 1 if the modifier is active, 0 if it is not. If the modifier
1702 * name does not exist in the keymap, returns -1.
1704 * @memberof xkb_state
1707 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
1708 enum xkb_state_component type);
1711 * Test whether a set of modifiers are active in a given keyboard state by
1714 * @param state The keyboard state.
1715 * @param type The component of the state against which to match the
1717 * @param match The manner by which to match the state against the
1719 * @param ... The set of of modifier names to test, terminated by a NULL
1720 * argument (sentinel).
1722 * @returns 1 if the modifiers are active, 0 if they are not. If any of
1723 * the modifier names do not exist in the keymap, returns -1.
1725 * @memberof xkb_state
1728 xkb_state_mod_names_are_active(struct xkb_state *state,
1729 enum xkb_state_component type,
1730 enum xkb_state_match match,
1734 * Test whether a modifier is active in a given keyboard state by index.
1736 * @returns 1 if the modifier is active, 0 if it is not. If the modifier
1737 * index is invalid in the keymap, returns -1.
1739 * @memberof xkb_state
1742 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
1743 enum xkb_state_component type);
1746 * Test whether a set of modifiers are active in a given keyboard state by
1749 * @param state The keyboard state.
1750 * @param type The component of the state against which to match the
1752 * @param match The manner by which to match the state against the
1754 * @param ... The set of of modifier indices to test, terminated by a
1755 * XKB_MOD_INVALID argument (sentinel).
1757 * @returns 1 if the modifiers are active, 0 if they are not. If any of
1758 * the modifier indices are invalid in the keymap, returns -1.
1760 * @memberof xkb_state
1763 xkb_state_mod_indices_are_active(struct xkb_state *state,
1764 enum xkb_state_component type,
1765 enum xkb_state_match match,
1769 * @page consumed-modifiers Consumed Modifiers
1772 * Some functions, like xkb_state_key_get_syms(), look at the state of
1773 * the modifiers in the keymap and derive from it the correct shift level
1774 * to use for the key. For example, in a US layout, pressing the key
1775 * labeled \<A\> while the Shift modifier is active, generates the keysym
1776 * 'A'. In this case, the Shift modifier is said to be "consumed".
1777 * However, the Num Lock modifier does not affect this translation at all,
1778 * even if it is active, so it is not consumed by this translation.
1780 * It may be desirable for some application to not reuse consumed modifiers
1781 * for further processing, e.g. for hotkeys or keyboard shortcuts. To
1782 * understand why, consider some requirements from a standard shortcut
1783 * mechanism, and how they are implemented:
1785 * 1. The shortcut's modifiers must match exactly to the state. For
1786 * example, it is possible to bind separate actions to \<Alt\>\<Tab\>
1787 * and to \<Alt\>\<Shift\>\<Tab\>. Further, if only \<Alt\>\<Tab\> is
1788 * bound to an action, pressing \<Alt\>\<Shift\>\<Tab\> should not
1789 * trigger the shortcut.
1790 * Effectively, this means that the modifiers are compared using the
1791 * equality operator (==).
1793 * 2. Only relevant modifiers are considered for the matching. For example,
1794 * Caps Lock and Num Lock should not generally affect the matching, e.g.
1795 * when matching \<Alt\>\<Tab\> against the state, it does not matter
1796 * whether Num Lock is active or not. These relevant, or "significant",
1797 * modifiers usually include Alt, Control, Shift, Super and similar.
1798 * Effectively, this means that non-significant modifiers are masked out,
1799 * before doing the comparison as described above.
1801 * 3. The matching must be independent of the layout/keymap. For example,
1802 * the \<Plus\> (+) symbol is found on the first level on some layouts,
1803 * but requires holding Shift on others. If you simply bind the action
1804 * to the \<Plus\> keysym, it would work for the unshifted kind, but
1805 * not for the others, because the match against Shift would fail. If
1806 * you bind the action to \<Shift\>\<Plus\>, only the shifted kind would
1807 * work. So what is needed is to recognize that Shift is used up in the
1808 * translation of the keysym itself, and therefore should not be included
1810 * Effectively, this means that consumed modifiers (Shift in this example)
1811 * are masked out as well, before doing the comparison.
1813 * In summary, this is approximately how the matching would be performed:
1815 * (keysym == shortcut_keysym) &&
1816 * ((state_mods & ~consumed_mods & significant_mods) == shortcut_mods)
1819 * @c state_mods are the modifiers reported by
1820 * xkb_state_mod_index_is_active() and similar functions.
1821 * @c consumed_mods are the modifiers reported by
1822 * xkb_state_mod_index_is_consumed() and similar functions.
1823 * @c significant_mods are decided upon by the application/toolkit/user;
1824 * it is up to them to decide whether these are configurable or hard-coded.
1830 * Consumed modifiers mode.
1832 * There are several possible methods for deciding which modifiers are
1833 * consumed and which are not, each applicable for different systems or
1834 * situations. The mode selects the method to use.
1836 * Keep in mind that in all methods, the keymap may decide to "preserve"
1837 * a modifier, meaning it is not reported as consumed even if it would
1840 enum xkb_consumed_mode {
1842 * This is the mode defined in the XKB specification and used by libX11.
1844 * A modifier is consumed if and only if it *may affect* key translation.
1846 * For example, if `Control+Alt+<Backspace>` produces some assigned keysym,
1847 * then when pressing just `<Backspace>`, `Control` and `Alt` are consumed,
1848 * even though they are not active, since if they *were* active they would
1849 * have affected key translation.
1851 XKB_CONSUMED_MODE_XKB,
1853 * This is the mode used by the GTK+ toolkit.
1855 * The mode consists of the following two independent heuristics:
1857 * - The currently active set of modifiers, excluding modifiers which do
1858 * not affect the key (as described for @ref XKB_CONSUMED_MODE_XKB), are
1859 * considered consumed, if the keysyms produced when all of them are
1860 * active are different from the keysyms produced when no modifiers are
1863 * - A single modifier is considered consumed if the keysyms produced for
1864 * the key when it is the only active modifier are different from the
1865 * keysyms produced when no modifiers are active.
1867 XKB_CONSUMED_MODE_GTK
1871 * Get the mask of modifiers consumed by translating a given key.
1873 * @param state The keyboard state.
1874 * @param key The keycode of the key.
1875 * @param mode The consumed modifiers mode to use; see enum description.
1877 * @returns a mask of the consumed modifiers.
1879 * @memberof xkb_state
1883 xkb_state_key_get_consumed_mods2(struct xkb_state *state, xkb_keycode_t key,
1884 enum xkb_consumed_mode mode);
1887 * Same as xkb_state_key_get_consumed_mods2() with mode XKB_CONSUMED_MODE_XKB.
1889 * @memberof xkb_state
1893 xkb_state_key_get_consumed_mods(struct xkb_state *state, xkb_keycode_t key);
1896 * Test whether a modifier is consumed by keyboard state translation for
1899 * @param state The keyboard state.
1900 * @param key The keycode of the key.
1901 * @param idx The index of the modifier to check.
1902 * @param mode The consumed modifiers mode to use; see enum description.
1904 * @returns 1 if the modifier is consumed, 0 if it is not. If the modifier
1905 * index is not valid in the keymap, returns -1.
1907 * @sa xkb_state_mod_mask_remove_consumed()
1908 * @sa xkb_state_key_get_consumed_mods()
1909 * @memberof xkb_state
1913 xkb_state_mod_index_is_consumed2(struct xkb_state *state,
1915 xkb_mod_index_t idx,
1916 enum xkb_consumed_mode mode);
1919 * Same as xkb_state_mod_index_is_consumed2() with mode XKB_CONSUMED_MOD_XKB.
1921 * @memberof xkb_state
1925 xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key,
1926 xkb_mod_index_t idx);
1929 * Remove consumed modifiers from a modifier mask for a key.
1931 * @deprecated Use xkb_state_key_get_consumed_mods2() instead.
1933 * Takes the given modifier mask, and removes all modifiers which are
1934 * consumed for that particular key (as in xkb_state_mod_index_is_consumed()).
1936 * @sa xkb_state_mod_index_is_consumed()
1937 * @memberof xkb_state
1940 xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t key,
1941 xkb_mod_mask_t mask);
1944 * Test whether a layout is active in a given keyboard state by name.
1946 * @returns 1 if the layout is active, 0 if it is not. If no layout with
1947 * this name exists in the keymap, return -1.
1949 * If multiple layouts in the keymap have this name, the one with the lowest
1952 * @sa xkb_layout_index_t
1953 * @memberof xkb_state
1956 xkb_state_layout_name_is_active(struct xkb_state *state, const char *name,
1957 enum xkb_state_component type);
1960 * Test whether a layout is active in a given keyboard state by index.
1962 * @returns 1 if the layout is active, 0 if it is not. If the layout index
1963 * is not valid in the keymap, returns -1.
1965 * @sa xkb_layout_index_t
1966 * @memberof xkb_state
1969 xkb_state_layout_index_is_active(struct xkb_state *state,
1970 xkb_layout_index_t idx,
1971 enum xkb_state_component type);
1974 * Test whether a LED is active in a given keyboard state by name.
1976 * @returns 1 if the LED is active, 0 if it not. If no LED with this name
1977 * exists in the keymap, returns -1.
1979 * @sa xkb_led_index_t
1980 * @memberof xkb_state
1983 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
1986 * Test whether a LED is active in a given keyboard state by index.
1988 * @returns 1 if the LED is active, 0 if it not. If the LED index is not
1989 * valid in the keymap, returns -1.
1991 * @sa xkb_led_index_t
1992 * @memberof xkb_state
1995 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
1999 /* Leave this include last, so it can pick up our types, etc. */
2000 #include <xkbcommon/xkbcommon-compat.h>
2006 #endif /* _XKBCOMMON_H_ */