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.
106 * Objects are created in a specific context, and multiple contexts may
107 * coexist simultaneously. Objects from different contexts are completely
108 * separated and do not share any memory or state.
109 * A context is created, accessed, manipulated and destroyed through the
110 * xkb_context_*() API.
116 * Opaque compiled keymap object.
118 * The keymap object holds all of the static keyboard information obtained
119 * from compiling XKB files.
121 * A keymap is immutable after it is created (besides reference counts, etc.);
122 * if you need to change it, you must create a new one.
124 * A keymap object is created, accessed and destroyed through the
125 * xkb_keymap_*() API.
131 * Opaque keyboard state object.
133 * State objects contain the active state of a keyboard (or keyboards), such
134 * as the currently effective layout and the active modifiers. It acts as a
135 * simple state machine, wherein key presses and releases are the input, and
136 * key symbols (keysyms) are the output.
138 * A state object is created, accessed, manipulated and destroyed through the
144 * A number used to represent a physical key on a keyboard.
146 * A standard PC-compatible keyboard might have 102 keys. An appropriate
147 * keymap would assign each of them a keycode, by which the user should
148 * refer to the key throughout the library.
150 * Historically, the X11 protocol, and consequentially the XKB protocol,
151 * assign only 8 bits for keycodes. This limits the number of different
152 * keys that can be used simultaneously in a single keymap to 256
153 * (disregarding other limitations). This library does not share this limit;
154 * keycodes beyond 255 ('extended keycodes') are not treated specially.
155 * Keymaps and applications which are compatible with X11 should not use
158 * @todo Explain how keycodes are mapped to scancodes.
160 * @sa xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11()
162 typedef uint32_t xkb_keycode_t;
165 * A number used to represent the symbols visible on the keycaps of a
168 * A key, represented by a keycode, may generate different symbols according
169 * to keyboard state. For example, on a QWERTY keyboard, pressing the key
170 * labled <A> generates the symbol 'a'. If the Shift key is held, it
171 * generates the symbol 'A'. If a different layout is used, say Greek,
172 * it generates the symbol 'α'. And so on.
174 * Each such symbol is represented by a keysym. Note that keysyms are
175 * somewhat more general, in that they can also represent some "function",
176 * such as "Left" or "Right" for the arrow keys. For more information,
178 * http://www.x.org/releases/X11R7.7/doc/xproto/x11protocol.html#keysym_encoding
180 * Specifically named keysyms can be found in the
181 * xkbcommon/xkbcommon-keysyms.h header file. Their name does not include
182 * the XKB_KEY_ prefix.
184 * Besides those, any Unicode/ISO 10646 character in the range U0100 to
185 * U10FFFF can be represented by a keysym value in the range 0x01000100 to
186 * 0x0110FFFF. The name of Unicode keysyms is "U<codepoint>", e.g. "Ua1b2".
188 * The name of other unnamed keysyms is the hexadecimal representation of
189 * their value, e.g. "0xabcd1234".
191 * Keysym names are case-sensitive.
193 typedef uint32_t xkb_keysym_t;
196 * Index of a modifier.
198 * @todo Explain what are modifiers.
200 * Modifier indexes are consecutive. The first modifier has index 0.
202 * Each modifier must have a name, and the names are unique. Therefore, it
203 * is safe to use the name as a unique identifier for a modifier. Modifier
204 * names are case-sensitive.
206 * @sa xkb_keymap_num_mods()
208 typedef uint32_t xkb_mod_index_t;
209 /** A mask of modifier indexes. */
210 typedef uint32_t xkb_mod_mask_t;
213 * Index of a keyboard layout.
215 * @todo Explain what are layouts.
217 * Layout indexes are consecutive. The first layout has index 0.
219 * Each layout is not required to have a name, and the names are not
220 * guarenteed to be unique (though they are usually provided and unique).
221 * Therefore, it is not safe to use the name as a unique identifier for a
222 * layout. Layout names are case-sensitive.
224 * Layouts are also called "groups" by XKB.
226 * @sa xkb_keymap_num_layouts() xkb_keymap_num_layouts_for_key()
228 typedef uint32_t xkb_layout_index_t;
229 /** A mask of layout indexes. */
230 typedef uint32_t xkb_layout_mask_t;
233 * Index of a shift level.
235 * @todo Explain what are shift levels.
237 typedef uint32_t xkb_level_index_t;
240 * Index of a keyboard LED.
242 * @todo Explain what are LEDs.
244 * LED indexes are non-consecutive. The first LED has index 0.
246 * LED names are case-sensitive.
248 * Each LED must have a name, and the names are unique. Therefore,
249 * it is safe to use the name as a unique identifier for a LED.
251 * @warning A given keymap may specify an exact index for a given LED.
252 * Therefore, LED indexing is not necessarily sequential, as opposed to
253 * modifiers and layouts. This means that when iterating over the LEDs
254 * in a keymap using e.g. xkb_keymap_num_leds(), some indexes might be
255 * invalid. Given such an index, functions like xkb_keymap_led_get_name()
256 * will return NULL, and xkb_state_led_index_is_active() will return -1.
258 * LEDs are also called "indicators" by XKB.
260 * @sa xkb_keymap_num_leds()
262 typedef uint32_t xkb_led_index_t;
263 /** A mask of LED indexes. */
264 typedef uint32_t xkb_led_mask_t;
266 #define XKB_MOD_INVALID (0xffffffff)
267 #define XKB_LAYOUT_INVALID (0xffffffff)
268 #define XKB_KEYCODE_INVALID (0xffffffff)
269 #define XKB_LEVEL_INVALID (0xffffffff)
270 #define XKB_LED_INVALID (0xffffffff)
272 #define XKB_KEYCODE_MAX (0xffffffff - 1)
275 * Test whether a value is a valid extended keycode.
278 #define xkb_keycode_is_legal_ext(key) (key <= XKB_KEYCODE_MAX)
281 * Test whether a value is a valid X11 keycode.
284 #define xkb_keycode_is_legal_x11(key) (key >= 8 && key <= 255)
287 * Names to compile a keymap with, also known as RMLVO.
289 * These names together are the primary identifier for a keymap.
290 * If any of the members is NULL or an empty string (""), a default value is
291 * used. It is recommended to use the system default by passing NULL for
292 * unspecified values, instead of providing your own defaults.
294 struct xkb_rule_names {
295 /** The rules file to use. The rules file describes how to interpret
296 * the values of the model, layout, variant and options fields. */
298 /** The keyboard model by which to interpret keycodes and LEDs. */
300 /** A comma seperated list of layouts (languages) to include in the
303 /** A comma seperated list of variants, one per layout, which may
304 * modify or augment the respective layout in various ways. */
306 /** A comma seprated list of options, through which the user specifies
307 * non-layout related preferences, like which key combinations are used
308 * for switching layouts, or which key is the Compose key. */
313 * @defgroup keysyms Keysyms
314 * Utility functions related to keysyms.
320 * Get the name of a keysym.
322 * For a description of how keysyms are named, see @ref xkb_keysym_t.
324 * @param[in] keysym The keysym.
325 * @param[out] buffer A string buffer to write the name into.
326 * @param[in] size Size of the buffer.
328 * @warning If the buffer passed is too small, the string is truncated
329 * (though still NUL-terminated); a size of at least 64 bytes is recommended.
331 * @returns The number of bytes in the name, excluding the NUL byte. If
332 * the keysym is invalid, returns -1.
334 * You may check if truncation has occured by comparing the return value
335 * with the length of buffer, similarly to the snprintf(3) function.
340 xkb_keysym_get_name(xkb_keysym_t keysym, char *buffer, size_t size);
342 /** Flags for xkb_keysym_from_name(). */
343 enum xkb_keysym_flags {
344 /** Find keysym by case-insensitive search. */
345 XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0),
349 * Get a keysym from its name.
351 * @param name The name of a keysym. See remarks in xkb_keysym_get_name();
352 * this function will accept any name returned by that function.
353 * @param flags A set of flags controlling how the search is done. If
354 * invalid flags are passed, this will fail with XKB_KEY_NoSymbol.
356 * If you use the XKB_KEYSYM_CASE_INSENSITIVE flag and two keysym names
357 * differ only by case, then the lower-case keysym is returned. For
358 * instance, for KEY_a and KEY_A, this function would return KEY_a for the
359 * case-insensitive search. If this functionality is needed, it is
360 * recommended to first call this function without this flag; and if that
361 * fails, only then to try with this flag, while possibly warning the user
362 * he had misspelled the name, and might get wrong results.
364 * @returns The keysym. If the name is invalid, returns XKB_KEY_NoSymbol.
369 xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags);
372 * Get the Unicode/UTF-8 representation of a keysym.
374 * @param[in] keysym The keysym.
375 * @param[out] buffer A buffer to write the UTF-8 string into.
376 * @param[in] size The size of buffer. Must be at least 7.
378 * @returns The number of bytes written to the buffer. If the keysym does
379 * not have a Unicode representation, returns 0. If the buffer is too small,
383 xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size);
386 * Get the Unicode/UTF-32 representation of a keysym.
388 * @returns The Unicode/UTF-32 representation of keysym, which is also
389 * compatible with UCS-4. If the keysym does not have a Unicode
390 * representation, returns 0.
393 xkb_keysym_to_utf32(xkb_keysym_t keysym);
398 * @defgroup context Library Context
399 * Creating, destroying and using library contexts.
401 * Every keymap compilation request must have a context associated with
402 * it. The context keeps around state such as the include path.
407 /** Flags for context creation. */
408 enum xkb_context_flags {
409 /** Create this context with an empty include path. */
410 XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
414 * Create a new context.
416 * @param flags Optional flags for the context, or 0.
418 * @returns A new context, or NULL on failure.
420 * The user may set some environment variables to affect default values in
421 * the context. See e.g. xkb_context_set_log_level() and
422 * xkb_context_set_log_verbosity().
424 * @memberof xkb_context
427 xkb_context_new(enum xkb_context_flags flags);
430 * Take a new reference on a context.
432 * @returns The passed in context.
434 * @memberof xkb_context
437 xkb_context_ref(struct xkb_context *context);
440 * Release a reference on a context, and possibly free it.
442 * @memberof xkb_context
445 xkb_context_unref(struct xkb_context *context);
448 * Append a new entry to the context's include path.
450 * @returns 1 on success, or 0 if the include path could not be added or is
453 * @memberof xkb_context
456 xkb_context_include_path_append(struct xkb_context *context, const char *path);
459 * Append the default include paths to the context's include path.
461 * @returns 1 on success, or 0 if the primary include path could not be added.
463 * @memberof xkb_context
466 xkb_context_include_path_append_default(struct xkb_context *context);
469 * Reset the context's include path to the default.
471 * Removes all entries from the context's include path, and inserts the
474 * @returns 1 on success, or 0 if the primary include path could not be added.
476 * @memberof xkb_context
479 xkb_context_include_path_reset_defaults(struct xkb_context *context);
482 * Remove all entries from the context's include path.
484 * @memberof xkb_context
487 xkb_context_include_path_clear(struct xkb_context *context);
490 * Get the number of paths in the context's include path.
492 * @memberof xkb_context
495 xkb_context_num_include_paths(struct xkb_context *context);
498 * Get a specific include path from the context's include path.
500 * @returns The include path at the specified index within the context, or
501 * NULL if the index is invalid.
503 * @memberof xkb_context
506 xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
509 * Store custom user data in the context.
511 * This may be useful in conjuction with xkb_context_set_log_fn() or other
514 * @memberof xkb_context
517 xkb_context_set_user_data(struct xkb_context *context, void *user_data);
520 * Retrieves stored user data from the context.
522 * @returns The stored user data. If the user data wasn't set, or the
523 * passed in context is NULL, returns NULL.
525 * This may be useful to access private user data from callbacks like a
526 * custom logging function.
528 * @memberof xkb_context
531 xkb_context_get_user_data(struct xkb_context *context);
536 * @defgroup logging Logging Handling
537 * Manipulating how logging from this library is handled.
542 /** Specifies a logging level. */
544 XKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
545 XKB_LOG_LEVEL_ERROR = 20, /**< Log all errors. */
546 XKB_LOG_LEVEL_WARNING = 30, /**< Log warnings and errors. */
547 XKB_LOG_LEVEL_INFO = 40, /**< Log information, warnings, and errors. */
548 XKB_LOG_LEVEL_DEBUG = 50, /**< Log everything. */
552 * Set the current logging level.
554 * @param context The context in which to set the logging level.
555 * @param level The logging level to use. Only messages from this level
556 * and below will be logged.
558 * The default level is XKB_LOG_LEVEL_ERROR. The environment variable
559 * XKB_LOG_LEVEL, if set in the time the context was created, overrides the
560 * default value. It may be specified as a level number or name.
562 * @memberof xkb_context
565 xkb_context_set_log_level(struct xkb_context *context,
566 enum xkb_log_level level);
569 * Get the current logging level.
571 * @memberof xkb_context
574 xkb_context_get_log_level(struct xkb_context *context);
577 * Sets the current logging verbosity.
579 * The library can generate a number of warnings which are not helpful to
580 * ordinary users of the library. The verbosity may be increased if more
581 * information is desired (e.g. when developing a new keymap).
583 * The default verbosity is 0. The environment variable XKB_LOG_VERBOSITY,
584 * if set in the time the context was created, overrides the default value.
586 * @param context The context in which to use the set verbosity.
587 * @param verbosity The verbosity to use. Currently used values are
588 * 1 to 10, higher values being more verbose. 0 would result in no verbose
589 * messages being logged.
591 * Most verbose messages are of level XKB_LOG_LEVEL_WARNING or lower.
593 * @memberof xkb_context
596 xkb_context_set_log_verbosity(struct xkb_context *context, int verbosity);
599 * Get the current logging verbosity of the context.
601 * @memberof xkb_context
604 xkb_context_get_log_verbosity(struct xkb_context *context);
607 * Set a custom function to handle logging messages.
609 * @param context The context in which to use the set logging function.
610 * @param log_fn The function that will be called for logging messages.
611 * Passing NULL restores the default function, which logs to stderr.
613 * By default, log messages from this library are printed to stderr. This
614 * function allows you to replace the default behavior with a custom
615 * handler. The handler is only called with messages which match the
616 * current logging level and verbosity settings for the context.
617 * level is the logging level of the message. format and args are the
618 * same as in the vprintf(3) function.
620 * You may use xkb_context_set_user_data() on the context, and then call
621 * xkb_context_get_user_data() from within the logging function to provide
622 * it with additional private context.
624 * @memberof xkb_context
627 xkb_context_set_log_fn(struct xkb_context *context,
628 void (*log_fn)(struct xkb_context *context,
629 enum xkb_log_level level,
630 const char *format, va_list args));
635 * @defgroup keymap Keymap Creation
636 * Creating and destroying keymaps.
641 /** Flags for keymap compilation. */
642 enum xkb_keymap_compile_flags {
643 /** Apparently you can't have empty enums. What a drag. */
644 XKB_MAP_COMPILE_PLACEHOLDER = 0,
648 * Create a keymap from RMLVO names.
650 * The primary keymap entry point: creates a new XKB keymap from a set of
651 * RMLVO (Rules + Model + Layouts + Variants + Options) names.
653 * You should almost certainly be using this and nothing else to create
656 * @param context The context in which to create the keymap.
657 * @param names The RMLVO names to use.
658 * @param flags Optional flags for the keymap, or 0.
660 * @returns A keymap compiled according to the RMLVO names, or NULL if
661 * the compilation failed.
664 * @memberof xkb_keymap
667 xkb_keymap_new_from_names(struct xkb_context *context,
668 const struct xkb_rule_names *names,
669 enum xkb_keymap_compile_flags flags);
671 /** The possible keymap text formats. */
672 enum xkb_keymap_format {
673 /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
674 XKB_KEYMAP_FORMAT_TEXT_V1 = 1,
678 * Create a keymap from a keymap file.
680 * @param context The context in which to create the keymap.
681 * @param file The keymap file to compile.
682 * @param format The text format of the keymap file to compile.
683 * @param flags Optional flags for the keymap, or 0.
685 * @returns A keymap compiled from the given XKB keymap file, or NULL if
686 * the compilation failed.
688 * The file must contain a complete keymap. For example, in the
689 * XKB_KEYMAP_FORMAT_TEXT_V1 format, this means the file must contain one
690 * top level '%xkb_keymap' section, which in turn contains other required
693 * @memberof xkb_keymap
696 xkb_keymap_new_from_file(struct xkb_context *context, FILE *file,
697 enum xkb_keymap_format format,
698 enum xkb_keymap_compile_flags flags);
701 * Create a keymap from a keymap string.
703 * This is just like xkb_keymap_new_from_file(), but instead of a file, gets
704 * the keymap as one enormous string.
706 * @see xkb_keymap_new_from_string()
707 * @memberof xkb_keymap
710 xkb_keymap_new_from_string(struct xkb_context *context, const char *string,
711 enum xkb_keymap_format format,
712 enum xkb_keymap_compile_flags flags);
715 * Take a new reference on a keymap.
717 * @returns The passed in keymap.
719 * @memberof xkb_keymap
722 xkb_keymap_ref(struct xkb_keymap *keymap);
725 * Release a reference on a keymap, and possibly free it.
727 * @memberof xkb_keymap
730 xkb_keymap_unref(struct xkb_keymap *keymap);
732 /* See xkb_keymap_get_as_string(). */
733 #define XKB_KEYMAP_USE_ORIGINAL_FORMAT ((enum xkb_keymap_format) -1)
736 * Get the compiled keymap as a string.
738 * @param keymap The keymap to get as a string.
739 * @param format The keymap format to use for the string. You can pass
740 * in the special value XKB_KEYMAP_USE_ORIGINAL_FORMAT to use the format
741 * from which the keymap was originally created.
743 * @returns The keymap as a NUL-terminated string, or NULL if unsuccessful.
745 * The returned string may be fed back into xkb_map_new_from_string() to get
746 * the exact same keymap (possibly in another process, etc.).
748 * The returned string is dynamically allocated and should be freed by the
751 * @memberof xkb_keymap
754 xkb_keymap_get_as_string(struct xkb_keymap *keymap,
755 enum xkb_keymap_format format);
760 * @defgroup components Keymap Components
761 * Enumeration of state components in a keymap.
767 * Get the number of modifiers in the keymap.
769 * @sa xkb_mod_index_t
770 * @memberof xkb_keymap
773 xkb_keymap_num_mods(struct xkb_keymap *keymap);
776 * Get the name of a modifier by index.
778 * @returns The name. If the index is invalid, returns NULL.
780 * @sa xkb_mod_index_t
781 * @memberof xkb_keymap
784 xkb_keymap_mod_get_name(struct xkb_keymap *keymap, xkb_mod_index_t idx);
787 * Get the index of a modifier by name.
789 * @returns The index. If no modifier with this name exists, returns
792 * @sa xkb_mod_index_t
793 * @memberof xkb_keymap
796 xkb_keymap_mod_get_index(struct xkb_keymap *keymap, const char *name);
799 * Get the number of layouts in the keymap.
801 * @sa xkb_layout_index_t xkb_rule_names xkb_keymap_num_layouts_for_key()
802 * @memberof xkb_keymap
805 xkb_keymap_num_layouts(struct xkb_keymap *keymap);
808 * Get the name of a layout by index.
810 * @returns The name. If the index is invalid, or the layout does not have
811 * a name, returns NULL.
813 * @sa xkb_layout_index_t
814 * @memberof xkb_keymap
817 xkb_keymap_layout_get_name(struct xkb_keymap *keymap, xkb_layout_index_t idx);
820 * Get the index of a layout by name.
822 * @returns The index. If no layout exists with this name, returns
823 * XKB_LAYOUT_INVALID. If more than one layout in the keymap has this name,
824 * returns the lowest index among them.
826 * @memberof xkb_keymap
829 xkb_keymap_layout_get_index(struct xkb_keymap *keymap, const char *name);
832 * Get the number of layouts for a specific key.
834 * This number can be different from xkb_keymap_num_layouts(), but is always
835 * smaller. It is the appropriate value to use when iterating over the
838 * @sa xkb_layout_index_t
839 * @memberof xkb_keymap
842 xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key);
845 * Get the number of shift levels of a specific key and layout.
847 * @sa xkb_level_index_t
848 * @memberof xkb_keymap
851 xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key,
852 xkb_layout_index_t layout);
855 * Get the number of LEDs in a keymap.
857 * @warning The range [ 0...xkb_keymap_num_leds() ) includes all of the LEDs
858 * in the keymap, but may also contain inactive LEDs. When iterating over
859 * this range, you need the handle this case when calling functions such as
860 * xkb_keymap_led_get_name() or xkb_state_led_index_is_active().
862 * @sa xkb_led_index_t
863 * @memberof xkb_keymap
866 xkb_keymap_num_leds(struct xkb_keymap *keymap);
869 * Get the name of a LED by index.
871 * @returns The name. If the index is invalid, returns NULL.
873 * @memberof xkb_keymap
876 xkb_keymap_led_get_name(struct xkb_keymap *keymap, xkb_led_index_t idx);
879 * Get the index of a LED by name.
881 * @returns The index. If no LED with this name exists, returns
884 * @memberof xkb_keymap
887 xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name);
890 * Determine whether a key should repeat or not.
892 * A keymap may specify different repeat behaviors for different keys.
893 * Most keys should generally exhibit repeat behavior; for example, holding
894 * the 'a' key down in a text editor should normally insert a single 'a'
895 * character every few milliseconds, until the key is released. However,
896 * there are keys which should not or do not need to be repeated. For
897 * example, repeating modifier keys such as Left/Right Shift or Caps Lock
898 * is not generally useful or desired.
900 * @returns 1 if the key should repeat, 0 otherwise.
902 * @memberof xkb_keymap
905 xkb_keymap_key_repeats(struct xkb_keymap *keymap, xkb_keycode_t key);
910 * @defgroup state Keyboard State
911 * Creating, destroying and manipulating keyboard state objects.
917 * Create a new keyboard state object for a keymap.
919 * @param keymap The keymap for which to create the state.
921 * @returns A new keyboard state object, or NULL on failure.
923 * @memberof xkb_state
926 xkb_state_new(struct xkb_keymap *keymap);
929 * Take a new reference on a keyboard state object.
931 * @returns The passed in object.
933 * @memberof xkb_state
936 xkb_state_ref(struct xkb_state *state);
939 * Release a reference on a keybaord state object, and possibly free it.
941 * @memberof xkb_state
944 xkb_state_unref(struct xkb_state *state);
947 * Get the keymap from which a keyboard state object was created.
949 * @returns The keymap which was used in xkb_state_new() to create this
952 * This function does not take a new reference on the keymap; you must
953 * explicitly reference it yourself if you plan to use it beyond the
954 * lifetime of the state.
956 * @memberof xkb_state
959 xkb_state_get_keymap(struct xkb_state *state);
961 /** Specifies the direction of the key (press / release). */
962 enum xkb_key_direction {
963 XKB_KEY_UP, /**< The key was released. */
964 XKB_KEY_DOWN, /**< The key was pressed. */
968 * Update the keyboard state to reflect a given key being pressed or
973 * @memberof xkb_state
976 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
977 enum xkb_key_direction direction);
980 * Get the keysyms obtained from pressing a particular key in a given
983 * Get the keysyms for a key according to the current active layout,
984 * modifiers and shift level for the key, as determined by a keyboard
987 * @param[in] state The keyboard state object.
988 * @param[in] key The keycode of the key.
989 * @param[out] syms_out An immutible array of keysyms corresponding the
990 * key in the given keyboard state.
992 * As an extension to XKB, this function can return more than one keysym.
993 * If you do not want to handle this case, you can use
994 * xkb_state_key_get_one_sym().
996 * @returns The number of keysyms in the syms_out array. If no keysyms
997 * are produced by the key in the given keyboard state, returns 0 and sets
1000 * @memberof xkb_state
1003 xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
1004 const xkb_keysym_t **syms_out);
1007 * Get the single keysym obtained from pressing a particular key in a
1008 * given keyboard state.
1010 * This function is similar to xkb_state_key_get_syms(), but with a
1011 * simplified interface for users which cannot or do not want to handle
1012 * the case where multiple keysyms are returned.
1014 * @returns The keysym. If the key does not have exactly one keysym,
1015 * returns XKB_KEY_NoSymbol
1017 * @sa xkb_state_key_get_syms()
1018 * @memberof xkb_state
1021 xkb_state_key_get_one_sym(struct xkb_state *state, xkb_keycode_t key);
1024 * Get the effective layout index for a key in a given keyboard state.
1026 * @returns The layout index for the key in the given keyboard state. If
1027 * the given keycode is invalid, or if the key is not included in any
1028 * layout at all, returns XKB_LAYOUT_INVALID.
1030 * @invariant If the returned layout is valid, the following always holds:
1032 * xkb_state_key_get_layout(state, key) < xkb_keymap_num_layouts_for_key(keymap, key)
1035 * @memberof xkb_state
1038 xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t key);
1041 * Get the effective shift level for a key in a given keyboard state and
1044 * @param state The keyboard state.
1045 * @param key The keycode of the key.
1046 * @param layout The layout for which to get the shift level. This must be
1048 * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
1049 * usually it would be:
1050 * @code xkb_state_key_get_layout(state, key) @endcode
1052 * @return The shift level index. If the key or layout are invalid,
1053 * returns XKB_LEVEL_INVALID.
1055 * @invariant If the returned level is valid, the following always holds:
1057 * xkb_state_key_get_level(state, key, layout) < xkb_keymap_num_levels_for_key(keymap, key, layout)
1060 * @memberof xkb_state
1063 xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key,
1064 xkb_layout_index_t layout);
1067 * Get the keysyms obtained from pressing a key in a given layout and
1070 * This function is like xkb_state_key_get_syms(), only the layout and
1071 * shift level are not derived from the keyboard state but are instead
1072 * specified explicitly.
1074 * @param[in] keymap The keymap.
1075 * @param[in] key The keycode of the key.
1076 * @param[in] layout The layout for which to get the keysyms. This must
1078 * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
1079 * Usually it would be:
1080 * @code xkb_state_key_get_layout(state, key) @endcode
1081 * @param[in] level The shift level in the layout for which to get the
1082 * keysyms. This must be smaller than:
1083 * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
1084 * usually it would be:
1085 * @code xkb_state_key_get_level(state, key, layout) @endcode.
1086 * @param[out] syms_out An immutible array of keysyms corresponding the
1087 * key in the given layout and shift level.
1089 * @returns The number of keysyms in the syms_out array. If no keysyms
1090 * are produced by the key in the given layout and shift level, returns 0
1091 * and sets syms_out to NULL.
1093 * @sa xkb_state_key_get_syms()
1094 * @memberof xkb_keymap
1097 xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap,
1099 xkb_layout_index_t layout,
1100 xkb_level_index_t level,
1101 const xkb_keysym_t **syms_out);
1104 * Modifier and layout types for state objects. This enum is bitmaskable,
1105 * e.g. (XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED) is valid to
1106 * exclude locked modifiers.
1108 * In XKB, the DEPRESSED states are also known as 'base'.
1110 enum xkb_state_component {
1111 /** Depressed modifiers, i.e. a key is physically holding them. */
1112 XKB_STATE_MODS_DEPRESSED = (1 << 0),
1113 /** Latched modifiers, i.e. will be unset after the next non-modifier
1115 XKB_STATE_MODS_LATCHED = (1 << 1),
1116 /** Locked modifiers, i.e. will be unset after the key provoking the
1117 * lock has been pressed again. */
1118 XKB_STATE_MODS_LOCKED = (1 << 2),
1119 /** Effective modifiers, i.e. currently active and affect key
1120 * processing (derived from the other state components). */
1121 XKB_STATE_MODS_EFFECTIVE = (1 << 3),
1122 /** Depressed layout, i.e. a key is physically holding it. */
1123 XKB_STATE_LAYOUT_DEPRESSED = (1 << 4),
1124 /** Latched layout, i.e. will be unset after the next non-modifier
1126 XKB_STATE_LAYOUT_LATCHED = (1 << 5),
1127 /** Locked layout, i.e. will be unset after the key provoking the lock
1128 * has been pressed again. */
1129 XKB_STATE_LAYOUT_LOCKED = (1 << 6),
1130 /** Effective layout, i.e. currently active and affects key processing
1131 * (derived from the other state components). */
1132 XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7),
1133 /** LEDs (derived from the other state components). */
1134 XKB_STATE_LEDS = (1 << 8),
1138 * Match flags for xkb_state_mod_indices_are_active and
1139 * xkb_state_mod_names_are_active, specifying how the conditions for a
1140 * successful match. XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with
1143 enum xkb_state_match {
1144 /** Returns true if any of the modifiers are active. */
1145 XKB_STATE_MATCH_ANY = (1 << 0),
1146 /** Returns true if all of the modifiers are active. */
1147 XKB_STATE_MATCH_ALL = (1 << 1),
1148 /** Makes matching non-exclusive, i.e. will not return false if a
1149 * modifier not specified in the arguments is active. */
1150 XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16),
1154 * Update a state object from a set of explicit masks.
1156 * This entrypoint is really only for window systems and the like, where a
1157 * master process holds an xkb_state, then serializes it over a wire
1158 * protocol, and clients then use the serialization to feed in to their own
1161 * All parameters must always be passed, or the resulting state may be
1164 * The serialization is lossy and will not survive round trips; it must only
1165 * be used to feed slave state objects, and must not be used to update the
1168 * Please do not use this unless you fit the description above.
1170 * @memberof xkb_state
1173 xkb_state_update_mask(struct xkb_state *state, xkb_mod_mask_t base_mods,
1174 xkb_mod_mask_t latched_mods, xkb_mod_mask_t locked_mods,
1175 xkb_layout_index_t base_layout,
1176 xkb_layout_index_t latched_layout,
1177 xkb_layout_index_t locked_layout);
1180 * The counterpart to xkb_state_update_mask for modifiers, to be used on
1181 * the server side of serialization.
1183 * @param state The keyboard state.
1184 * @param components A mask of the modifier state components to serialize.
1185 * State components other than XKB_STATE_MODS_* are ignored.
1186 * If XKB_STATE_MODS_EFFECTIVE is included, all other state components are
1189 * @returns A xkb_mod_mask_t representing the given components of the
1192 * This function should not be used in regular clients; please use the
1193 * xkb_state_mod_*_is_active API instead.
1195 * @memberof xkb_state
1198 xkb_state_serialize_mods(struct xkb_state *state,
1199 enum xkb_state_component components);
1202 * The counterpart to xkb_state_update_mask for layouts, to be used on
1203 * the server side of serialization.
1205 * @param state The keyboard state.
1206 * @param components A mask of the layout state components to serialize.
1207 * State components other than XKB_STATE_LAYOUT_* are ignored.
1208 * If XKB_STATE_LAYOUT_EFFECTIVE is included, all other state components are
1211 * @returns A xkb_layout_mask_t representing the given components of the
1214 * This function should not be used in regular clients; please use the
1215 * xkb_state_layout_*_is_active API instead.
1217 * @memberof xkb_state
1220 xkb_state_serialize_layout(struct xkb_state *state,
1221 enum xkb_state_component components);
1224 * Test whether a modifier is active in a given keyboard state by name.
1226 * @returns 1 if the modifier is active, 0 if it is not. If the modifier
1227 * name does not exist in the keymap, returns -1.
1229 * @memberof xkb_state
1232 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
1233 enum xkb_state_component type);
1236 * Test whether a set of modifiers are active in a given keyboard state by
1239 * @param state The keyboard state.
1240 * @param type The component of the state against which to match the
1242 * @param match The manner by which to match the state against the
1244 * @param ... The set of of modifier names to test, terminated by a NULL
1245 * argument (sentinel).
1247 * @returns 1 if the modifiers are active, 0 if they are not. If any of
1248 * the modifier names do not exist in the keymap, returns -1.
1250 * @memberof xkb_state
1253 xkb_state_mod_names_are_active(struct xkb_state *state,
1254 enum xkb_state_component type,
1255 enum xkb_state_match match,
1259 * Test whether a modifier is active in a given keyboard state by index.
1261 * @returns 1 if the modifier is active, 0 if it is not. If the modifier
1262 * index is invalid in the keymap, returns -1.
1264 * @memberof xkb_state
1267 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
1268 enum xkb_state_component type);
1271 * Test whether a set of modifiers are active in a given keyboard state by
1274 * @param state The keyboard state.
1275 * @param type The component of the state against which to match the
1277 * @param match The manner by which to match the state against the
1279 * @param ... The set of of modifier indexes to test, terminated by a
1280 * XKB_MOD_INVALID argument (sentinel).
1282 * @returns 1 if the modifiers are active, 0 if they are not. If any of
1283 * the modifier indexes are invalid in the keymap, returns -1.
1285 * @memberof xkb_state
1288 xkb_state_mod_indices_are_active(struct xkb_state *state,
1289 enum xkb_state_component type,
1290 enum xkb_state_match match,
1294 * Test whether a modifier is consumed by keyboard state translation for
1297 * Some functions, like xkb_state_key_get_syms(), look at the state of
1298 * the modifiers in the keymap and derive from it the correct shift level
1299 * to use for the key. For example, in a US layout, pressing the key
1300 * labeled <A> while the Shift modifier is active, generates the keysym 'A'.
1301 * In this case, the Shift modifier is said to be consumed. However, the
1302 * Num Lock modifier does not affect this translation at all, even if it
1303 * active, so it is not consumed by this translation.
1305 * It may be desireable for some application to not reuse consumed modifiers
1306 * for further processing, e.g. for hotkeys or keyboard shortcuts.
1308 * @returns 1 if the modifier is consumed, 0 if it is not. If the modifier
1309 * index is not valid in the keymap, returns -1.
1311 * @sa xkb_state_mod_mask_remove_consumend()
1312 * @memberof xkb_state
1315 xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key,
1316 xkb_mod_index_t idx);
1319 * Remove consumed modifiers from a modifier mask for a key.
1321 * Takes the given modifier mask, and removes all modifiers which are
1322 * consumed for that particular key (as in xkb_state_mod_index_is_consumed()).
1324 * @sa xkb_state_mod_index_is_consumed()
1325 * @memberof xkb_state
1328 xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t key,
1329 xkb_mod_mask_t mask);
1332 * Test whether a layout is active in a given keyboard state by name.
1334 * @returns 1 if the layout is active, 0 if it is not. If no layout with
1335 * this name exists in the keymap, return -1.
1337 * If multiple layouts in the keymap have this name, the one with the lowest
1340 * @sa xkb_layout_index_t
1341 * @memberof xkb_state
1344 xkb_state_layout_name_is_active(struct xkb_state *state, const char *name,
1345 enum xkb_state_component type);
1348 * Test whether a layout is active in a given keyboard state by index.
1350 * @returns 1 if the layout is active, 0 if it is not. If the layout index
1351 * is not valid in the keymap, returns -1.
1353 * @sa xkb_layout_index_t
1354 * @memberof xkb_state
1357 xkb_state_layout_index_is_active(struct xkb_state *state,
1358 xkb_layout_index_t idx,
1359 enum xkb_state_component type);
1362 * Test whether a LED is active in a given keyboard state by name.
1364 * @returns 1 if the LED is active, 0 if it not. If no LED with this name
1365 * exists in the keymap, returns -1.
1367 * @sa xkb_led_index_t
1368 * @memberof xkb_state
1371 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
1374 * Test whether a LED is active in a given keyboard state by index.
1376 * @returns 1 if the LED is active, 0 if it not. If the LED index is not
1377 * valid in the keymap, returns -1.
1379 * @sa xkb_led_index_t
1380 * @memberof xkb_state
1383 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
1387 /* Leave this include last, so it can pick up our types, etc. */
1388 #include <xkbcommon/xkbcommon-compat.h>
1394 #endif /* _XKBCOMMON_H_ */