• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright 1985, 1987, 1990, 1998  The Open Group
3  * Copyright 2008  Dan Nicholson
4  *
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:
11  *
12  * The above copyright notice and this permission notice shall be included in
13  * all copies or substantial portions of the Software.
14  *
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.
21  *
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.
26  */
27 
28 /************************************************************
29  * Copyright (c) 1993 by Silicon Graphics Computer Systems, Inc.
30  *
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.
42  *
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.
51  *
52  ********************************************************/
53 
54 /*
55  * Copyright © 2009-2012 Daniel Stone
56  * Copyright © 2012 Intel Corporation
57  * Copyright © 2012 Ran Benita
58  *
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:
65  *
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
68  * Software.
69  *
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.
77  *
78  * Author: Daniel Stone <daniel@fooishbar.org>
79  */
80 
81 #ifndef _XKBCOMMON_H_
82 #define _XKBCOMMON_H_
83 
84 #include <stdint.h>
85 #include <stdio.h>
86 #include <stdarg.h>
87 
88 #include <xkbcommon/xkbcommon-names.h>
89 #include <xkbcommon/xkbcommon-keysyms.h>
90 
91 #ifdef __cplusplus
92 extern "C" {
93 #endif
94 
95 /**
96  * @file
97  * Main libxkbcommon API.
98  */
99 
100 /**
101  * @struct xkb_context
102  * Opaque top level library context object.
103  *
104  * The context contains various general library data and state, like
105  * logging level and include paths.
106  *
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.
110  */
111 struct xkb_context;
112 
113 /**
114  * @struct xkb_keymap
115  * Opaque compiled keymap object.
116  *
117  * The keymap object holds all of the static keyboard information obtained
118  * from compiling XKB files.
119  *
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.
122  */
123 struct xkb_keymap;
124 
125 /**
126  * @struct xkb_state
127  * Opaque keyboard state object.
128  *
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.
133  */
134 struct xkb_state;
135 
136 /**
137  * A number used to represent a physical key on a keyboard.
138  *
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.
142  *
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
149  * these keycodes.
150  *
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:
154  *
155  * @code
156  * xkb_keycode_t keycode_A = KEY_A + 8;
157  * @endcode
158  *
159  * @sa xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11()
160  */
161 typedef uint32_t xkb_keycode_t;
162 
163 /**
164  * A number used to represent the symbols generated from a key on a keyboard.
165  *
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.
171  *
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,
175  * see:
176  * http://www.x.org/releases/X11R7.7/doc/xproto/x11protocol.html#keysym_encoding
177  *
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.
181  *
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".
185  *
186  * The name of other unnamed keysyms is the hexadecimal representation of
187  * their value, e.g. "0xabcd1234".
188  *
189  * Keysym names are case-sensitive.
190  */
191 typedef uint32_t xkb_keysym_t;
192 
193 /**
194  * Index of a keyboard layout.
195  *
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
198  * arrangements, etc.
199  *
200  * Layout indices are consecutive.  The first layout has index 0.
201  *
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.
206  *
207  * Layouts are also called "groups" by XKB.
208  *
209  * @sa xkb_keymap_num_layouts() xkb_keymap_num_layouts_for_key()
210  */
211 typedef uint32_t xkb_layout_index_t;
212 /** A mask of layout indices. */
213 typedef uint32_t xkb_layout_mask_t;
214 
215 /**
216  * Index of a shift level.
217  *
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).
224  *
225  * Level indices are consecutive.  The first level has index 0.
226  */
227 typedef uint32_t xkb_level_index_t;
228 
229 /**
230  * Index of a modifier.
231  *
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).
238  *
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).
242  *
243  * Modifier indices are consecutive.  The first modifier has index 0.
244  *
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.
249  *
250  * @sa xkb_keymap_num_mods()
251  */
252 typedef uint32_t xkb_mod_index_t;
253 /** A mask of modifier indices. */
254 typedef uint32_t xkb_mod_mask_t;
255 
256 /**
257  * Index of a keyboard LED.
258  *
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.
262  *
263  * LED indices are non-consecutive.  The first LED has index 0.
264  *
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.
269  *
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.
276  *
277  * LEDs are also called "indicators" by XKB.
278  *
279  * @sa xkb_keymap_num_leds()
280  */
281 typedef uint32_t xkb_led_index_t;
282 /** A mask of LED indices. */
283 typedef uint32_t xkb_led_mask_t;
284 
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)
290 
291 #define XKB_KEYCODE_MAX     (0xffffffff - 1)
292 
293 /**
294  * Test whether a value is a valid extended keycode.
295  * @sa xkb_keycode_t
296  **/
297 #define xkb_keycode_is_legal_ext(key) (key <= XKB_KEYCODE_MAX)
298 
299 /**
300  * Test whether a value is a valid X11 keycode.
301  * @sa xkb_keycode_t
302  */
303 #define xkb_keycode_is_legal_x11(key) (key >= 8 && key <= 255)
304 
305 /**
306  * Names to compile a keymap with, also known as RMLVO.
307  *
308  * The names are the common configuration values by which a user picks
309  * a keymap.
310  *
311  * If the entire struct is NULL, then each field is taken to be NULL.
312  * You should prefer passing NULL instead of choosing your own defaults.
313  */
314 struct xkb_rule_names {
315     /**
316      * The rules file to use. The rules file describes how to interpret
317      * the values of the model, layout, variant and options fields.
318      *
319      * If NULL or the empty string "", a default value is used.
320      * If the XKB_DEFAULT_RULES environment variable is set, it is used
321      * as the default.  Otherwise the system default is used.
322      */
323     const char *rules;
324     /**
325      * The keyboard model by which to interpret keycodes and LEDs.
326      *
327      * If NULL or the empty string "", a default value is used.
328      * If the XKB_DEFAULT_MODEL environment variable is set, it is used
329      * as the default.  Otherwise the system default is used.
330      */
331     const char *model;
332     /**
333      * A comma separated list of layouts (languages) to include in the
334      * keymap.
335      *
336      * If NULL or the empty string "", a default value is used.
337      * If the XKB_DEFAULT_LAYOUT environment variable is set, it is used
338      * as the default.  Otherwise the system default is used.
339      */
340     const char *layout;
341     /**
342      * A comma separated list of variants, one per layout, which may
343      * modify or augment the respective layout in various ways.
344      *
345      * If NULL or the empty string "", and a default value is also used
346      * for the layout, a default value is used.  Otherwise no variant is
347      * used.
348      * If the XKB_DEFAULT_VARIANT environment variable is set, it is used
349      * as the default.  Otherwise the system default is used.
350      */
351     const char *variant;
352     /**
353      * A comma separated list of options, through which the user specifies
354      * non-layout related preferences, like which key combinations are used
355      * for switching layouts, or which key is the Compose key.
356      *
357      * If NULL, a default value is used.  If the empty string "", no
358      * options are used.
359      * If the XKB_DEFAULT_OPTIONS environment variable is set, it is used
360      * as the default.  Otherwise the system default is used.
361      */
362     const char *options;
363 };
364 
365 /**
366  * @defgroup keysyms Keysyms
367  * Utility functions related to keysyms.
368  *
369  * @{
370  */
371 
372 /**
373  * @page keysym-transformations Keysym Transformations
374  *
375  * Keysym translation is subject to several "keysym transformations",
376  * as described in the XKB specification.  These are:
377  *
378  * - Capitalization transformation.  If the Caps Lock modifier is
379  *   active and was not consumed by the translation process, a single
380  *   keysym is transformed to its upper-case form (if applicable).
381  *   Similarly, the UTF-8/UTF-32 string produced is capitalized.
382  *
383  *   This is described in:
384  *   http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Lock_Modifier
385  *
386  * - Control transformation.  If the Control modifier is active and
387  *   was not consumed by the translation process, the string produced
388  *   is transformed to its matching ASCII control character (if
389  *   applicable).  Keysyms are not affected.
390  *
391  *   This is described in:
392  *   http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier
393  *
394  * Each relevant function discusses which transformations it performs.
395  *
396  * These transformations are not applicable when a key produces multiple
397  * keysyms.
398  */
399 
400 
401 /**
402  * Get the name of a keysym.
403  *
404  * For a description of how keysyms are named, see @ref xkb_keysym_t.
405  *
406  * @param[in]  keysym The keysym.
407  * @param[out] buffer A string buffer to write the name into.
408  * @param[in]  size   Size of the buffer.
409  *
410  * @warning If the buffer passed is too small, the string is truncated
411  * (though still NUL-terminated); a size of at least 64 bytes is recommended.
412  *
413  * @returns The number of bytes in the name, excluding the NUL byte. If
414  * the keysym is invalid, returns -1.
415  *
416  * You may check if truncation has occurred by comparing the return value
417  * with the length of buffer, similarly to the snprintf(3) function.
418  *
419  * @sa xkb_keysym_t
420  */
421 int
422 xkb_keysym_get_name(xkb_keysym_t keysym, char *buffer, size_t size);
423 
424 /** Flags for xkb_keysym_from_name(). */
425 enum xkb_keysym_flags {
426     /** Do not apply any flags. */
427     XKB_KEYSYM_NO_FLAGS = 0,
428     /** Find keysym by case-insensitive search. */
429     XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0)
430 };
431 
432 /**
433  * Get a keysym from its name.
434  *
435  * @param name The name of a keysym. See remarks in xkb_keysym_get_name();
436  * this function will accept any name returned by that function.
437  * @param flags A set of flags controlling how the search is done. If
438  * invalid flags are passed, this will fail with XKB_KEY_NoSymbol.
439  *
440  * If you use the XKB_KEYSYM_CASE_INSENSITIVE flag and two keysym names
441  * differ only by case, then the lower-case keysym is returned.  For
442  * instance, for KEY_a and KEY_A, this function would return KEY_a for the
443  * case-insensitive search.  If this functionality is needed, it is
444  * recommended to first call this function without this flag; and if that
445  * fails, only then to try with this flag, while possibly warning the user
446  * he had misspelled the name, and might get wrong results.
447  *
448  * @returns The keysym. If the name is invalid, returns XKB_KEY_NoSymbol.
449  *
450  * @sa xkb_keysym_t
451  */
452 xkb_keysym_t
453 xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags);
454 
455 /**
456  * Get the Unicode/UTF-8 representation of a keysym.
457  *
458  * @param[in]  keysym The keysym.
459  * @param[out] buffer A buffer to write the UTF-8 string into.
460  * @param[in]  size   The size of buffer.  Must be at least 7.
461  *
462  * @returns The number of bytes written to the buffer (including the
463  * terminating byte).  If the keysym does not have a Unicode
464  * representation, returns 0.  If the buffer is too small, returns -1.
465  *
466  * This function does not perform any @ref keysym-transformations.
467  * Therefore, prefer to use xkb_state_key_get_utf8() if possible.
468  *
469  * @sa xkb_state_key_get_utf8()
470  */
471 int
472 xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size);
473 
474 /**
475  * Get the Unicode/UTF-32 representation of a keysym.
476  *
477  * @returns The Unicode/UTF-32 representation of keysym, which is also
478  * compatible with UCS-4.  If the keysym does not have a Unicode
479  * representation, returns 0.
480  *
481  * This function does not perform any @ref keysym-transformations.
482  * Therefore, prefer to use xkb_state_key_get_utf32() if possible.
483  *
484  * @sa xkb_state_key_get_utf32()
485  */
486 uint32_t
487 xkb_keysym_to_utf32(xkb_keysym_t keysym);
488 
489 /** @} */
490 
491 /**
492  * @defgroup context Library Context
493  * Creating, destroying and using library contexts.
494  *
495  * Every keymap compilation request must have a context associated with
496  * it.  The context keeps around state such as the include path.
497  *
498  * @{
499  */
500 
501 /** Flags for context creation. */
502 enum xkb_context_flags {
503     /** Do not apply any context flags. */
504     XKB_CONTEXT_NO_FLAGS = 0,
505     /** Create this context with an empty include path. */
506     XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
507     /**
508      * Don't take RMLVO names from the environment.
509      * @since 0.3.0
510      */
511     XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1)
512 };
513 
514 /**
515  * Create a new context.
516  *
517  * @param flags Optional flags for the context, or 0.
518  *
519  * @returns A new context, or NULL on failure.
520  *
521  * The user may set some environment variables to affect default values in
522  * the context. See e.g. xkb_context_set_log_level() and
523  * xkb_context_set_log_verbosity().
524  *
525  * @memberof xkb_context
526  */
527 struct xkb_context *
528 xkb_context_new(enum xkb_context_flags flags);
529 
530 /**
531  * Take a new reference on a context.
532  *
533  * @returns The passed in context.
534  *
535  * @memberof xkb_context
536  */
537 struct xkb_context *
538 xkb_context_ref(struct xkb_context *context);
539 
540 /**
541  * Release a reference on a context, and possibly free it.
542  *
543  * @param context The context.  If it is NULL, this function does nothing.
544  *
545  * @memberof xkb_context
546  */
547 void
548 xkb_context_unref(struct xkb_context *context);
549 
550 /**
551  * Store custom user data in the context.
552  *
553  * This may be useful in conjunction with xkb_context_set_log_fn() or other
554  * callbacks.
555  *
556  * @memberof xkb_context
557  */
558 void
559 xkb_context_set_user_data(struct xkb_context *context, void *user_data);
560 
561 /**
562  * Retrieves stored user data from the context.
563  *
564  * @returns The stored user data.  If the user data wasn't set, or the
565  * passed in context is NULL, returns NULL.
566  *
567  * This may be useful to access private user data from callbacks like a
568  * custom logging function.
569  *
570  * @memberof xkb_context
571  **/
572 void *
573 xkb_context_get_user_data(struct xkb_context *context);
574 
575 /** @} */
576 
577 /**
578  * @defgroup include-path Include Paths
579  * Manipulating the include paths in a context.
580  *
581  * The include paths are the file-system paths that are searched when an
582  * include statement is encountered during keymap compilation.
583  * In most cases, the default include paths are sufficient.
584  *
585  * @{
586  */
587 
588 /**
589  * Append a new entry to the context's include path.
590  *
591  * @returns 1 on success, or 0 if the include path could not be added or is
592  * inaccessible.
593  *
594  * @memberof xkb_context
595  */
596 int
597 xkb_context_include_path_append(struct xkb_context *context, const char *path);
598 
599 /**
600  * Append the default include paths to the context's include path.
601  *
602  * @returns 1 on success, or 0 if the primary include path could not be added.
603  *
604  * @memberof xkb_context
605  */
606 int
607 xkb_context_include_path_append_default(struct xkb_context *context);
608 
609 /**
610  * Reset the context's include path to the default.
611  *
612  * Removes all entries from the context's include path, and inserts the
613  * default paths.
614  *
615  * @returns 1 on success, or 0 if the primary include path could not be added.
616  *
617  * @memberof xkb_context
618  */
619 int
620 xkb_context_include_path_reset_defaults(struct xkb_context *context);
621 
622 /**
623  * Remove all entries from the context's include path.
624  *
625  * @memberof xkb_context
626  */
627 void
628 xkb_context_include_path_clear(struct xkb_context *context);
629 
630 /**
631  * Get the number of paths in the context's include path.
632  *
633  * @memberof xkb_context
634  */
635 unsigned int
636 xkb_context_num_include_paths(struct xkb_context *context);
637 
638 /**
639  * Get a specific include path from the context's include path.
640  *
641  * @returns The include path at the specified index.  If the index is
642  * invalid, returns NULL.
643  *
644  * @memberof xkb_context
645  */
646 const char *
647 xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
648 
649 /** @} */
650 
651 /**
652  * @defgroup logging Logging Handling
653  * Manipulating how logging from this library is handled.
654  *
655  * @{
656  */
657 
658 /** Specifies a logging level. */
659 enum xkb_log_level {
660     XKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
661     XKB_LOG_LEVEL_ERROR = 20,    /**< Log all errors. */
662     XKB_LOG_LEVEL_WARNING = 30,  /**< Log warnings and errors. */
663     XKB_LOG_LEVEL_INFO = 40,     /**< Log information, warnings, and errors. */
664     XKB_LOG_LEVEL_DEBUG = 50     /**< Log everything. */
665 };
666 
667 /**
668  * Set the current logging level.
669  *
670  * @param context The context in which to set the logging level.
671  * @param level   The logging level to use.  Only messages from this level
672  * and below will be logged.
673  *
674  * The default level is XKB_LOG_LEVEL_ERROR.  The environment variable
675  * XKB_LOG_LEVEL, if set in the time the context was created, overrides the
676  * default value.  It may be specified as a level number or name.
677  *
678  * @memberof xkb_context
679  */
680 void
681 xkb_context_set_log_level(struct xkb_context *context,
682                           enum xkb_log_level level);
683 
684 /**
685  * Get the current logging level.
686  *
687  * @memberof xkb_context
688  */
689 enum xkb_log_level
690 xkb_context_get_log_level(struct xkb_context *context);
691 
692 /**
693  * Sets the current logging verbosity.
694  *
695  * The library can generate a number of warnings which are not helpful to
696  * ordinary users of the library.  The verbosity may be increased if more
697  * information is desired (e.g. when developing a new keymap).
698  *
699  * The default verbosity is 0.  The environment variable XKB_LOG_VERBOSITY,
700  * if set in the time the context was created, overrides the default value.
701  *
702  * @param context   The context in which to use the set verbosity.
703  * @param verbosity The verbosity to use.  Currently used values are
704  * 1 to 10, higher values being more verbose.  0 would result in no verbose
705  * messages being logged.
706  *
707  * Most verbose messages are of level XKB_LOG_LEVEL_WARNING or lower.
708  *
709  * @memberof xkb_context
710  */
711 void
712 xkb_context_set_log_verbosity(struct xkb_context *context, int verbosity);
713 
714 /**
715  * Get the current logging verbosity of the context.
716  *
717  * @memberof xkb_context
718  */
719 int
720 xkb_context_get_log_verbosity(struct xkb_context *context);
721 
722 /**
723  * Set a custom function to handle logging messages.
724  *
725  * @param context The context in which to use the set logging function.
726  * @param log_fn  The function that will be called for logging messages.
727  * Passing NULL restores the default function, which logs to stderr.
728  *
729  * By default, log messages from this library are printed to stderr.  This
730  * function allows you to replace the default behavior with a custom
731  * handler.  The handler is only called with messages which match the
732  * current logging level and verbosity settings for the context.
733  * level is the logging level of the message.  @a format and @a args are
734  * the same as in the vprintf(3) function.
735  *
736  * You may use xkb_context_set_user_data() on the context, and then call
737  * xkb_context_get_user_data() from within the logging function to provide
738  * it with additional private context.
739  *
740  * @memberof xkb_context
741  */
742 void
743 xkb_context_set_log_fn(struct xkb_context *context,
744                        void (*log_fn)(struct xkb_context *context,
745                                       enum xkb_log_level level,
746                                       const char *format, va_list args));
747 
748 /** @} */
749 
750 /**
751  * @defgroup keymap Keymap Creation
752  * Creating and destroying keymaps.
753  *
754  * @{
755  */
756 
757 /** Flags for keymap compilation. */
758 enum xkb_keymap_compile_flags {
759     /** Do not apply any flags. */
760     XKB_KEYMAP_COMPILE_NO_FLAGS = 0
761 };
762 
763 /**
764  * Create a keymap from RMLVO names.
765  *
766  * The primary keymap entry point: creates a new XKB keymap from a set of
767  * RMLVO (Rules + Model + Layouts + Variants + Options) names.
768  *
769  * @param context The context in which to create the keymap.
770  * @param names   The RMLVO names to use.  See xkb_rule_names.
771  * @param flags   Optional flags for the keymap, or 0.
772  *
773  * @returns A keymap compiled according to the RMLVO names, or NULL if
774  * the compilation failed.
775  *
776  * @sa xkb_rule_names
777  * @memberof xkb_keymap
778  */
779 struct xkb_keymap *
780 xkb_keymap_new_from_names(struct xkb_context *context,
781                           const struct xkb_rule_names *names,
782                           enum xkb_keymap_compile_flags flags);
783 
784 /** The possible keymap formats. */
785 enum xkb_keymap_format {
786     /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
787     XKB_KEYMAP_FORMAT_TEXT_V1 = 1
788 };
789 
790 /**
791  * Create a keymap from a keymap file.
792  *
793  * @param context The context in which to create the keymap.
794  * @param file    The keymap file to compile.
795  * @param format  The text format of the keymap file to compile.
796  * @param flags   Optional flags for the keymap, or 0.
797  *
798  * @returns A keymap compiled from the given XKB keymap file, or NULL if
799  * the compilation failed.
800  *
801  * The file must contain a complete keymap.  For example, in the
802  * XKB_KEYMAP_FORMAT_TEXT_V1 format, this means the file must contain one
803  * top level '%xkb_keymap' section, which in turn contains other required
804  * sections.
805  *
806  * @memberof xkb_keymap
807  */
808 struct xkb_keymap *
809 xkb_keymap_new_from_file(struct xkb_context *context, FILE *file,
810                          enum xkb_keymap_format format,
811                          enum xkb_keymap_compile_flags flags);
812 
813 /**
814  * Create a keymap from a keymap string.
815  *
816  * This is just like xkb_keymap_new_from_file(), but instead of a file, gets
817  * the keymap as one enormous string.
818  *
819  * @see xkb_keymap_new_from_file()
820  * @memberof xkb_keymap
821  */
822 struct xkb_keymap *
823 xkb_keymap_new_from_string(struct xkb_context *context, const char *string,
824                            enum xkb_keymap_format format,
825                            enum xkb_keymap_compile_flags flags);
826 
827 /**
828  * Create a keymap from a memory buffer.
829  *
830  * This is just like xkb_keymap_new_from_string(), but takes a length argument
831  * so the input string does not have to be zero-terminated.
832  *
833  * @see xkb_keymap_new_from_string()
834  * @memberof xkb_keymap
835  * @since 0.3.0
836  */
837 struct xkb_keymap *
838 xkb_keymap_new_from_buffer(struct xkb_context *context, const char *buffer,
839                            size_t length, enum xkb_keymap_format format,
840                            enum xkb_keymap_compile_flags flags);
841 
842 /**
843  * Take a new reference on a keymap.
844  *
845  * @returns The passed in keymap.
846  *
847  * @memberof xkb_keymap
848  */
849 struct xkb_keymap *
850 xkb_keymap_ref(struct xkb_keymap *keymap);
851 
852 /**
853  * Release a reference on a keymap, and possibly free it.
854  *
855  * @param keymap The keymap.  If it is NULL, this function does nothing.
856  *
857  * @memberof xkb_keymap
858  */
859 void
860 xkb_keymap_unref(struct xkb_keymap *keymap);
861 
862 /**
863  * Get the keymap as a string in the format from which it was created.
864  * @sa xkb_keymap_get_as_string()
865  **/
866 #define XKB_KEYMAP_USE_ORIGINAL_FORMAT ((enum xkb_keymap_format) -1)
867 
868 /**
869  * Get the compiled keymap as a string.
870  *
871  * @param keymap The keymap to get as a string.
872  * @param format The keymap format to use for the string.  You can pass
873  * in the special value XKB_KEYMAP_USE_ORIGINAL_FORMAT to use the format
874  * from which the keymap was originally created.
875  *
876  * @returns The keymap as a NUL-terminated string, or NULL if unsuccessful.
877  *
878  * The returned string may be fed back into xkb_map_new_from_string() to get
879  * the exact same keymap (possibly in another process, etc.).
880  *
881  * The returned string is dynamically allocated and should be freed by the
882  * caller.
883  *
884  * @memberof xkb_keymap
885  */
886 char *
887 xkb_keymap_get_as_string(struct xkb_keymap *keymap,
888                          enum xkb_keymap_format format);
889 
890 /** @} */
891 
892 /**
893  * @defgroup components Keymap Components
894  * Enumeration of state components in a keymap.
895  *
896  * @{
897  */
898 
899 /**
900  * Get the minimum keycode in the keymap.
901  *
902  * @sa xkb_keycode_t
903  * @memberof xkb_keymap
904  * @since 0.3.1
905  */
906 xkb_keycode_t
907 xkb_keymap_min_keycode(struct xkb_keymap *keymap);
908 
909 /**
910  * Get the maximum keycode in the keymap.
911  *
912  * @sa xkb_keycode_t
913  * @memberof xkb_keymap
914  * @since 0.3.1
915  */
916 xkb_keycode_t
917 xkb_keymap_max_keycode(struct xkb_keymap *keymap);
918 
919 /**
920  * The iterator used by xkb_keymap_key_for_each().
921  *
922  * @sa xkb_keymap_key_for_each
923  * @memberof xkb_keymap
924  * @since 0.3.1
925  */
926 typedef void
927 (*xkb_keymap_key_iter_t)(struct xkb_keymap *keymap, xkb_keycode_t key,
928                          void *data);
929 
930 /**
931  * Run a specified function for every valid keycode in the keymap.  If a
932  * keymap is sparse, this function may be called fewer than
933  * (max_keycode - min_keycode + 1) times.
934  *
935  * @sa xkb_keymap_min_keycode() xkb_keymap_max_keycode() xkb_keycode_t
936  * @memberof xkb_keymap
937  * @since 0.3.1
938  */
939 void
940 xkb_keymap_key_for_each(struct xkb_keymap *keymap, xkb_keymap_key_iter_t iter,
941                         void *data);
942 
943 /**
944  * Get the number of modifiers in the keymap.
945  *
946  * @sa xkb_mod_index_t
947  * @memberof xkb_keymap
948  */
949 xkb_mod_index_t
950 xkb_keymap_num_mods(struct xkb_keymap *keymap);
951 
952 /**
953  * Get the name of a modifier by index.
954  *
955  * @returns The name.  If the index is invalid, returns NULL.
956  *
957  * @sa xkb_mod_index_t
958  * @memberof xkb_keymap
959  */
960 const char *
961 xkb_keymap_mod_get_name(struct xkb_keymap *keymap, xkb_mod_index_t idx);
962 
963 /**
964  * Get the index of a modifier by name.
965  *
966  * @returns The index.  If no modifier with this name exists, returns
967  * XKB_MOD_INVALID.
968  *
969  * @sa xkb_mod_index_t
970  * @memberof xkb_keymap
971  */
972 xkb_mod_index_t
973 xkb_keymap_mod_get_index(struct xkb_keymap *keymap, const char *name);
974 
975 /**
976  * Get the number of layouts in the keymap.
977  *
978  * @sa xkb_layout_index_t xkb_rule_names xkb_keymap_num_layouts_for_key()
979  * @memberof xkb_keymap
980  */
981 xkb_layout_index_t
982 xkb_keymap_num_layouts(struct xkb_keymap *keymap);
983 
984 /**
985  * Get the name of a layout by index.
986  *
987  * @returns The name.  If the index is invalid, or the layout does not have
988  * a name, returns NULL.
989  *
990  * @sa xkb_layout_index_t
991  * @memberof xkb_keymap
992  */
993 const char *
994 xkb_keymap_layout_get_name(struct xkb_keymap *keymap, xkb_layout_index_t idx);
995 
996 /**
997  * Get the index of a layout by name.
998  *
999  * @returns The index.  If no layout exists with this name, returns
1000  * XKB_LAYOUT_INVALID.  If more than one layout in the keymap has this name,
1001  * returns the lowest index among them.
1002  *
1003  * @memberof xkb_keymap
1004  */
1005 xkb_layout_index_t
1006 xkb_keymap_layout_get_index(struct xkb_keymap *keymap, const char *name);
1007 
1008 /**
1009  * Get the number of LEDs in the keymap.
1010  *
1011  * @warning The range [ 0...xkb_keymap_num_leds() ) includes all of the LEDs
1012  * in the keymap, but may also contain inactive LEDs.  When iterating over
1013  * this range, you need the handle this case when calling functions such as
1014  * xkb_keymap_led_get_name() or xkb_state_led_index_is_active().
1015  *
1016  * @sa xkb_led_index_t
1017  * @memberof xkb_keymap
1018  */
1019 xkb_led_index_t
1020 xkb_keymap_num_leds(struct xkb_keymap *keymap);
1021 
1022 /**
1023  * Get the name of a LED by index.
1024  *
1025  * @returns The name.  If the index is invalid, returns NULL.
1026  *
1027  * @memberof xkb_keymap
1028  */
1029 const char *
1030 xkb_keymap_led_get_name(struct xkb_keymap *keymap, xkb_led_index_t idx);
1031 
1032 /**
1033  * Get the index of a LED by name.
1034  *
1035  * @returns The index.  If no LED with this name exists, returns
1036  * XKB_LED_INVALID.
1037  *
1038  * @memberof xkb_keymap
1039  */
1040 xkb_led_index_t
1041 xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name);
1042 
1043 /**
1044  * Get the number of layouts for a specific key.
1045  *
1046  * This number can be different from xkb_keymap_num_layouts(), but is always
1047  * smaller.  It is the appropriate value to use when iterating over the
1048  * layouts of a key.
1049  *
1050  * @sa xkb_layout_index_t
1051  * @memberof xkb_keymap
1052  */
1053 xkb_layout_index_t
1054 xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key);
1055 
1056 /**
1057  * Get the number of shift levels for a specific key and layout.
1058  *
1059  * If @c layout is out of range for this key (that is, larger or equal to
1060  * the value returned by xkb_keymap_num_layouts_for_key()), it is brought
1061  * back into range in a manner consistent with xkb_state_key_get_layout().
1062  *
1063  * @sa xkb_level_index_t
1064  * @memberof xkb_keymap
1065  */
1066 xkb_level_index_t
1067 xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key,
1068                               xkb_layout_index_t layout);
1069 
1070 /**
1071  * Get the keysyms obtained from pressing a key in a given layout and
1072  * shift level.
1073  *
1074  * This function is like xkb_state_key_get_syms(), only the layout and
1075  * shift level are not derived from the keyboard state but are instead
1076  * specified explicitly.
1077  *
1078  * @param[in] keymap    The keymap.
1079  * @param[in] key       The keycode of the key.
1080  * @param[in] layout    The layout for which to get the keysyms.
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_levels_for_key(keymap, key) @endcode
1084  * @param[out] syms_out An immutable array of keysyms corresponding to the
1085  * key in the given layout and shift level.
1086  *
1087  * If @c layout is out of range for this key (that is, larger or equal to
1088  * the value returned by xkb_keymap_num_layouts_for_key()), it is brought
1089  * back into range in a manner consistent with xkb_state_key_get_layout().
1090  *
1091  * @returns The number of keysyms in the syms_out array.  If no keysyms
1092  * are produced by the key in the given layout and shift level, returns 0
1093  * and sets syms_out to NULL.
1094  *
1095  * @sa xkb_state_key_get_syms()
1096  * @memberof xkb_keymap
1097  */
1098 int
1099 xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap,
1100                                  xkb_keycode_t key,
1101                                  xkb_layout_index_t layout,
1102                                  xkb_level_index_t level,
1103                                  const xkb_keysym_t **syms_out);
1104 
1105 /**
1106  * Determine whether a key should repeat or not.
1107  *
1108  * A keymap may specify different repeat behaviors for different keys.
1109  * Most keys should generally exhibit repeat behavior; for example, holding
1110  * the 'a' key down in a text editor should normally insert a single 'a'
1111  * character every few milliseconds, until the key is released.  However,
1112  * there are keys which should not or do not need to be repeated.  For
1113  * example, repeating modifier keys such as Left/Right Shift or Caps Lock
1114  * is not generally useful or desired.
1115  *
1116  * @returns 1 if the key should repeat, 0 otherwise.
1117  *
1118  * @memberof xkb_keymap
1119  */
1120 int
1121 xkb_keymap_key_repeats(struct xkb_keymap *keymap, xkb_keycode_t key);
1122 
1123 /** @} */
1124 
1125 /**
1126  * @defgroup state Keyboard State
1127  * Creating, destroying and manipulating keyboard state objects.
1128  *
1129  * @{
1130  */
1131 
1132 /**
1133  * Create a new keyboard state object.
1134  *
1135  * @param keymap The keymap which the state will use.
1136  *
1137  * @returns A new keyboard state object, or NULL on failure.
1138  *
1139  * @memberof xkb_state
1140  */
1141 struct xkb_state *
1142 xkb_state_new(struct xkb_keymap *keymap);
1143 
1144 /**
1145  * Take a new reference on a keyboard state object.
1146  *
1147  * @returns The passed in object.
1148  *
1149  * @memberof xkb_state
1150  */
1151 struct xkb_state *
1152 xkb_state_ref(struct xkb_state *state);
1153 
1154 /**
1155  * Release a reference on a keybaord state object, and possibly free it.
1156  *
1157  * @param state The state.  If it is NULL, this function does nothing.
1158  *
1159  * @memberof xkb_state
1160  */
1161 void
1162 xkb_state_unref(struct xkb_state *state);
1163 
1164 /**
1165  * Get the keymap which a keyboard state object is using.
1166  *
1167  * @returns The keymap which was passed to xkb_state_new() when creating
1168  * this state object.
1169  *
1170  * This function does not take a new reference on the keymap; you must
1171  * explicitly reference it yourself if you plan to use it beyond the
1172  * lifetime of the state.
1173  *
1174  * @memberof xkb_state
1175  */
1176 struct xkb_keymap *
1177 xkb_state_get_keymap(struct xkb_state *state);
1178 
1179 /** Specifies the direction of the key (press / release). */
1180 enum xkb_key_direction {
1181     XKB_KEY_UP,   /**< The key was released. */
1182     XKB_KEY_DOWN  /**< The key was pressed. */
1183 };
1184 
1185 /**
1186  * Modifier and layout types for state objects.  This enum is bitmaskable,
1187  * e.g. (XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED) is valid to
1188  * exclude locked modifiers.
1189  *
1190  * In XKB, the DEPRESSED components are also known as 'base'.
1191  */
1192 enum xkb_state_component {
1193     /** Depressed modifiers, i.e. a key is physically holding them. */
1194     XKB_STATE_MODS_DEPRESSED = (1 << 0),
1195     /** Latched modifiers, i.e. will be unset after the next non-modifier
1196      *  key press. */
1197     XKB_STATE_MODS_LATCHED = (1 << 1),
1198     /** Locked modifiers, i.e. will be unset after the key provoking the
1199      *  lock has been pressed again. */
1200     XKB_STATE_MODS_LOCKED = (1 << 2),
1201     /** Effective modifiers, i.e. currently active and affect key
1202      *  processing (derived from the other state components).
1203      *  Use this unless you explictly care how the state came about. */
1204     XKB_STATE_MODS_EFFECTIVE = (1 << 3),
1205     /** Depressed layout, i.e. a key is physically holding it. */
1206     XKB_STATE_LAYOUT_DEPRESSED = (1 << 4),
1207     /** Latched layout, i.e. will be unset after the next non-modifier
1208      *  key press. */
1209     XKB_STATE_LAYOUT_LATCHED = (1 << 5),
1210     /** Locked layout, i.e. will be unset after the key provoking the lock
1211      *  has been pressed again. */
1212     XKB_STATE_LAYOUT_LOCKED = (1 << 6),
1213     /** Effective layout, i.e. currently active and affects key processing
1214      *  (derived from the other state components).
1215      *  Use this unless you explictly care how the state came about. */
1216     XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7),
1217     /** LEDs (derived from the other state components). */
1218     XKB_STATE_LEDS = (1 << 8)
1219 };
1220 
1221 /**
1222  * Update the keyboard state to reflect a given key being pressed or
1223  * released.
1224  *
1225  * This entry point is intended for programs which track the keyboard state
1226  * explictly (like an evdev client).  If the state is serialized to you by
1227  * a master process (like a Wayland compositor) using functions like
1228  * xkb_state_serialize_mods(), you should use xkb_state_update_mask() instead.
1229  * The two functins should not generally be used together.
1230  *
1231  * A series of calls to this function should be consistent; that is, a call
1232  * with XKB_KEY_DOWN for a key should be matched by an XKB_KEY_UP; if a key
1233  * is pressed twice, it should be released twice; etc. Otherwise (e.g. due
1234  * to missed input events), situations like "stuck modifiers" may occur.
1235  *
1236  * This function is often used in conjunction with the function
1237  * xkb_state_key_get_syms() (or xkb_state_key_get_one_sym()), for example,
1238  * when handling a key event.  In this case, you should prefer to get the
1239  * keysyms *before* updating the key, such that the keysyms reported for
1240  * the key event are not affected by the event itself.  This is the
1241  * conventional behavior.
1242  *
1243  * @returns A mask of state components that have changed as a result of
1244  * the update.  If nothing in the state has changed, returns 0.
1245  *
1246  * @memberof xkb_state
1247  *
1248  * @sa xkb_state_update_mask()
1249  */
1250 enum xkb_state_component
1251 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
1252                      enum xkb_key_direction direction);
1253 
1254 /**
1255  * Update a keyboard state from a set of explicit masks.
1256  *
1257  * This entry point is intended for window systems and the like, where a
1258  * master process holds an xkb_state, then serializes it over a wire
1259  * protocol, and clients then use the serialization to feed in to their own
1260  * xkb_state.
1261  *
1262  * All parameters must always be passed, or the resulting state may be
1263  * incoherent.
1264  *
1265  * The serialization is lossy and will not survive round trips; it must only
1266  * be used to feed slave state objects, and must not be used to update the
1267  * master state.
1268  *
1269  * If you do not fit the description above, you should use
1270  * xkb_state_update_key() instead.  The two functions should not generally be
1271  * used together.
1272  *
1273  * @returns A mask of state components that have changed as a result of
1274  * the update.  If nothing in the state has changed, returns 0.
1275  *
1276  * @memberof xkb_state
1277  *
1278  * @sa xkb_state_component
1279  * @sa xkb_state_update_key
1280  */
1281 enum xkb_state_component
1282 xkb_state_update_mask(struct xkb_state *state,
1283                       xkb_mod_mask_t depressed_mods,
1284                       xkb_mod_mask_t latched_mods,
1285                       xkb_mod_mask_t locked_mods,
1286                       xkb_layout_index_t depressed_layout,
1287                       xkb_layout_index_t latched_layout,
1288                       xkb_layout_index_t locked_layout);
1289 
1290 /**
1291  * Get the keysyms obtained from pressing a particular key in a given
1292  * keyboard state.
1293  *
1294  * Get the keysyms for a key according to the current active layout,
1295  * modifiers and shift level for the key, as determined by a keyboard
1296  * state.
1297  *
1298  * @param[in]  state    The keyboard state object.
1299  * @param[in]  key      The keycode of the key.
1300  * @param[out] syms_out An immutable array of keysyms corresponding the
1301  * key in the given keyboard state.
1302  *
1303  * As an extension to XKB, this function can return more than one keysym.
1304  * If you do not want to handle this case, you can use
1305  * xkb_state_key_get_one_sym() for a simpler interface.
1306  *
1307  * This function does not perform any @ref keysym-transformations.
1308  * (This might change).
1309  *
1310  * @returns The number of keysyms in the syms_out array.  If no keysyms
1311  * are produced by the key in the given keyboard state, returns 0 and sets
1312  * syms_out to NULL.
1313  *
1314  * @memberof xkb_state
1315  */
1316 int
1317 xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
1318                        const xkb_keysym_t **syms_out);
1319 
1320 /**
1321  * Get the Unicode/UTF-8 string obtained from pressing a particular key
1322  * in a given keyboard state.
1323  *
1324  * @param[in]  state  The keyboard state object.
1325  * @param[in]  key    The keycode of the key.
1326  * @param[out] buffer A buffer to write the string into.
1327  * @param[in]  size   Size of the buffer.
1328  *
1329  * @warning If the buffer passed is too small, the string is truncated
1330  * (though still NUL-terminated).
1331  *
1332  * @returns The number of bytes required for the string, excluding the
1333  * NUL byte.  If there is nothing to write, returns 0.
1334  *
1335  * You may check if truncation has occurred by comparing the return value
1336  * with the size of @p buffer, similarly to the snprintf(3) function.
1337  * You may safely pass NULL and 0 to @p buffer and @p size to find the
1338  * required size (without the NUL-byte).
1339  *
1340  * This function performs Capitalization and Control @ref
1341  * keysym-transformations.
1342  *
1343  * @memberof xkb_state
1344  * @since 0.4.1
1345  */
1346 int
1347 xkb_state_key_get_utf8(struct xkb_state *state, xkb_keycode_t key,
1348                        char *buffer, size_t size);
1349 
1350 /**
1351  * Get the Unicode/UTF-32 codepoint obtained from pressing a particular
1352  * key in a a given keyboard state.
1353  *
1354  * @returns The UTF-32 representation for the key, if it consists of only
1355  * a single codepoint.  Otherwise, returns 0.
1356  *
1357  * This function performs Capitalization and Control @ref
1358  * keysym-transformations.
1359  *
1360  * @memberof xkb_state
1361  * @since 0.4.1
1362  */
1363 uint32_t
1364 xkb_state_key_get_utf32(struct xkb_state *state, xkb_keycode_t key);
1365 
1366 /**
1367  * Get the single keysym obtained from pressing a particular key in a
1368  * given keyboard state.
1369  *
1370  * This function is similar to xkb_state_key_get_syms(), but intended
1371  * for users which cannot or do not want to handle the case where
1372  * multiple keysyms are returned (in which case this function is
1373  * preferred).
1374  *
1375  * @returns The keysym.  If the key does not have exactly one keysym,
1376  * returns XKB_KEY_NoSymbol
1377  *
1378  * This function performs Capitalization @ref keysym-transformations.
1379  *
1380  * @sa xkb_state_key_get_syms()
1381  * @memberof xkb_state
1382  */
1383 xkb_keysym_t
1384 xkb_state_key_get_one_sym(struct xkb_state *state, xkb_keycode_t key);
1385 
1386 /**
1387  * Get the effective layout index for a key in a given keyboard state.
1388  *
1389  * @returns The layout index for the key in the given keyboard state.  If
1390  * the given keycode is invalid, or if the key is not included in any
1391  * layout at all, returns XKB_LAYOUT_INVALID.
1392  *
1393  * @invariant If the returned layout is valid, the following always holds:
1394  * @code
1395  * xkb_state_key_get_layout(state, key) < xkb_keymap_num_layouts_for_key(keymap, key)
1396  * @endcode
1397  *
1398  * @memberof xkb_state
1399  */
1400 xkb_layout_index_t
1401 xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t key);
1402 
1403 /**
1404  * Get the effective shift level for a key in a given keyboard state and
1405  * layout.
1406  *
1407  * @param state The keyboard state.
1408  * @param key The keycode of the key.
1409  * @param layout The layout for which to get the shift level.  This must be
1410  * smaller than:
1411  * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
1412  * usually it would be:
1413  * @code xkb_state_key_get_layout(state, key) @endcode
1414  *
1415  * @return The shift level index.  If the key or layout are invalid,
1416  * returns XKB_LEVEL_INVALID.
1417  *
1418  * @invariant If the returned level is valid, the following always holds:
1419  * @code
1420  * xkb_state_key_get_level(state, key, layout) < xkb_keymap_num_levels_for_key(keymap, key, layout)
1421  * @endcode
1422  *
1423  * @memberof xkb_state
1424  */
1425 xkb_level_index_t
1426 xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key,
1427                         xkb_layout_index_t layout);
1428 
1429 /**
1430  * Match flags for xkb_state_mod_indices_are_active() and
1431  * xkb_state_mod_names_are_active(), specifying the conditions for a
1432  * successful match.  XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with
1433  * the other modes.
1434  */
1435 enum xkb_state_match {
1436     /** Returns true if any of the modifiers are active. */
1437     XKB_STATE_MATCH_ANY = (1 << 0),
1438     /** Returns true if all of the modifiers are active. */
1439     XKB_STATE_MATCH_ALL = (1 << 1),
1440     /** Makes matching non-exclusive, i.e. will not return false if a
1441      *  modifier not specified in the arguments is active. */
1442     XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16)
1443 };
1444 
1445 /**
1446  * The counterpart to xkb_state_update_mask for modifiers, to be used on
1447  * the server side of serialization.
1448  *
1449  * @param state      The keyboard state.
1450  * @param components A mask of the modifier state components to serialize.
1451  * State components other than XKB_STATE_MODS_* are ignored.
1452  * If XKB_STATE_MODS_EFFECTIVE is included, all other state components are
1453  * ignored.
1454  *
1455  * @returns A xkb_mod_mask_t representing the given components of the
1456  * modifier state.
1457  *
1458  * This function should not be used in regular clients; please use the
1459  * xkb_state_mod_*_is_active API instead.
1460  *
1461  * @memberof xkb_state
1462  */
1463 xkb_mod_mask_t
1464 xkb_state_serialize_mods(struct xkb_state *state,
1465                          enum xkb_state_component components);
1466 
1467 /**
1468  * The counterpart to xkb_state_update_mask for layouts, to be used on
1469  * the server side of serialization.
1470  *
1471  * @param state      The keyboard state.
1472  * @param components A mask of the layout state components to serialize.
1473  * State components other than XKB_STATE_LAYOUT_* are ignored.
1474  * If XKB_STATE_LAYOUT_EFFECTIVE is included, all other state components are
1475  * ignored.
1476  *
1477  * @returns A layout index representing the given components of the
1478  * layout state.
1479  *
1480  * This function should not be used in regular clients; please use the
1481  * xkb_state_layout_*_is_active API instead.
1482  *
1483  * @memberof xkb_state
1484  */
1485 xkb_layout_index_t
1486 xkb_state_serialize_layout(struct xkb_state *state,
1487                            enum xkb_state_component components);
1488 
1489 /**
1490  * Test whether a modifier is active in a given keyboard state by name.
1491  *
1492  * @returns 1 if the modifier is active, 0 if it is not.  If the modifier
1493  * name does not exist in the keymap, returns -1.
1494  *
1495  * @memberof xkb_state
1496  */
1497 int
1498 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
1499                              enum xkb_state_component type);
1500 
1501 /**
1502  * Test whether a set of modifiers are active in a given keyboard state by
1503  * name.
1504  *
1505  * @param state The keyboard state.
1506  * @param type  The component of the state against which to match the
1507  * given modifiers.
1508  * @param match The manner by which to match the state against the
1509  * given modifiers.
1510  * @param ...   The set of of modifier names to test, terminated by a NULL
1511  * argument (sentinel).
1512  *
1513  * @returns 1 if the modifiers are active, 0 if they are not.  If any of
1514  * the modifier names do not exist in the keymap, returns -1.
1515  *
1516  * @memberof xkb_state
1517  */
1518 int
1519 xkb_state_mod_names_are_active(struct xkb_state *state,
1520                                enum xkb_state_component type,
1521                                enum xkb_state_match match,
1522                                ...);
1523 
1524 /**
1525  * Test whether a modifier is active in a given keyboard state by index.
1526  *
1527  * @returns 1 if the modifier is active, 0 if it is not.  If the modifier
1528  * index is invalid in the keymap, returns -1.
1529  *
1530  * @memberof xkb_state
1531  */
1532 int
1533 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
1534                               enum xkb_state_component type);
1535 
1536 /**
1537  * Test whether a set of modifiers are active in a given keyboard state by
1538  * index.
1539  *
1540  * @param state The keyboard state.
1541  * @param type  The component of the state against which to match the
1542  * given modifiers.
1543  * @param match The manner by which to match the state against the
1544  * given modifiers.
1545  * @param ...   The set of of modifier indices to test, terminated by a
1546  * XKB_MOD_INVALID argument (sentinel).
1547  *
1548  * @returns 1 if the modifiers are active, 0 if they are not.  If any of
1549  * the modifier indices are invalid in the keymap, returns -1.
1550  *
1551  * @memberof xkb_state
1552  */
1553 int
1554 xkb_state_mod_indices_are_active(struct xkb_state *state,
1555                                  enum xkb_state_component type,
1556                                  enum xkb_state_match match,
1557                                  ...);
1558 
1559 /**
1560  * @page consumed-modifiers Consumed Modifiers
1561  * @parblock
1562  *
1563  * Some functions, like xkb_state_key_get_syms(), look at the state of
1564  * the modifiers in the keymap and derive from it the correct shift level
1565  * to use for the key.  For example, in a US layout, pressing the key
1566  * labeled \<A\> while the Shift modifier is active, generates the keysym
1567  * 'A'.  In this case, the Shift modifier is said to be "consumed".
1568  * However, the Num Lock modifier does not affect this translation at all,
1569  * even if it is active, so it is not consumed by this translation.
1570  *
1571  * It may be desirable for some application to not reuse consumed modifiers
1572  * for further processing, e.g. for hotkeys or keyboard shortcuts.  To
1573  * understand why, consider some requirements from a standard shortcut
1574  * mechanism, and how they are implemented:
1575  *
1576  * 1. The shortcut's modifiers must match exactly to the state.  For
1577  *    example, it is possible to bind separate actions to \<Alt\>\<Tab\>
1578  *    and to \<Alt\>\<Shift\>\<Tab\>.  Further, if only \<Alt\>\<Tab\> is
1579  *    bound to an action, pressing \<Alt\>\<Shift\>\<Tab\> should not
1580  *    trigger the shortcut.
1581  *    Effectively, this means that the modifiers are compared using the
1582  *    equality operator (==).
1583  *
1584  * 2. Only relevant modifiers are considered for the matching.  For example,
1585  *    Caps Lock and Num Lock should not generally affect the matching, e.g.
1586  *    when matching \<Alt\>\<Tab\> against the state, it does not matter
1587  *    whether Num Lock is active or not.  These relevant, or "significant",
1588  *    modifiers usually include Alt, Control, Shift, Super and similar.
1589  *    Effectively, this means that non-significant modifiers are masked out,
1590  *    before doing the comparison as described above.
1591  *
1592  * 3. The matching must be independent of the layout/keymap.  For example,
1593  *    the \<Plus\> (+) symbol is found on the first level on some layouts,
1594  *    but requires holding Shift on others.  If you simply bind the action
1595  *    to the \<Plus\> keysym, it would work for the unshifted kind, but
1596  *    not for the others, because the match against Shift would fail.  If
1597  *    you bind the action to \<Shift\>\<Plus\>, only the shifted kind would
1598  *    work.  So what is needed is to recognize that Shift is used up in the
1599  *    translation of the keysym itself, and therefore should not be included
1600  *    in the matching.
1601  *    Effectively, this means that consumed modifiers (Shift in this example)
1602  *    are masked out as well, before doing the comparison.
1603  *
1604  * In summary, this is how the matching would be performed:
1605  * @code
1606  *   (keysym == shortcut_keysym) &&
1607  *   ((state_mods & ~consumed_mods & significant_mods) == shortcut_mods)
1608  * @endcode
1609  *
1610  * @c state_mods are the modifiers reported by
1611  * xkb_state_mod_index_is_active() and similar functions.
1612  * @c consumed_mods are the modifiers reported by
1613  * xkb_state_mod_index_is_consumed() and similar functions.
1614  * @c significant_mods are decided upon by the application/toolkit/user;
1615  * it is up to them to decide whether these are configurable or hard-coded.
1616  *
1617  * @endparblock
1618  */
1619 
1620 /**
1621  * Test whether a modifier is consumed by keyboard state translation for
1622  * a key.
1623  *
1624  * @returns 1 if the modifier is consumed, 0 if it is not.  If the modifier
1625  * index is not valid in the keymap, returns -1.
1626  *
1627  * @sa xkb_state_mod_mask_remove_consumed()
1628  * @sa xkb_state_key_get_consumed_mods()
1629  * @memberof xkb_state
1630  */
1631 int
1632 xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key,
1633                                 xkb_mod_index_t idx);
1634 
1635 /**
1636  * Remove consumed modifiers from a modifier mask for a key.
1637  *
1638  * Takes the given modifier mask, and removes all modifiers which are
1639  * consumed for that particular key (as in xkb_state_mod_index_is_consumed()).
1640  *
1641  * @sa xkb_state_mod_index_is_consumed()
1642  * @memberof xkb_state
1643  */
1644 xkb_mod_mask_t
1645 xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t key,
1646                                    xkb_mod_mask_t mask);
1647 
1648 /**
1649  * Get the mask of modifiers consumed by translating a given key.
1650  *
1651  * @returns a mask of the consumed modifiers.
1652  *
1653  * @sa xkb_state_mod_index_is_consumed()
1654  * @memberof xkb_state
1655  * @since 0.4.1
1656  */
1657 xkb_mod_mask_t
1658 xkb_state_key_get_consumed_mods(struct xkb_state *state, xkb_keycode_t key);
1659 
1660 /**
1661  * Test whether a layout is active in a given keyboard state by name.
1662  *
1663  * @returns 1 if the layout is active, 0 if it is not.  If no layout with
1664  * this name exists in the keymap, return -1.
1665  *
1666  * If multiple layouts in the keymap have this name, the one with the lowest
1667  * index is tested.
1668  *
1669  * @sa xkb_layout_index_t
1670  * @memberof xkb_state
1671  */
1672 int
1673 xkb_state_layout_name_is_active(struct xkb_state *state, const char *name,
1674                                 enum xkb_state_component type);
1675 
1676 /**
1677  * Test whether a layout is active in a given keyboard state by index.
1678  *
1679  * @returns 1 if the layout is active, 0 if it is not.  If the layout index
1680  * is not valid in the keymap, returns -1.
1681  *
1682  * @sa xkb_layout_index_t
1683  * @memberof xkb_state
1684  */
1685 int
1686 xkb_state_layout_index_is_active(struct xkb_state *state,
1687                                  xkb_layout_index_t idx,
1688                                  enum xkb_state_component type);
1689 
1690 /**
1691  * Test whether a LED is active in a given keyboard state by name.
1692  *
1693  * @returns 1 if the LED is active, 0 if it not.  If no LED with this name
1694  * exists in the keymap, returns -1.
1695  *
1696  * @sa xkb_led_index_t
1697  * @memberof xkb_state
1698  */
1699 int
1700 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
1701 
1702 /**
1703  * Test whether a LED is active in a given keyboard state by index.
1704  *
1705  * @returns 1 if the LED is active, 0 if it not.  If the LED index is not
1706  * valid in the keymap, returns -1.
1707  *
1708  * @sa xkb_led_index_t
1709  * @memberof xkb_state
1710  */
1711 int
1712 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
1713 
1714 /** @} */
1715 
1716 /* Leave this include last, so it can pick up our types, etc. */
1717 #include <xkbcommon/xkbcommon-compat.h>
1718 
1719 #ifdef __cplusplus
1720 } /* extern "C" */
1721 #endif
1722 
1723 #endif /* _XKBCOMMON_H_ */
1724