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:
156 * xkb_keycode_t keycode_A = KEY_A + 8;
159 * @sa xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11()
161 typedef uint32_t xkb_keycode_t;
164 * A number used to represent the symbols generated from a key on a keyboard.
166 * A key, represented by a keycode, may generate different symbols according
167 * to keyboard state. For example, on a QWERTY keyboard, pressing the key
168 * labled \<A\> generates the symbol 'a'. If the Shift key is held, it
169 * generates the symbol 'A'. If a different layout is used, say Greek,
170 * it generates the symbol 'α'. And so on.
172 * Each such symbol is represented by a keysym. Note that keysyms are
173 * somewhat more general, in that they can also represent some "function",
174 * such as "Left" or "Right" for the arrow keys. For more information,
176 * http://www.x.org/releases/X11R7.7/doc/xproto/x11protocol.html#keysym_encoding
178 * Specifically named keysyms can be found in the
179 * xkbcommon/xkbcommon-keysyms.h header file. Their name does not include
180 * the XKB_KEY_ prefix.
182 * Besides those, any Unicode/ISO 10646 character in the range U0100 to
183 * U10FFFF can be represented by a keysym value in the range 0x01000100 to
184 * 0x0110FFFF. The name of Unicode keysyms is "U<codepoint>", e.g. "UA1B2".
186 * The name of other unnamed keysyms is the hexadecimal representation of
187 * their value, e.g. "0xabcd1234".
189 * Keysym names are case-sensitive.
191 typedef uint32_t xkb_keysym_t;
194 * Index of a keyboard layout.
196 * The layout index is a state component which detemines which <em>keyboard
197 * layout</em> is active. These may be different alphabets, different key
200 * Layout indices are consecutive. The first layout has index 0.
202 * Each layout is not required to have a name, and the names are not
203 * guaranteed to be unique (though they are usually provided and unique).
204 * Therefore, it is not safe to use the name as a unique identifier for a
205 * layout. Layout names are case-sensitive.
207 * Layouts are also called "groups" by XKB.
209 * @sa xkb_keymap_num_layouts() xkb_keymap_num_layouts_for_key()
211 typedef uint32_t xkb_layout_index_t;
212 /** A mask of layout indices. */
213 typedef uint32_t xkb_layout_mask_t;
216 * Index of a shift level.
218 * Any key, in any layout, can have several <em>shift levels</em>. Each
219 * shift level can assign different keysyms to the key. The shift level
220 * to use is chosen according to the current keyboard state; for example,
221 * if no keys are pressed, the first level may be used; if the Left Shift
222 * key is pressed, the second; if Num Lock is pressed, the third; and
223 * many such combinations are possible (see xkb_mod_index_t).
225 * Level indices are consecutive. The first level has index 0.
227 typedef uint32_t xkb_level_index_t;
230 * Index of a modifier.
232 * A @e modifier is a state component which changes the way keys are
233 * interpreted. A keymap defines a set of modifiers, such as Alt, Shift,
234 * Num Lock or Meta, and specifies which keys may @e activate which
235 * modifiers (in a many-to-many relationship, i.e. a key can activate
236 * several modifiers, and a modifier may be activated by several keys.
237 * Different keymaps do this differently).
239 * When retrieving the keysyms for a key, the active modifier set is
240 * consulted; this detemines the correct shift level to use within the
241 * currently active layout (see xkb_level_index_t).
243 * Modifier indices are consecutive. The first modifier has index 0.
245 * Each modifier must have a name, and the names are unique. Therefore, it
246 * is safe to use the name as a unique identifier for a modifier. The names
247 * of some common modifiers are provided in the xkbcommon/xkbcommon-names.h
248 * header file. Modifier names are case-sensitive.
250 * @sa xkb_keymap_num_mods()
252 typedef uint32_t xkb_mod_index_t;
253 /** A mask of modifier indices. */
254 typedef uint32_t xkb_mod_mask_t;
257 * Index of a keyboard LED.
259 * LEDs are logical objects which may be @e active or @e inactive. They
260 * typically correspond to the lights on the keyboard. Their state is
261 * determined by the current keyboard state.
263 * LED indices are non-consecutive. The first LED has index 0.
265 * Each LED must have a name, and the names are unique. Therefore,
266 * it is safe to use the name as a unique identifier for a LED. The names
267 * of some common LEDs are provided in the xkbcommon/xkbcommon-names.h
268 * header file. LED names are case-sensitive.
270 * @warning A given keymap may specify an exact index for a given LED.
271 * Therefore, LED indexing is not necessarily sequential, as opposed to
272 * modifiers and layouts. This means that when iterating over the LEDs
273 * in a keymap using e.g. xkb_keymap_num_leds(), some indices might be
274 * invalid. Given such an index, functions like xkb_keymap_led_get_name()
275 * will return NULL, and xkb_state_led_index_is_active() will return -1.
277 * LEDs are also called "indicators" by XKB.
279 * @sa xkb_keymap_num_leds()
281 typedef uint32_t xkb_led_index_t;
282 /** A mask of LED indices. */
283 typedef uint32_t xkb_led_mask_t;
285 #define XKB_KEYCODE_INVALID (0xffffffff)
286 #define XKB_LAYOUT_INVALID (0xffffffff)
287 #define XKB_LEVEL_INVALID (0xffffffff)
288 #define XKB_MOD_INVALID (0xffffffff)
289 #define XKB_LED_INVALID (0xffffffff)
291 #define XKB_KEYCODE_MAX (0xffffffff - 1)
294 * Test whether a value is a valid extended keycode.
297 #define xkb_keycode_is_legal_ext(key) (key <= XKB_KEYCODE_MAX)
300 * Test whether a value is a valid X11 keycode.
303 #define xkb_keycode_is_legal_x11(key) (key >= 8 && key <= 255)
306 * Names to compile a keymap with, also known as RMLVO.
308 * These names together are the primary identifier for a keymap.
309 * If any of the members is NULL or an empty string (""), a default value is
310 * used. It is recommended to use the system default by passing NULL for
311 * unspecified values, instead of providing your own defaults.
313 struct xkb_rule_names {
314 /** The rules file to use. The rules file describes how to interpret
315 * the values of the model, layout, variant and options fields. */
317 /** The keyboard model by which to interpret keycodes and LEDs. */
319 /** A comma separated list of layouts (languages) to include in the
322 /** A comma separated list of variants, one per layout, which may
323 * modify or augment the respective layout in various ways. */
325 /** A comma separated list of options, through which the user specifies
326 * non-layout related preferences, like which key combinations are used
327 * for switching layouts, or which key is the Compose key. */
332 * @defgroup keysyms Keysyms
333 * Utility functions related to keysyms.
339 * Get the name of a keysym.
341 * For a description of how keysyms are named, see @ref xkb_keysym_t.
343 * @param[in] keysym The keysym.
344 * @param[out] buffer A string buffer to write the name into.
345 * @param[in] size Size of the buffer.
347 * @warning If the buffer passed is too small, the string is truncated
348 * (though still NUL-terminated); a size of at least 64 bytes is recommended.
350 * @returns The number of bytes in the name, excluding the NUL byte. If
351 * the keysym is invalid, returns -1.
353 * You may check if truncation has occurred by comparing the return value
354 * with the length of buffer, similarly to the snprintf(3) function.
359 xkb_keysym_get_name(xkb_keysym_t keysym, char *buffer, size_t size);
361 /** Flags for xkb_keysym_from_name(). */
362 enum xkb_keysym_flags {
363 /** Do not apply any flags. */
364 XKB_KEYSYM_NO_FLAGS = 0,
365 /** Find keysym by case-insensitive search. */
366 XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0)
370 * Get a keysym from its name.
372 * @param name The name of a keysym. See remarks in xkb_keysym_get_name();
373 * this function will accept any name returned by that function.
374 * @param flags A set of flags controlling how the search is done. If
375 * invalid flags are passed, this will fail with XKB_KEY_NoSymbol.
377 * If you use the XKB_KEYSYM_CASE_INSENSITIVE flag and two keysym names
378 * differ only by case, then the lower-case keysym is returned. For
379 * instance, for KEY_a and KEY_A, this function would return KEY_a for the
380 * case-insensitive search. If this functionality is needed, it is
381 * recommended to first call this function without this flag; and if that
382 * fails, only then to try with this flag, while possibly warning the user
383 * he had misspelled the name, and might get wrong results.
385 * @returns The keysym. If the name is invalid, returns XKB_KEY_NoSymbol.
390 xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags);
393 * Get the Unicode/UTF-8 representation of a keysym.
395 * @param[in] keysym The keysym.
396 * @param[out] buffer A buffer to write the UTF-8 string into.
397 * @param[in] size The size of buffer. Must be at least 7.
399 * @returns The number of bytes written to the buffer (including the
400 * terminating byte). If the keysym does not have a Unicode
401 * representation, returns 0. If the buffer is too small, returns -1.
404 xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size);
407 * Get the Unicode/UTF-32 representation of a keysym.
409 * @returns The Unicode/UTF-32 representation of keysym, which is also
410 * compatible with UCS-4. If the keysym does not have a Unicode
411 * representation, returns 0.
414 xkb_keysym_to_utf32(xkb_keysym_t keysym);
419 * @defgroup context Library Context
420 * Creating, destroying and using library contexts.
422 * Every keymap compilation request must have a context associated with
423 * it. The context keeps around state such as the include path.
428 /** Flags for context creation. */
429 enum xkb_context_flags {
430 /** Do not apply any context flags. */
431 XKB_CONTEXT_NO_FLAGS = 0,
432 /** Create this context with an empty include path. */
433 XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
434 /** Don't take RMLVO names from the environment. */
435 XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1),
439 * Create a new context.
441 * @param flags Optional flags for the context, or 0.
443 * @returns A new context, or NULL on failure.
445 * The user may set some environment variables to affect default values in
446 * the context. See e.g. xkb_context_set_log_level() and
447 * xkb_context_set_log_verbosity().
449 * @memberof xkb_context
452 xkb_context_new(enum xkb_context_flags flags);
455 * Take a new reference on a context.
457 * @returns The passed in context.
459 * @memberof xkb_context
462 xkb_context_ref(struct xkb_context *context);
465 * Release a reference on a context, and possibly free it.
467 * @param context The context. If it is NULL, this function does nothing.
469 * @memberof xkb_context
472 xkb_context_unref(struct xkb_context *context);
475 * Store custom user data in the context.
477 * This may be useful in conjunction with xkb_context_set_log_fn() or other
480 * @memberof xkb_context
483 xkb_context_set_user_data(struct xkb_context *context, void *user_data);
486 * Retrieves stored user data from the context.
488 * @returns The stored user data. If the user data wasn't set, or the
489 * passed in context is NULL, returns NULL.
491 * This may be useful to access private user data from callbacks like a
492 * custom logging function.
494 * @memberof xkb_context
497 xkb_context_get_user_data(struct xkb_context *context);
502 * @defgroup include-path Include Paths
503 * Manipulating the include paths in a context.
505 * The include paths are the file-system paths that are searched when an
506 * include statement is encountered during keymap compilation.
507 * In most cases, the default include paths are sufficient.
513 * Append a new entry to the context's include path.
515 * @returns 1 on success, or 0 if the include path could not be added or is
518 * @memberof xkb_context
521 xkb_context_include_path_append(struct xkb_context *context, const char *path);
524 * Append the default include paths to the context's include path.
526 * @returns 1 on success, or 0 if the primary include path could not be added.
528 * @memberof xkb_context
531 xkb_context_include_path_append_default(struct xkb_context *context);
534 * Reset the context's include path to the default.
536 * Removes all entries from the context's include path, and inserts the
539 * @returns 1 on success, or 0 if the primary include path could not be added.
541 * @memberof xkb_context
544 xkb_context_include_path_reset_defaults(struct xkb_context *context);
547 * Remove all entries from the context's include path.
549 * @memberof xkb_context
552 xkb_context_include_path_clear(struct xkb_context *context);
555 * Get the number of paths in the context's include path.
557 * @memberof xkb_context
560 xkb_context_num_include_paths(struct xkb_context *context);
563 * Get a specific include path from the context's include path.
565 * @returns The include path at the specified index. If the index is
566 * invalid, returns NULL.
568 * @memberof xkb_context
571 xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
576 * @defgroup logging Logging Handling
577 * Manipulating how logging from this library is handled.
582 /** Specifies a logging level. */
584 XKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
585 XKB_LOG_LEVEL_ERROR = 20, /**< Log all errors. */
586 XKB_LOG_LEVEL_WARNING = 30, /**< Log warnings and errors. */
587 XKB_LOG_LEVEL_INFO = 40, /**< Log information, warnings, and errors. */
588 XKB_LOG_LEVEL_DEBUG = 50 /**< Log everything. */
592 * Set the current logging level.
594 * @param context The context in which to set the logging level.
595 * @param level The logging level to use. Only messages from this level
596 * and below will be logged.
598 * The default level is XKB_LOG_LEVEL_ERROR. The environment variable
599 * XKB_LOG_LEVEL, if set in the time the context was created, overrides the
600 * default value. It may be specified as a level number or name.
602 * @memberof xkb_context
605 xkb_context_set_log_level(struct xkb_context *context,
606 enum xkb_log_level level);
609 * Get the current logging level.
611 * @memberof xkb_context
614 xkb_context_get_log_level(struct xkb_context *context);
617 * Sets the current logging verbosity.
619 * The library can generate a number of warnings which are not helpful to
620 * ordinary users of the library. The verbosity may be increased if more
621 * information is desired (e.g. when developing a new keymap).
623 * The default verbosity is 0. The environment variable XKB_LOG_VERBOSITY,
624 * if set in the time the context was created, overrides the default value.
626 * @param context The context in which to use the set verbosity.
627 * @param verbosity The verbosity to use. Currently used values are
628 * 1 to 10, higher values being more verbose. 0 would result in no verbose
629 * messages being logged.
631 * Most verbose messages are of level XKB_LOG_LEVEL_WARNING or lower.
633 * @memberof xkb_context
636 xkb_context_set_log_verbosity(struct xkb_context *context, int verbosity);
639 * Get the current logging verbosity of the context.
641 * @memberof xkb_context
644 xkb_context_get_log_verbosity(struct xkb_context *context);
647 * Set a custom function to handle logging messages.
649 * @param context The context in which to use the set logging function.
650 * @param log_fn The function that will be called for logging messages.
651 * Passing NULL restores the default function, which logs to stderr.
653 * By default, log messages from this library are printed to stderr. This
654 * function allows you to replace the default behavior with a custom
655 * handler. The handler is only called with messages which match the
656 * current logging level and verbosity settings for the context.
657 * level is the logging level of the message. @a format and @a args are
658 * the same as in the vprintf(3) function.
660 * You may use xkb_context_set_user_data() on the context, and then call
661 * xkb_context_get_user_data() from within the logging function to provide
662 * it with additional private context.
664 * @memberof xkb_context
667 xkb_context_set_log_fn(struct xkb_context *context,
668 void (*log_fn)(struct xkb_context *context,
669 enum xkb_log_level level,
670 const char *format, va_list args));
675 * @defgroup keymap Keymap Creation
676 * Creating and destroying keymaps.
681 /** Flags for keymap compilation. */
682 enum xkb_keymap_compile_flags {
683 /** Do not apply any flags. */
684 XKB_KEYMAP_COMPILE_NO_FLAGS = 0
688 * Create a keymap from RMLVO names.
690 * The primary keymap entry point: creates a new XKB keymap from a set of
691 * RMLVO (Rules + Model + Layouts + Variants + Options) names.
693 * You should almost certainly be using this and nothing else to create
696 * @param context The context in which to create the keymap.
697 * @param names The RMLVO names to use. In xkbcommon versions prior
698 * to 0.2.1, this field must be non-NULL. In later
699 * versions, passing NULL will use the default keymap.
700 * @param flags Optional flags for the keymap, or 0.
702 * @returns A keymap compiled according to the RMLVO names, or NULL if
703 * the compilation failed.
706 * @memberof xkb_keymap
709 xkb_keymap_new_from_names(struct xkb_context *context,
710 const struct xkb_rule_names *names,
711 enum xkb_keymap_compile_flags flags);
713 /** The possible keymap formats. */
714 enum xkb_keymap_format {
715 /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
716 XKB_KEYMAP_FORMAT_TEXT_V1 = 1
720 * Create a keymap from a keymap file.
722 * @param context The context in which to create the keymap.
723 * @param file The keymap file to compile.
724 * @param format The text format of the keymap file to compile.
725 * @param flags Optional flags for the keymap, or 0.
727 * @returns A keymap compiled from the given XKB keymap file, or NULL if
728 * the compilation failed.
730 * The file must contain a complete keymap. For example, in the
731 * XKB_KEYMAP_FORMAT_TEXT_V1 format, this means the file must contain one
732 * top level '%xkb_keymap' section, which in turn contains other required
735 * @memberof xkb_keymap
738 xkb_keymap_new_from_file(struct xkb_context *context, FILE *file,
739 enum xkb_keymap_format format,
740 enum xkb_keymap_compile_flags flags);
743 * Create a keymap from a keymap string.
745 * This is just like xkb_keymap_new_from_file(), but instead of a file, gets
746 * the keymap as one enormous string.
748 * @see xkb_keymap_new_from_string()
749 * @memberof xkb_keymap
752 xkb_keymap_new_from_string(struct xkb_context *context, const char *string,
753 enum xkb_keymap_format format,
754 enum xkb_keymap_compile_flags flags);
757 * Create a keymap from a memory buffer.
759 * This is just like xkb_keymap_new_from_string(), but takes a length argument
760 * so the input string does not have to be zero-terminated.
762 * @see xkb_keymap_new_from_string()
763 * @memberof xkb_keymap
766 xkb_keymap_new_from_buffer(struct xkb_context *context, const char *buffer,
767 size_t length, enum xkb_keymap_format format,
768 enum xkb_keymap_compile_flags flags);
771 * Take a new reference on a keymap.
773 * @returns The passed in keymap.
775 * @memberof xkb_keymap
778 xkb_keymap_ref(struct xkb_keymap *keymap);
781 * Release a reference on a keymap, and possibly free it.
783 * @param keymap The keymap. If it is NULL, this function does nothing.
785 * @memberof xkb_keymap
788 xkb_keymap_unref(struct xkb_keymap *keymap);
791 * Get the keymap as a string in the format from which it was created.
792 * @sa xkb_keymap_get_as_string()
794 #define XKB_KEYMAP_USE_ORIGINAL_FORMAT ((enum xkb_keymap_format) -1)
797 * Get the compiled keymap as a string.
799 * @param keymap The keymap to get as a string.
800 * @param format The keymap format to use for the string. You can pass
801 * in the special value XKB_KEYMAP_USE_ORIGINAL_FORMAT to use the format
802 * from which the keymap was originally created.
804 * @returns The keymap as a NUL-terminated string, or NULL if unsuccessful.
806 * The returned string may be fed back into xkb_map_new_from_string() to get
807 * the exact same keymap (possibly in another process, etc.).
809 * The returned string is dynamically allocated and should be freed by the
812 * @memberof xkb_keymap
815 xkb_keymap_get_as_string(struct xkb_keymap *keymap,
816 enum xkb_keymap_format format);
821 * @defgroup components Keymap Components
822 * Enumeration of state components in a keymap.
828 * Get the minimum keycode in the keymap.
831 * @memberof xkb_keymap
834 xkb_keymap_min_keycode(struct xkb_keymap *keymap);
837 * Get the maximum keycode in the keymap.
840 * @memberof xkb_keymap
843 xkb_keymap_max_keycode(struct xkb_keymap *keymap);
846 * The iterator used by xkb_keymap_key_for_each().
848 * @sa xkb_keymap_key_for_each
849 * @memberof xkb_keymap
852 (*xkb_keymap_key_iter_t)(struct xkb_keymap *keymap, xkb_keycode_t key,
856 * Run a specified function for every valid keycode in the keymap. If a
857 * keymap is sparse, this function may be called fewer than
858 * (max_keycode - min_keycode + 1) times.
860 * @sa xkb_keymap_min_keycode() xkb_keymap_max_keycode() xkb_keycode_t
861 * @memberof xkb_keymap
864 xkb_keymap_key_for_each(struct xkb_keymap *keymap, xkb_keymap_key_iter_t iter,
868 * Get the number of modifiers in the keymap.
870 * @sa xkb_mod_index_t
871 * @memberof xkb_keymap
874 xkb_keymap_num_mods(struct xkb_keymap *keymap);
877 * Get the name of a modifier by index.
879 * @returns The name. If the index is invalid, returns NULL.
881 * @sa xkb_mod_index_t
882 * @memberof xkb_keymap
885 xkb_keymap_mod_get_name(struct xkb_keymap *keymap, xkb_mod_index_t idx);
888 * Get the index of a modifier by name.
890 * @returns The index. If no modifier with this name exists, returns
893 * @sa xkb_mod_index_t
894 * @memberof xkb_keymap
897 xkb_keymap_mod_get_index(struct xkb_keymap *keymap, const char *name);
900 * Get the number of layouts in the keymap.
902 * @sa xkb_layout_index_t xkb_rule_names xkb_keymap_num_layouts_for_key()
903 * @memberof xkb_keymap
906 xkb_keymap_num_layouts(struct xkb_keymap *keymap);
909 * Get the name of a layout by index.
911 * @returns The name. If the index is invalid, or the layout does not have
912 * a name, returns NULL.
914 * @sa xkb_layout_index_t
915 * @memberof xkb_keymap
918 xkb_keymap_layout_get_name(struct xkb_keymap *keymap, xkb_layout_index_t idx);
921 * Get the index of a layout by name.
923 * @returns The index. If no layout exists with this name, returns
924 * XKB_LAYOUT_INVALID. If more than one layout in the keymap has this name,
925 * returns the lowest index among them.
927 * @memberof xkb_keymap
930 xkb_keymap_layout_get_index(struct xkb_keymap *keymap, const char *name);
933 * Get the number of layouts for a specific key.
935 * This number can be different from xkb_keymap_num_layouts(), but is always
936 * smaller. It is the appropriate value to use when iterating over the
939 * @sa xkb_layout_index_t
940 * @memberof xkb_keymap
943 xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key);
946 * Get the number of shift levels for a specific key and layout.
948 * If @c layout is out of range for this key (that is, larger or equal to
949 * the value returned by xkb_keymap_num_layouts_for_key()), it is brought
950 * back into range in a manner consistent with xkb_state_key_get_layout().
952 * @sa xkb_level_index_t
953 * @memberof xkb_keymap
956 xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key,
957 xkb_layout_index_t layout);
960 * Get the keysyms obtained from pressing a key in a given layout and
963 * This function is like xkb_state_key_get_syms(), only the layout and
964 * shift level are not derived from the keyboard state but are instead
965 * specified explicitly.
967 * @param[in] keymap The keymap.
968 * @param[in] key The keycode of the key.
969 * @param[in] layout The layout for which to get the keysyms.
970 * @param[in] level The shift level in the layout for which to get the
971 * keysyms. This must be smaller than:
972 * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
973 * @param[out] syms_out An immutible array of keysyms corresponding to the
974 * key in the given layout and shift level.
976 * If @c layout is out of range for this key (that is, larger or equal to
977 * the value returned by xkb_keymap_num_layouts_for_key()), it is brought
978 * back into range in a manner consistent with xkb_state_key_get_layout().
980 * @returns The number of keysyms in the syms_out array. If no keysyms
981 * are produced by the key in the given layout and shift level, returns 0
982 * and sets syms_out to NULL.
984 * @sa xkb_state_key_get_syms()
985 * @memberof xkb_keymap
988 xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap,
990 xkb_layout_index_t layout,
991 xkb_level_index_t level,
992 const xkb_keysym_t **syms_out);
995 * Get the number of LEDs in the keymap.
997 * @warning The range [ 0...xkb_keymap_num_leds() ) includes all of the LEDs
998 * in the keymap, but may also contain inactive LEDs. When iterating over
999 * this range, you need the handle this case when calling functions such as
1000 * xkb_keymap_led_get_name() or xkb_state_led_index_is_active().
1002 * @sa xkb_led_index_t
1003 * @memberof xkb_keymap
1006 xkb_keymap_num_leds(struct xkb_keymap *keymap);
1009 * Get the name of a LED by index.
1011 * @returns The name. If the index is invalid, returns NULL.
1013 * @memberof xkb_keymap
1016 xkb_keymap_led_get_name(struct xkb_keymap *keymap, xkb_led_index_t idx);
1019 * Get the index of a LED by name.
1021 * @returns The index. If no LED with this name exists, returns
1024 * @memberof xkb_keymap
1027 xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name);
1030 * Determine whether a key should repeat or not.
1032 * A keymap may specify different repeat behaviors for different keys.
1033 * Most keys should generally exhibit repeat behavior; for example, holding
1034 * the 'a' key down in a text editor should normally insert a single 'a'
1035 * character every few milliseconds, until the key is released. However,
1036 * there are keys which should not or do not need to be repeated. For
1037 * example, repeating modifier keys such as Left/Right Shift or Caps Lock
1038 * is not generally useful or desired.
1040 * @returns 1 if the key should repeat, 0 otherwise.
1042 * @memberof xkb_keymap
1045 xkb_keymap_key_repeats(struct xkb_keymap *keymap, xkb_keycode_t key);
1050 * @defgroup state Keyboard State
1051 * Creating, destroying and manipulating keyboard state objects.
1057 * Create a new keyboard state object.
1059 * @param keymap The keymap which the state will use.
1061 * @returns A new keyboard state object, or NULL on failure.
1063 * @memberof xkb_state
1066 xkb_state_new(struct xkb_keymap *keymap);
1069 * Take a new reference on a keyboard state object.
1071 * @returns The passed in object.
1073 * @memberof xkb_state
1076 xkb_state_ref(struct xkb_state *state);
1079 * Release a reference on a keybaord state object, and possibly free it.
1081 * @param state The state. If it is NULL, this function does nothing.
1083 * @memberof xkb_state
1086 xkb_state_unref(struct xkb_state *state);
1089 * Get the keymap which a keyboard state object is using.
1091 * @returns The keymap which was passed to xkb_state_new() when creating
1092 * this state object.
1094 * This function does not take a new reference on the keymap; you must
1095 * explicitly reference it yourself if you plan to use it beyond the
1096 * lifetime of the state.
1098 * @memberof xkb_state
1101 xkb_state_get_keymap(struct xkb_state *state);
1103 /** Specifies the direction of the key (press / release). */
1104 enum xkb_key_direction {
1105 XKB_KEY_UP, /**< The key was released. */
1106 XKB_KEY_DOWN /**< The key was pressed. */
1110 * Modifier and layout types for state objects. This enum is bitmaskable,
1111 * e.g. (XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED) is valid to
1112 * exclude locked modifiers.
1114 * In XKB, the DEPRESSED components are also known as 'base'.
1116 enum xkb_state_component {
1117 /** Depressed modifiers, i.e. a key is physically holding them. */
1118 XKB_STATE_MODS_DEPRESSED = (1 << 0),
1119 /** Latched modifiers, i.e. will be unset after the next non-modifier
1121 XKB_STATE_MODS_LATCHED = (1 << 1),
1122 /** Locked modifiers, i.e. will be unset after the key provoking the
1123 * lock has been pressed again. */
1124 XKB_STATE_MODS_LOCKED = (1 << 2),
1125 /** Effective modifiers, i.e. currently active and affect key
1126 * processing (derived from the other state components).
1127 * Use this unless you explictly care how the state came about. */
1128 XKB_STATE_MODS_EFFECTIVE = (1 << 3),
1129 /** Depressed layout, i.e. a key is physically holding it. */
1130 XKB_STATE_LAYOUT_DEPRESSED = (1 << 4),
1131 /** Latched layout, i.e. will be unset after the next non-modifier
1133 XKB_STATE_LAYOUT_LATCHED = (1 << 5),
1134 /** Locked layout, i.e. will be unset after the key provoking the lock
1135 * has been pressed again. */
1136 XKB_STATE_LAYOUT_LOCKED = (1 << 6),
1137 /** Effective layout, i.e. currently active and affects key processing
1138 * (derived from the other state components).
1139 * Use this unless you explictly care how the state came about. */
1140 XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7),
1141 /** LEDs (derived from the other state components). */
1142 XKB_STATE_LEDS = (1 << 8)
1146 * Update the keyboard state to reflect a given key being pressed or
1149 * This entry point is intended for programs which track the keyboard state
1150 * explictly (like an evdev client). If the state is serialized to you by
1151 * a master process (like a Wayland compositor) using functions like
1152 * xkb_state_serialize_mods(), you should use xkb_state_update_mask() instead.
1153 * The two functins should not generally be used together.
1155 * A series of calls to this function should be consistent; that is, a call
1156 * with XKB_KEY_DOWN for a key should be matched by an XKB_KEY_UP; if a key
1157 * is pressed twice, it should be released twice; etc. Otherwise (e.g. due
1158 * to missed input events), situations like "stuck modifiers" may occur.
1160 * @returns A mask of state components that have changed as a result of
1161 * the update. If nothing in the state has changed, returns 0.
1163 * @memberof xkb_state
1165 * @sa xkb_state_update_mask()
1167 enum xkb_state_component
1168 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
1169 enum xkb_key_direction direction);
1172 * Update a keyboard state from a set of explicit masks.
1174 * This entry point is intended for window systems and the like, where a
1175 * master process holds an xkb_state, then serializes it over a wire
1176 * protocol, and clients then use the serialization to feed in to their own
1179 * All parameters must always be passed, or the resulting state may be
1182 * The serialization is lossy and will not survive round trips; it must only
1183 * be used to feed slave state objects, and must not be used to update the
1186 * If you do not fit the description above, you should use
1187 * xkb_state_update_key() instead. The two functions should not generally be
1190 * @returns A mask of state components that have changed as a result of
1191 * the update. If nothing in the state has changed, returns 0.
1193 * @memberof xkb_state
1195 * @sa xkb_state_component
1196 * @sa xkb_state_update_key
1198 enum xkb_state_component
1199 xkb_state_update_mask(struct xkb_state *state,
1200 xkb_mod_mask_t depressed_mods,
1201 xkb_mod_mask_t latched_mods,
1202 xkb_mod_mask_t locked_mods,
1203 xkb_layout_index_t depressed_layout,
1204 xkb_layout_index_t latched_layout,
1205 xkb_layout_index_t locked_layout);
1208 * Get the keysyms obtained from pressing a particular key in a given
1211 * Get the keysyms for a key according to the current active layout,
1212 * modifiers and shift level for the key, as determined by a keyboard
1215 * @param[in] state The keyboard state object.
1216 * @param[in] key The keycode of the key.
1217 * @param[out] syms_out An immutable array of keysyms corresponding the
1218 * key in the given keyboard state.
1220 * As an extension to XKB, this function can return more than one keysym.
1221 * If you do not want to handle this case, you should use
1222 * xkb_state_key_get_one_sym(), which additionally performs transformations
1223 * which are specific to the one-keysym case.
1225 * @returns The number of keysyms in the syms_out array. If no keysyms
1226 * are produced by the key in the given keyboard state, returns 0 and sets
1229 * @memberof xkb_state
1232 xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
1233 const xkb_keysym_t **syms_out);
1236 * Get the single keysym obtained from pressing a particular key in a
1237 * given keyboard state.
1239 * This function is similar to xkb_state_key_get_syms(), but intended
1240 * for users which cannot or do not want to handle the case where
1241 * multiple keysyms are returned (in which case this function is
1244 * @returns The keysym. If the key does not have exactly one keysym,
1245 * returns XKB_KEY_NoSymbol
1247 * @sa xkb_state_key_get_syms()
1248 * @memberof xkb_state
1251 xkb_state_key_get_one_sym(struct xkb_state *state, xkb_keycode_t key);
1254 * Get the effective layout index for a key in a given keyboard state.
1256 * @returns The layout index for the key in the given keyboard state. If
1257 * the given keycode is invalid, or if the key is not included in any
1258 * layout at all, returns XKB_LAYOUT_INVALID.
1260 * @invariant If the returned layout is valid, the following always holds:
1262 * xkb_state_key_get_layout(state, key) < xkb_keymap_num_layouts_for_key(keymap, key)
1265 * @memberof xkb_state
1268 xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t key);
1271 * Get the effective shift level for a key in a given keyboard state and
1274 * @param state The keyboard state.
1275 * @param key The keycode of the key.
1276 * @param layout The layout for which to get the shift level. This must be
1278 * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
1279 * usually it would be:
1280 * @code xkb_state_key_get_layout(state, key) @endcode
1282 * @return The shift level index. If the key or layout are invalid,
1283 * returns XKB_LEVEL_INVALID.
1285 * @invariant If the returned level is valid, the following always holds:
1287 * xkb_state_key_get_level(state, key, layout) < xkb_keymap_num_levels_for_key(keymap, key, layout)
1290 * @memberof xkb_state
1293 xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key,
1294 xkb_layout_index_t layout);
1297 * Match flags for xkb_state_mod_indices_are_active and
1298 * xkb_state_mod_names_are_active, specifying how the conditions for a
1299 * successful match. XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with
1302 enum xkb_state_match {
1303 /** Returns true if any of the modifiers are active. */
1304 XKB_STATE_MATCH_ANY = (1 << 0),
1305 /** Returns true if all of the modifiers are active. */
1306 XKB_STATE_MATCH_ALL = (1 << 1),
1307 /** Makes matching non-exclusive, i.e. will not return false if a
1308 * modifier not specified in the arguments is active. */
1309 XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16)
1313 * The counterpart to xkb_state_update_mask for modifiers, to be used on
1314 * the server side of serialization.
1316 * @param state The keyboard state.
1317 * @param components A mask of the modifier state components to serialize.
1318 * State components other than XKB_STATE_MODS_* are ignored.
1319 * If XKB_STATE_MODS_EFFECTIVE is included, all other state components are
1322 * @returns A xkb_mod_mask_t representing the given components of the
1325 * This function should not be used in regular clients; please use the
1326 * xkb_state_mod_*_is_active API instead.
1328 * @memberof xkb_state
1331 xkb_state_serialize_mods(struct xkb_state *state,
1332 enum xkb_state_component components);
1335 * The counterpart to xkb_state_update_mask for layouts, to be used on
1336 * the server side of serialization.
1338 * @param state The keyboard state.
1339 * @param components A mask of the layout state components to serialize.
1340 * State components other than XKB_STATE_LAYOUT_* are ignored.
1341 * If XKB_STATE_LAYOUT_EFFECTIVE is included, all other state components are
1344 * @returns A layout index representing the given components of the
1347 * This function should not be used in regular clients; please use the
1348 * xkb_state_layout_*_is_active API instead.
1350 * @memberof xkb_state
1353 xkb_state_serialize_layout(struct xkb_state *state,
1354 enum xkb_state_component components);
1357 * Test whether a modifier is active in a given keyboard state by name.
1359 * @returns 1 if the modifier is active, 0 if it is not. If the modifier
1360 * name does not exist in the keymap, returns -1.
1362 * @memberof xkb_state
1365 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
1366 enum xkb_state_component type);
1369 * Test whether a set of modifiers are active in a given keyboard state by
1372 * @param state The keyboard state.
1373 * @param type The component of the state against which to match the
1375 * @param match The manner by which to match the state against the
1377 * @param ... The set of of modifier names to test, terminated by a NULL
1378 * argument (sentinel).
1380 * @returns 1 if the modifiers are active, 0 if they are not. If any of
1381 * the modifier names do not exist in the keymap, returns -1.
1383 * @memberof xkb_state
1386 xkb_state_mod_names_are_active(struct xkb_state *state,
1387 enum xkb_state_component type,
1388 enum xkb_state_match match,
1392 * Test whether a modifier is active in a given keyboard state by index.
1394 * @returns 1 if the modifier is active, 0 if it is not. If the modifier
1395 * index is invalid in the keymap, returns -1.
1397 * @memberof xkb_state
1400 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
1401 enum xkb_state_component type);
1404 * Test whether a set of modifiers are active in a given keyboard state by
1407 * @param state The keyboard state.
1408 * @param type The component of the state against which to match the
1410 * @param match The manner by which to match the state against the
1412 * @param ... The set of of modifier indices to test, terminated by a
1413 * XKB_MOD_INVALID argument (sentinel).
1415 * @returns 1 if the modifiers are active, 0 if they are not. If any of
1416 * the modifier indices are invalid in the keymap, returns -1.
1418 * @memberof xkb_state
1421 xkb_state_mod_indices_are_active(struct xkb_state *state,
1422 enum xkb_state_component type,
1423 enum xkb_state_match match,
1427 * Test whether a modifier is consumed by keyboard state translation for
1430 * Some functions, like xkb_state_key_get_syms(), look at the state of
1431 * the modifiers in the keymap and derive from it the correct shift level
1432 * to use for the key. For example, in a US layout, pressing the key
1433 * labeled \<A\> while the Shift modifier is active, generates the keysym 'A'.
1434 * In this case, the Shift modifier is said to be consumed. However, the
1435 * Num Lock modifier does not affect this translation at all, even if it
1436 * active, so it is not consumed by this translation.
1438 * It may be desirable for some application to not reuse consumed modifiers
1439 * for further processing, e.g. for hotkeys or keyboard shortcuts. To
1440 * understand why, consider some requirements from a standard shortcut
1441 * mechanism, and how they are implemented:
1443 * 1. The shortcut's modifiers must match exactly to the state. For example,
1444 * it is possible to bind separate actions to \<Alt\>\<Tab\> and to
1445 * \<Alt\>\<Shift\>\<Tab\>. Further, if only \<Alt\>\<Tab\> is bound to
1446 * an action, pressing \<Alt\>\<Shift\>\<Tab\> should not trigger the
1448 * Effectively, this means that the modifiers are compared using the
1449 * equality operator (==).
1450 * 2. Only relevant modifiers are considered for the matching. For example,
1451 * Caps Lock and Num Lock should not generally affect the matching, e.g.
1452 * when matching \<Alt\>\<Tab\> against the state, it does not matter
1453 * whether Num Lock is active or not. These relevant, or significant,
1454 * modifiers usually include Alt, Control, Shift, Super and similar.
1455 * Effectively, this means that non-significant modifiers are masked out,
1456 * before doing the comparison as described above.
1457 * 3. The matching must be independent of the layout/keymap. For example,
1458 * the \<Plus\> (+) symbol is found on the first level on some layouts,
1459 * and requires holding Shift on others. If you simply bind the action
1460 * to the \<Plus\> keysym, it would work for the unshifted kind, but
1461 * not for the others, because the match against Shift would fail. If
1462 * you bind the action to \<Shift\>\<Plus\>, only the shifted kind would
1463 * work. So what is needed is to recognize that Shift is used up in the
1464 * translation of the keysym itself, and therefore should not be included
1466 * Effectively, this means that consumed modifiers (Shift in this example)
1467 * are masked out as well, before doing the comparison.
1469 * To summarize, this is how the matching would be performed:
1471 * (keysym == shortcut_keysym) &&
1472 * ((state_modifiers & ~consumed_modifiers & significant_modifiers) == shortcut_modifiers)
1475 * @c state_modifiers are the modifiers reported by
1476 * xkb_state_mod_index_is_active() and similar functions.
1477 * @c consumed_modifiers are the modifiers reported by
1478 * xkb_state_mod_index_is_consumed().
1479 * @c significant_modifiers are decided upon by the application/toolkit/user;
1480 * it is up to them to decide whether these are configurable or hard-coded.
1482 * @returns 1 if the modifier is consumed, 0 if it is not. If the modifier
1483 * index is not valid in the keymap, returns -1.
1485 * @sa xkb_state_mod_mask_remove_consumed()
1486 * @sa xkb_state_key_get_consumed_mods()
1487 * @memberof xkb_state
1490 xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key,
1491 xkb_mod_index_t idx);
1494 * Remove consumed modifiers from a modifier mask for a key.
1496 * Takes the given modifier mask, and removes all modifiers which are
1497 * consumed for that particular key (as in xkb_state_mod_index_is_consumed()).
1499 * @sa xkb_state_mod_index_is_consumed()
1500 * @memberof xkb_state
1503 xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t key,
1504 xkb_mod_mask_t mask);
1507 * Get the mask of modifiers consumed by translating a given key.
1509 * @returns a mask of the consumed modifiers.
1511 * @sa xkb_state_mod_index_is_consumed()
1512 * @memberof xkb_state
1515 xkb_state_key_get_consumed_mods(struct xkb_state *state, xkb_keycode_t key);
1518 * Test whether a layout is active in a given keyboard state by name.
1520 * @returns 1 if the layout is active, 0 if it is not. If no layout with
1521 * this name exists in the keymap, return -1.
1523 * If multiple layouts in the keymap have this name, the one with the lowest
1526 * @sa xkb_layout_index_t
1527 * @memberof xkb_state
1530 xkb_state_layout_name_is_active(struct xkb_state *state, const char *name,
1531 enum xkb_state_component type);
1534 * Test whether a layout is active in a given keyboard state by index.
1536 * @returns 1 if the layout is active, 0 if it is not. If the layout index
1537 * is not valid in the keymap, returns -1.
1539 * @sa xkb_layout_index_t
1540 * @memberof xkb_state
1543 xkb_state_layout_index_is_active(struct xkb_state *state,
1544 xkb_layout_index_t idx,
1545 enum xkb_state_component type);
1548 * Test whether a LED is active in a given keyboard state by name.
1550 * @returns 1 if the LED is active, 0 if it not. If no LED with this name
1551 * exists in the keymap, returns -1.
1553 * @sa xkb_led_index_t
1554 * @memberof xkb_state
1557 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
1560 * Test whether a LED is active in a given keyboard state by index.
1562 * @returns 1 if the LED is active, 0 if it not. If the LED index is not
1563 * valid in the keymap, returns -1.
1565 * @sa xkb_led_index_t
1566 * @memberof xkb_state
1569 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
1573 /* Leave this include last, so it can pick up our types, etc. */
1574 #include <xkbcommon/xkbcommon-compat.h>
1580 #endif /* _XKBCOMMON_H_ */