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	* The keymap defines a canonical name for each key, plus possible aliases.
156	* Historically, the XKB protocol restricts these names to at most 4 (ASCII)
157	* characters, but this library does not share this limit.
158	*
159	* @code
160	* xkb_keycode_t keycode_A = KEY_A + 8;
161	* @endcode
162	*
163	* @sa xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11()
164	*/
165	typedef uint32_t xkb_keycode_t;
166
167	/**
168	* A number used to represent the symbols generated from a key on a keyboard.
169	*
170	* A key, represented by a keycode, may generate different symbols according
171	* to keyboard state. For example, on a QWERTY keyboard, pressing the key
172	* labled \<A\> generates the symbol ‘a’. If the Shift key is held, it
173	* generates the symbol ‘A’. If a different layout is used, say Greek,
174	* it generates the symbol ‘α’. And so on.
175	*
176	* Each such symbol is represented by a *keysym* (short for “key symbol”).
177	* Note that keysyms are somewhat more general, in that they can also represent
178	* some “function”, such as “Left” or “Right” for the arrow keys. For more
179	* information, see: Appendix A [“KEYSYM Encoding”][encoding] of the X Window
180	* System Protocol.
181	*
182	* Specifically named keysyms can be found in the
183	* xkbcommon/xkbcommon-keysyms.h header file. Their name does not include
184	* the `XKB_KEY_` prefix.
185	*
186	* Besides those, any Unicode/ISO&nbsp;10646 character in the range U+0100 to
187	* U+10FFFF can be represented by a keysym value in the range 0x01000100 to
188	* 0x0110FFFF. The name of Unicode keysyms is `U<codepoint>`, e.g. `UA1B2`.
189	*
190	* The name of other unnamed keysyms is the hexadecimal representation of
191	* their value, e.g. `0xabcd1234`.
192	*
193	* Keysym names are case-sensitive.
194	*
195	* @note **Encoding:** Keysyms are 32-bit integers with the 3 most significant
196	* bits always set to zero. See: Appendix A [“KEYSYM Encoding”][encoding] of
197	* the X Window System Protocol.
198	*
199	* [encoding]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#keysym_encoding
200	*
201	* @ingroup keysyms
202	* @sa XKB_KEYSYM_MAX
203	*/
204	typedef uint32_t xkb_keysym_t;
205
206	/**
207	* Index of a keyboard layout.
208	*
209	* The layout index is a state component which detemines which <em>keyboard
210	* layout</em> is active. These may be different alphabets, different key
211	* arrangements, etc.
212	*
213	* Layout indices are consecutive. The first layout has index 0.
214	*
215	* Each layout is not required to have a name, and the names are not
216	* guaranteed to be unique (though they are usually provided and unique).
217	* Therefore, it is not safe to use the name as a unique identifier for a
218	* layout. Layout names are case-sensitive.
219	*
220	* Layout names are specified in the layout's definition, for example
221	* "English (US)". These are different from the (conventionally) short names
222	* which are used to locate the layout, for example "us" or "us(intl)". These
223	* names are not present in a compiled keymap.
224	*
225	* If the user selects layouts from a list generated from the XKB registry
226	* (using libxkbregistry or directly), and this metadata is needed later on, it
227	* is recommended to store it along with the keymap.
228	*
229	* Layouts are also called "groups" by XKB.
230	*
231	* @sa xkb_keymap_num_layouts() xkb_keymap_num_layouts_for_key()
232	*/
233	typedef uint32_t xkb_layout_index_t;
234	/** A mask of layout indices. */
235	typedef uint32_t xkb_layout_mask_t;
236
237	/**
238	* Index of a shift level.
239	*
240	* Any key, in any layout, can have several <em>shift levels</em>. Each
241	* shift level can assign different keysyms to the key. The shift level
242	* to use is chosen according to the current keyboard state; for example,
243	* if no keys are pressed, the first level may be used; if the Left Shift
244	* key is pressed, the second; if Num Lock is pressed, the third; and
245	* many such combinations are possible (see xkb_mod_index_t).
246	*
247	* Level indices are consecutive. The first level has index 0.
248	*/
249	typedef uint32_t xkb_level_index_t;
250
251	/**
252	* Index of a modifier.
253	*
254	* A @e modifier is a state component which changes the way keys are
255	* interpreted. A keymap defines a set of modifiers, such as Alt, Shift,
256	* Num Lock or Meta, and specifies which keys may @e activate which
257	* modifiers (in a many-to-many relationship, i.e. a key can activate
258	* several modifiers, and a modifier may be activated by several keys.
259	* Different keymaps do this differently).
260	*
261	* When retrieving the keysyms for a key, the active modifier set is
262	* consulted; this detemines the correct shift level to use within the
263	* currently active layout (see xkb_level_index_t).
264	*
265	* Modifier indices are consecutive. The first modifier has index 0.
266	*
267	* Each modifier must have a name, and the names are unique. Therefore, it
268	* is safe to use the name as a unique identifier for a modifier. The names
269	* of some common modifiers are provided in the xkbcommon/xkbcommon-names.h
270	* header file. Modifier names are case-sensitive.
271	*
272	* @sa xkb_keymap_num_mods()
273	*/
274	typedef uint32_t xkb_mod_index_t;
275	/** A mask of modifier indices. */
276	typedef uint32_t xkb_mod_mask_t;
277
278	/**
279	* Index of a keyboard LED.
280	*
281	* LEDs are logical objects which may be @e active or @e inactive. They
282	* typically correspond to the lights on the keyboard. Their state is
283	* determined by the current keyboard state.
284	*
285	* LED indices are non-consecutive. The first LED has index 0.
286	*
287	* Each LED must have a name, and the names are unique. Therefore,
288	* it is safe to use the name as a unique identifier for a LED. The names
289	* of some common LEDs are provided in the xkbcommon/xkbcommon-names.h
290	* header file. LED names are case-sensitive.
291	*
292	* @warning A given keymap may specify an exact index for a given LED.
293	* Therefore, LED indexing is not necessarily sequential, as opposed to
294	* modifiers and layouts. This means that when iterating over the LEDs
295	* in a keymap using e.g. xkb_keymap_num_leds(), some indices might be
296	* invalid. Given such an index, functions like xkb_keymap_led_get_name()
297	* will return NULL, and xkb_state_led_index_is_active() will return -1.
298	*
299	* LEDs are also called "indicators" by XKB.
300	*
301	* @sa xkb_keymap_num_leds()
302	*/
303	typedef uint32_t xkb_led_index_t;
304	/** A mask of LED indices. */
305	typedef uint32_t xkb_led_mask_t;
306
307	#define XKB_KEYCODE_INVALID (0xffffffff)
308	#define XKB_LAYOUT_INVALID (0xffffffff)
309	#define XKB_LEVEL_INVALID (0xffffffff)
310	#define XKB_MOD_INVALID (0xffffffff)
311	#define XKB_LED_INVALID (0xffffffff)
312
313	#define XKB_KEYCODE_MAX (0xffffffff - 1)
314
315	/**
316	* Maximum keysym value
317	*
318	* @since 1.6.0
319	* @sa xkb_keysym_t
320	* @ingroup keysyms
321	*/
322	#define XKB_KEYSYM_MAX 0x1fffffff
323
324	/**
325	* Test whether a value is a valid extended keycode.
326	* @sa xkb_keycode_t
327	**/
328	#define xkb_keycode_is_legal_ext(key) (key <= XKB_KEYCODE_MAX)
329
330	/**
331	* Test whether a value is a valid X11 keycode.
332	* @sa xkb_keycode_t
333	*/
334	#define xkb_keycode_is_legal_x11(key) (key >= 8 && key <= 255)
335
336	/**
337	* Names to compile a keymap with, also known as RMLVO.
338	*
339	* The names are the common configuration values by which a user picks
340	* a keymap.
341	*
342	* If the entire struct is NULL, then each field is taken to be NULL.
343	* You should prefer passing NULL instead of choosing your own defaults.
344	*/
345	struct xkb_rule_names {
346	/**
347	* The rules file to use. The rules file describes how to interpret
348	* the values of the model, layout, variant and options fields.
349	*
350	* If NULL or the empty string "", a default value is used.
351	* If the XKB_DEFAULT_RULES environment variable is set, it is used
352	* as the default. Otherwise the system default is used.
353	*/
354	const char *rules;
355	/**
356	* The keyboard model by which to interpret keycodes and LEDs.
357	*
358	* If NULL or the empty string "", a default value is used.
359	* If the XKB_DEFAULT_MODEL environment variable is set, it is used
360	* as the default. Otherwise the system default is used.
361	*/
362	const char *model;
363	/**
364	* A comma separated list of layouts (languages) to include in the
365	* keymap.
366	*
367	* If NULL or the empty string "", a default value is used.
368	* If the XKB_DEFAULT_LAYOUT environment variable is set, it is used
369	* as the default. Otherwise the system default is used.
370	*/
371	const char *layout;
372	/**
373	* A comma separated list of variants, one per layout, which may
374	* modify or augment the respective layout in various ways.
375	*
376	* Generally, should either be empty or have the same number of values
377	* as the number of layouts. You may use empty values as in "intl,,neo".
378	*
379	* If NULL or the empty string "", and a default value is also used
380	* for the layout, a default value is used. Otherwise no variant is
381	* used.
382	* If the XKB_DEFAULT_VARIANT environment variable is set, it is used
383	* as the default. Otherwise the system default is used.
384	*/
385	const char *variant;
386	/**
387	* A comma separated list of options, through which the user specifies
388	* non-layout related preferences, like which key combinations are used
389	* for switching layouts, or which key is the Compose key.
390	*
391	* If NULL, a default value is used. If the empty string "", no
392	* options are used.
393	* If the XKB_DEFAULT_OPTIONS environment variable is set, it is used
394	* as the default. Otherwise the system default is used.
395	*/
396	const char *options;
397	};
398
399	/**
400	* @defgroup keysyms Keysyms
401	* Utility functions related to *keysyms* (short for “key symbols”).
402	*
403	* @{
404	*/
405
406	/**
407	* @page keysym-transformations Keysym Transformations
408	*
409	* Keysym translation is subject to several "keysym transformations",
410	* as described in the XKB specification. These are:
411	*
412	* - Capitalization transformation. If the Caps Lock modifier is
413	* active and was not consumed by the translation process, a single
414	* keysym is transformed to its upper-case form (if applicable).
415	* Similarly, the UTF-8/UTF-32 string produced is capitalized.
416	*
417	* This is described in:
418	* https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Lock_Modifier
419	*
420	* - Control transformation. If the Control modifier is active and
421	* was not consumed by the translation process, the string produced
422	* is transformed to its matching ASCII control character (if
423	* applicable). Keysyms are not affected.
424	*
425	* This is described in:
426	* https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier
427	*
428	* Each relevant function discusses which transformations it performs.
429	*
430	* These transformations are not applicable when a key produces multiple
431	* keysyms.
432	*/
433
434
435	/**
436	* Get the name of a keysym.
437	*
438	* For a description of how keysyms are named, see @ref xkb_keysym_t.
439	*
440	* @param[in] keysym The keysym.
441	* @param[out] buffer A string buffer to write the name into.
442	* @param[in] size Size of the buffer.
443	*
444	* @warning If the buffer passed is too small, the string is truncated
445	* (though still NUL-terminated); a size of at least 64 bytes is recommended.
446	*
447	* @returns The number of bytes in the name, excluding the NUL byte. If
448	* the keysym is invalid, returns -1.
449	*
450	* You may check if truncation has occurred by comparing the return value
451	* with the length of buffer, similarly to the snprintf(3) function.
452	*
453	* @sa xkb_keysym_t
454	*/
455	int
456	xkb_keysym_get_name(xkb_keysym_t keysym, char *buffer, size_t size);
457
458	/** Flags for xkb_keysym_from_name(). */
459	enum xkb_keysym_flags {
460	/** Do not apply any flags. */
461	XKB_KEYSYM_NO_FLAGS = 0,
462	/** Find keysym by case-insensitive search. */
463	XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0)
464	};
465
466	/**
467	* Get a keysym from its name.
468	*
469	* @param name The name of a keysym. See remarks in xkb_keysym_get_name();
470	* this function will accept any name returned by that function.
471	* @param flags A set of flags controlling how the search is done. If
472	* invalid flags are passed, this will fail with XKB_KEY_NoSymbol.
473	*
474	* If you use the XKB_KEYSYM_CASE_INSENSITIVE flag and two keysym names
475	* differ only by case, then the lower-case keysym is returned. For
476	* instance, for KEY_a and KEY_A, this function would return KEY_a for the
477	* case-insensitive search. If this functionality is needed, it is
478	* recommended to first call this function without this flag; and if that
479	* fails, only then to try with this flag, while possibly warning the user
480	* he had misspelled the name, and might get wrong results.
481	*
482	* Case folding is done according to the C locale; the current locale is not
483	* consulted.
484	*
485	* @returns The keysym. If the name is invalid, returns XKB_KEY_NoSymbol.
486	*
487	* @sa xkb_keysym_t
488	*/
489	xkb_keysym_t
490	xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags);
491
492	/**
493	* Get the Unicode/UTF-8 representation of a keysym.
494	*
495	* @param[in] keysym The keysym.
496	* @param[out] buffer A buffer to write the UTF-8 string into.
497	* @param[in] size The size of buffer. Must be at least 7.
498	*
499	* @returns The number of bytes written to the buffer (including the
500	* terminating byte). If the keysym does not have a Unicode
501	* representation, returns 0. If the buffer is too small, returns -1.
502	*
503	* This function does not perform any @ref keysym-transformations.
504	* Therefore, prefer to use xkb_state_key_get_utf8() if possible.
505	*
506	* @sa xkb_state_key_get_utf8()
507	*/
508	int
509	xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size);
510
511	/**
512	* Get the Unicode/UTF-32 representation of a keysym.
513	*
514	* @returns The Unicode/UTF-32 representation of keysym, which is also
515	* compatible with UCS-4. If the keysym does not have a Unicode
516	* representation, returns 0.
517	*
518	* This function does not perform any @ref keysym-transformations.
519	* Therefore, prefer to use xkb_state_key_get_utf32() if possible.
520	*
521	* @sa xkb_state_key_get_utf32()
522	*/
523	uint32_t
524	xkb_keysym_to_utf32(xkb_keysym_t keysym);
525
526	/**
527	* Get the keysym corresponding to a Unicode/UTF-32 codepoint.
528	*
529	* @returns The keysym corresponding to the specified Unicode
530	* codepoint, or XKB_KEY_NoSymbol if there is none.
531	*
532	* This function is the inverse of @ref xkb_keysym_to_utf32. In cases
533	* where a single codepoint corresponds to multiple keysyms, returns
534	* the keysym with the lowest value.
535	*
536	* Unicode codepoints which do not have a special (legacy) keysym
537	* encoding use a direct encoding scheme. These keysyms don't usually
538	* have an associated keysym constant (XKB_KEY_*).
539	*
540	* For noncharacter Unicode codepoints and codepoints outside of the
541	* defined Unicode planes this function returns XKB_KEY_NoSymbol.
542	*
543	* @sa xkb_keysym_to_utf32()
544	* @since 1.0.0
545	*/
546	xkb_keysym_t
547	xkb_utf32_to_keysym(uint32_t ucs);
548
549	/**
550	* Convert a keysym to its uppercase form.
551	*
552	* If there is no such form, the keysym is returned unchanged.
553	*
554	* The conversion rules may be incomplete; prefer to work with the Unicode
555	* representation instead, when possible.
556	*/
557	xkb_keysym_t
558	xkb_keysym_to_upper(xkb_keysym_t ks);
559
560	/**
561	* Convert a keysym to its lowercase form.
562	*
563	* The conversion rules may be incomplete; prefer to work with the Unicode
564	* representation instead, when possible.
565	*/
566	xkb_keysym_t
567	xkb_keysym_to_lower(xkb_keysym_t ks);
568
569	/** @} */
570
571	/**
572	* @defgroup context Library Context
573	* Creating, destroying and using library contexts.
574	*
575	* Every keymap compilation request must have a context associated with
576	* it. The context keeps around state such as the include path.
577	*
578	* @{
579	*/
580
581	/**
582	* @page envvars Environment Variables
583	*
584	* The user may set some environment variables which affect the library:
585	*
586	* - `XKB_CONFIG_ROOT`, `XKB_CONFIG_EXTRA_PATH`, `XDG_CONFIG_DIR`, `HOME` - see @ref include-path.
587	* - `XKB_LOG_LEVEL` - see xkb_context_set_log_level().
588	* - `XKB_LOG_VERBOSITY` - see xkb_context_set_log_verbosity().
589	* - `XKB_DEFAULT_RULES`, `XKB_DEFAULT_MODEL`, `XKB_DEFAULT_LAYOUT`,
590	* `XKB_DEFAULT_VARIANT`, `XKB_DEFAULT_OPTIONS` - see xkb_rule_names.
591	*/
592
593	/** Flags for context creation. */
594	enum xkb_context_flags {
595	/** Do not apply any context flags. */
596	XKB_CONTEXT_NO_FLAGS = 0,
597	/** Create this context with an empty include path. */
598	XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
599	/**
600	* Don't take RMLVO names from the environment.
601	*
602	* @since 0.3.0
603	*/
604	XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1),
605	/**
606	* Disable the use of secure_getenv for this context, so that privileged
607	* processes can use environment variables. Client uses at their own risk.
608	*
609	* @since 1.5.0
610	*/
611	XKB_CONTEXT_NO_SECURE_GETENV = (1 << 2)
612	};
613
614	/**
615	* Create a new context.
616	*
617	* @param flags Optional flags for the context, or 0.
618	*
619	* @returns A new context, or NULL on failure.
620	*
621	* @memberof xkb_context
622	*/
623	struct xkb_context *
624	xkb_context_new(enum xkb_context_flags flags);
625
626	/**
627	* Take a new reference on a context.
628	*
629	* @returns The passed in context.
630	*
631	* @memberof xkb_context
632	*/
633	struct xkb_context *
634	xkb_context_ref(struct xkb_context *context);
635
636	/**
637	* Release a reference on a context, and possibly free it.
638	*
639	* @param context The context. If it is NULL, this function does nothing.
640	*
641	* @memberof xkb_context
642	*/
643	void
644	xkb_context_unref(struct xkb_context *context);
645
646	/**
647	* Store custom user data in the context.
648	*
649	* This may be useful in conjunction with xkb_context_set_log_fn() or other
650	* callbacks.
651	*
652	* @memberof xkb_context
653	*/
654	void
655	xkb_context_set_user_data(struct xkb_context *context, void *user_data);
656
657	/**
658	* Retrieves stored user data from the context.
659	*
660	* @returns The stored user data. If the user data wasn't set, or the
661	* passed in context is NULL, returns NULL.
662	*
663	* This may be useful to access private user data from callbacks like a
664	* custom logging function.
665	*
666	* @memberof xkb_context
667	**/
668	void *
669	xkb_context_get_user_data(struct xkb_context *context);
670
671	/** @} */
672
673	/**
674	* @defgroup include-path Include Paths
675	* Manipulating the include paths in a context.
676	*
677	* The include paths are the file-system paths that are searched when an
678	* include statement is encountered during keymap compilation.
679	*
680	* The default include paths are, in that lookup order:
681	* - The path `$XDG_CONFIG_HOME/xkb`, with the usual `XDG_CONFIG_HOME`
682	* fallback to `$HOME/.config/` if unset.
683	* - The path `$HOME/.xkb`, where $HOME is the value of the environment
684	* variable `HOME`.
685	* - The `XKB_CONFIG_EXTRA_PATH` environment variable, if defined, otherwise the
686	* system configuration directory, defined at library configuration time
687	* (usually `/etc/xkb`).
688	* - The `XKB_CONFIG_ROOT` environment variable, if defined, otherwise
689	* the system XKB root, defined at library configuration time.
690	*
691	* @{
692	*/
693
694	/**
695	* Append a new entry to the context's include path.
696	*
697	* @returns 1 on success, or 0 if the include path could not be added or is
698	* inaccessible.
699	*
700	* @memberof xkb_context
701	*/
702	int
703	xkb_context_include_path_append(struct xkb_context *context, const char *path);
704
705	/**
706	* Append the default include paths to the context's include path.
707	*
708	* @returns 1 on success, or 0 if the primary include path could not be added.
709	*
710	* @memberof xkb_context
711	*/
712	int
713	xkb_context_include_path_append_default(struct xkb_context *context);
714
715	/**
716	* Reset the context's include path to the default.
717	*
718	* Removes all entries from the context's include path, and inserts the
719	* default paths.
720	*
721	* @returns 1 on success, or 0 if the primary include path could not be added.
722	*
723	* @memberof xkb_context
724	*/
725	int
726	xkb_context_include_path_reset_defaults(struct xkb_context *context);
727
728	/**
729	* Remove all entries from the context's include path.
730	*
731	* @memberof xkb_context
732	*/
733	void
734	xkb_context_include_path_clear(struct xkb_context *context);
735
736	/**
737	* Get the number of paths in the context's include path.
738	*
739	* @memberof xkb_context
740	*/
741	unsigned int
742	xkb_context_num_include_paths(struct xkb_context *context);
743
744	/**
745	* Get a specific include path from the context's include path.
746	*
747	* @returns The include path at the specified index. If the index is
748	* invalid, returns NULL.
749	*
750	* @memberof xkb_context
751	*/
752	const char *
753	xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
754
755	/** @} */
756
757	/**
758	* @defgroup logging Logging Handling
759	* Manipulating how logging from this library is handled.
760	*
761	* @{
762	*/
763
764	/** Specifies a logging level. */
765	enum xkb_log_level {
766	XKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
767	XKB_LOG_LEVEL_ERROR = 20, /**< Log all errors. */
768	XKB_LOG_LEVEL_WARNING = 30, /**< Log warnings and errors. */
769	XKB_LOG_LEVEL_INFO = 40, /**< Log information, warnings, and errors. */
770	XKB_LOG_LEVEL_DEBUG = 50 /**< Log everything. */
771	};
772
773	/**
774	* Set the current logging level.
775	*
776	* @param context The context in which to set the logging level.
777	* @param level The logging level to use. Only messages from this level
778	* and below will be logged.
779	*
780	* The default level is XKB_LOG_LEVEL_ERROR. The environment variable
781	* XKB_LOG_LEVEL, if set in the time the context was created, overrides the
782	* default value. It may be specified as a level number or name.
783	*
784	* @memberof xkb_context
785	*/
786	void
787	xkb_context_set_log_level(struct xkb_context *context,
788	enum xkb_log_level level);
789
790	/**
791	* Get the current logging level.
792	*
793	* @memberof xkb_context
794	*/
795	enum xkb_log_level
796	xkb_context_get_log_level(struct xkb_context *context);
797
798	/**
799	* Sets the current logging verbosity.
800	*
801	* The library can generate a number of warnings which are not helpful to
802	* ordinary users of the library. The verbosity may be increased if more
803	* information is desired (e.g. when developing a new keymap).
804	*
805	* The default verbosity is 0. The environment variable XKB_LOG_VERBOSITY,
806	* if set in the time the context was created, overrides the default value.
807	*
808	* @param context The context in which to use the set verbosity.
809	* @param verbosity The verbosity to use. Currently used values are
810	* 1 to 10, higher values being more verbose. 0 would result in no verbose
811	* messages being logged.
812	*
813	* Most verbose messages are of level XKB_LOG_LEVEL_WARNING or lower.
814	*
815	* @memberof xkb_context
816	*/
817	void
818	xkb_context_set_log_verbosity(struct xkb_context *context, int verbosity);
819
820	/**
821	* Get the current logging verbosity of the context.
822	*
823	* @memberof xkb_context
824	*/
825	int
826	xkb_context_get_log_verbosity(struct xkb_context *context);
827
828	/**
829	* Set a custom function to handle logging messages.
830	*
831	* @param context The context in which to use the set logging function.
832	* @param log_fn The function that will be called for logging messages.
833	* Passing NULL restores the default function, which logs to stderr.
834	*
835	* By default, log messages from this library are printed to stderr. This
836	* function allows you to replace the default behavior with a custom
837	* handler. The handler is only called with messages which match the
838	* current logging level and verbosity settings for the context.
839	* level is the logging level of the message. @a format and @a args are
840	* the same as in the vprintf(3) function.
841	*
842	* You may use xkb_context_set_user_data() on the context, and then call
843	* xkb_context_get_user_data() from within the logging function to provide
844	* it with additional private context.
845	*
846	* @memberof xkb_context
847	*/
848	void
849	xkb_context_set_log_fn(struct xkb_context *context,
850	void (*log_fn)(struct xkb_context *context,
851	enum xkb_log_level level,
852	const char *format, va_list args));
853
854	/** @} */
855
856	/**
857	* @defgroup keymap Keymap Creation
858	* Creating and destroying keymaps.
859	*
860	* @{
861	*/
862
863	/** Flags for keymap compilation. */
864	enum xkb_keymap_compile_flags {
865	/** Do not apply any flags. */
866	XKB_KEYMAP_COMPILE_NO_FLAGS = 0
867	};
868
869	/**
870	* Create a keymap from RMLVO names.
871	*
872	* The primary keymap entry point: creates a new XKB keymap from a set of
873	* RMLVO (Rules + Model + Layouts + Variants + Options) names.
874	*
875	* @param context The context in which to create the keymap.
876	* @param names The RMLVO names to use. See xkb_rule_names.
877	* @param flags Optional flags for the keymap, or 0.
878	*
879	* @returns A keymap compiled according to the RMLVO names, or NULL if
880	* the compilation failed.
881	*
882	* @sa xkb_rule_names
883	* @memberof xkb_keymap
884	*/
885	struct xkb_keymap *
886	xkb_keymap_new_from_names(struct xkb_context *context,
887	const struct xkb_rule_names *names,
888	enum xkb_keymap_compile_flags flags);
889
890	/** The possible keymap formats. */
891	enum xkb_keymap_format {
892	/** The current/classic XKB text format, as generated by xkbcomp -xkb. */
893	XKB_KEYMAP_FORMAT_TEXT_V1 = 1
894	};
895
896	/**
897	* Create a keymap from a keymap file.
898	*
899	* @param context The context in which to create the keymap.
900	* @param file The keymap file to compile.
901	* @param format The text format of the keymap file to compile.
902	* @param flags Optional flags for the keymap, or 0.
903	*
904	* @returns A keymap compiled from the given XKB keymap file, or NULL if
905	* the compilation failed.
906	*
907	* The file must contain a complete keymap. For example, in the
908	* XKB_KEYMAP_FORMAT_TEXT_V1 format, this means the file must contain one
909	* top level '%xkb_keymap' section, which in turn contains other required
910	* sections.
911	*
912	* @memberof xkb_keymap
913	*/
914	struct xkb_keymap *
915	xkb_keymap_new_from_file(struct xkb_context *context, FILE *file,
916	enum xkb_keymap_format format,
917	enum xkb_keymap_compile_flags flags);
918
919	/**
920	* Create a keymap from a keymap string.
921	*
922	* This is just like xkb_keymap_new_from_file(), but instead of a file, gets
923	* the keymap as one enormous string.
924	*
925	* @see xkb_keymap_new_from_file()
926	* @memberof xkb_keymap
927	*/
928	struct xkb_keymap *
929	xkb_keymap_new_from_string(struct xkb_context *context, const char *string,
930	enum xkb_keymap_format format,
931	enum xkb_keymap_compile_flags flags);
932
933	/**
934	* Create a keymap from a memory buffer.
935	*
936	* This is just like xkb_keymap_new_from_string(), but takes a length argument
937	* so the input string does not have to be zero-terminated.
938	*
939	* @see xkb_keymap_new_from_string()
940	* @memberof xkb_keymap
941	* @since 0.3.0
942	*/
943	struct xkb_keymap *
944	xkb_keymap_new_from_buffer(struct xkb_context *context, const char *buffer,
945	size_t length, enum xkb_keymap_format format,
946	enum xkb_keymap_compile_flags flags);
947
948	/**
949	* Take a new reference on a keymap.
950	*
951	* @returns The passed in keymap.
952	*
953	* @memberof xkb_keymap
954	*/
955	struct xkb_keymap *
956	xkb_keymap_ref(struct xkb_keymap *keymap);
957
958	/**
959	* Release a reference on a keymap, and possibly free it.
960	*
961	* @param keymap The keymap. If it is NULL, this function does nothing.
962	*
963	* @memberof xkb_keymap
964	*/
965	void
966	xkb_keymap_unref(struct xkb_keymap *keymap);
967
968	/**
969	* Get the keymap as a string in the format from which it was created.
970	* @sa xkb_keymap_get_as_string()
971	**/
972	#define XKB_KEYMAP_USE_ORIGINAL_FORMAT ((enum xkb_keymap_format) -1)
973
974	/**
975	* Get the compiled keymap as a string.
976	*
977	* @param keymap The keymap to get as a string.
978	* @param format The keymap format to use for the string. You can pass
979	* in the special value XKB_KEYMAP_USE_ORIGINAL_FORMAT to use the format
980	* from which the keymap was originally created.
981	*
982	* @returns The keymap as a NUL-terminated string, or NULL if unsuccessful.
983	*
984	* The returned string may be fed back into xkb_keymap_new_from_string() to get
985	* the exact same keymap (possibly in another process, etc.).
986	*
987	* The returned string is dynamically allocated and should be freed by the
988	* caller.
989	*
990	* @memberof xkb_keymap
991	*/
992	char *
993	xkb_keymap_get_as_string(struct xkb_keymap *keymap,
994	enum xkb_keymap_format format);
995
996	/** @} */
997
998	/**
999	* @defgroup components Keymap Components
1000	* Enumeration of state components in a keymap.
1001	*
1002	* @{
1003	*/
1004
1005	/**
1006	* Get the minimum keycode in the keymap.
1007	*
1008	* @sa xkb_keycode_t
1009	* @memberof xkb_keymap
1010	* @since 0.3.1
1011	*/
1012	xkb_keycode_t
1013	xkb_keymap_min_keycode(struct xkb_keymap *keymap);
1014
1015	/**
1016	* Get the maximum keycode in the keymap.
1017	*
1018	* @sa xkb_keycode_t
1019	* @memberof xkb_keymap
1020	* @since 0.3.1
1021	*/
1022	xkb_keycode_t
1023	xkb_keymap_max_keycode(struct xkb_keymap *keymap);
1024
1025	/**
1026	* The iterator used by xkb_keymap_key_for_each().
1027	*
1028	* @sa xkb_keymap_key_for_each
1029	* @memberof xkb_keymap
1030	* @since 0.3.1
1031	*/
1032	typedef void
1033	(*xkb_keymap_key_iter_t)(struct xkb_keymap *keymap, xkb_keycode_t key,
1034	void *data);
1035
1036	/**
1037	* Run a specified function for every valid keycode in the keymap. If a
1038	* keymap is sparse, this function may be called fewer than
1039	* (max_keycode - min_keycode + 1) times.
1040	*
1041	* @sa xkb_keymap_min_keycode() xkb_keymap_max_keycode() xkb_keycode_t
1042	* @memberof xkb_keymap
1043	* @since 0.3.1
1044	*/
1045	void
1046	xkb_keymap_key_for_each(struct xkb_keymap *keymap, xkb_keymap_key_iter_t iter,
1047	void *data);
1048
1049	/**
1050	* Find the name of the key with the given keycode.
1051	*
1052	* This function always returns the canonical name of the key (see
1053	* description in xkb_keycode_t).
1054	*
1055	* @returns The key name. If no key with this keycode exists,
1056	* returns NULL.
1057	*
1058	* @sa xkb_keycode_t
1059	* @memberof xkb_keymap
1060	* @since 0.6.0
1061	*/
1062	const char *
1063	xkb_keymap_key_get_name(struct xkb_keymap *keymap, xkb_keycode_t key);
1064
1065	/**
1066	* Find the keycode of the key with the given name.
1067	*
1068	* The name can be either a canonical name or an alias.
1069	*
1070	* @returns The keycode. If no key with this name exists,
1071	* returns XKB_KEYCODE_INVALID.
1072	*
1073	* @sa xkb_keycode_t
1074	* @memberof xkb_keymap
1075	* @since 0.6.0
1076	*/
1077	xkb_keycode_t
1078	xkb_keymap_key_by_name(struct xkb_keymap *keymap, const char *name);
1079
1080	/**
1081	* Get the number of modifiers in the keymap.
1082	*
1083	* @sa xkb_mod_index_t
1084	* @memberof xkb_keymap
1085	*/
1086	xkb_mod_index_t
1087	xkb_keymap_num_mods(struct xkb_keymap *keymap);
1088
1089	/**
1090	* Get the name of a modifier by index.
1091	*
1092	* @returns The name. If the index is invalid, returns NULL.
1093	*
1094	* @sa xkb_mod_index_t
1095	* @memberof xkb_keymap
1096	*/
1097	const char *
1098	xkb_keymap_mod_get_name(struct xkb_keymap *keymap, xkb_mod_index_t idx);
1099
1100	/**
1101	* Get the index of a modifier by name.
1102	*
1103	* @returns The index. If no modifier with this name exists, returns
1104	* XKB_MOD_INVALID.
1105	*
1106	* @sa xkb_mod_index_t
1107	* @memberof xkb_keymap
1108	*/
1109	xkb_mod_index_t
1110	xkb_keymap_mod_get_index(struct xkb_keymap *keymap, const char *name);
1111
1112	/**
1113	* Get the number of layouts in the keymap.
1114	*
1115	* @sa xkb_layout_index_t xkb_rule_names xkb_keymap_num_layouts_for_key()
1116	* @memberof xkb_keymap
1117	*/
1118	xkb_layout_index_t
1119	xkb_keymap_num_layouts(struct xkb_keymap *keymap);
1120
1121	/**
1122	* Get the name of a layout by index.
1123	*
1124	* @returns The name. If the index is invalid, or the layout does not have
1125	* a name, returns NULL.
1126	*
1127	* @sa xkb_layout_index_t
1128	* For notes on layout names.
1129	* @memberof xkb_keymap
1130	*/
1131	const char *
1132	xkb_keymap_layout_get_name(struct xkb_keymap *keymap, xkb_layout_index_t idx);
1133
1134	/**
1135	* Get the index of a layout by name.
1136	*
1137	* @returns The index. If no layout exists with this name, returns
1138	* XKB_LAYOUT_INVALID. If more than one layout in the keymap has this name,
1139	* returns the lowest index among them.
1140	*
1141	* @sa xkb_layout_index_t
1142	* For notes on layout names.
1143	* @memberof xkb_keymap
1144	*/
1145	xkb_layout_index_t
1146	xkb_keymap_layout_get_index(struct xkb_keymap *keymap, const char *name);
1147
1148	/**
1149	* Get the number of LEDs in the keymap.
1150	*
1151	* @warning The range [ 0...xkb_keymap_num_leds() ) includes all of the LEDs
1152	* in the keymap, but may also contain inactive LEDs. When iterating over
1153	* this range, you need the handle this case when calling functions such as
1154	* xkb_keymap_led_get_name() or xkb_state_led_index_is_active().
1155	*
1156	* @sa xkb_led_index_t
1157	* @memberof xkb_keymap
1158	*/
1159	xkb_led_index_t
1160	xkb_keymap_num_leds(struct xkb_keymap *keymap);
1161
1162	/**
1163	* Get the name of a LED by index.
1164	*
1165	* @returns The name. If the index is invalid, returns NULL.
1166	*
1167	* @memberof xkb_keymap
1168	*/
1169	const char *
1170	xkb_keymap_led_get_name(struct xkb_keymap *keymap, xkb_led_index_t idx);
1171
1172	/**
1173	* Get the index of a LED by name.
1174	*
1175	* @returns The index. If no LED with this name exists, returns
1176	* XKB_LED_INVALID.
1177	*
1178	* @memberof xkb_keymap
1179	*/
1180	xkb_led_index_t
1181	xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name);
1182
1183	/**
1184	* Get the number of layouts for a specific key.
1185	*
1186	* This number can be different from xkb_keymap_num_layouts(), but is always
1187	* smaller. It is the appropriate value to use when iterating over the
1188	* layouts of a key.
1189	*
1190	* @sa xkb_layout_index_t
1191	* @memberof xkb_keymap
1192	*/
1193	xkb_layout_index_t
1194	xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key);
1195
1196	/**
1197	* Get the number of shift levels for a specific key and layout.
1198	*
1199	* If @c layout is out of range for this key (that is, larger or equal to
1200	* the value returned by xkb_keymap_num_layouts_for_key()), it is brought
1201	* back into range in a manner consistent with xkb_state_key_get_layout().
1202	*
1203	* @sa xkb_level_index_t
1204	* @memberof xkb_keymap
1205	*/
1206	xkb_level_index_t
1207	xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key,
1208	xkb_layout_index_t layout);
1209
1210	/**
1211	* Retrieves every possible modifier mask that produces the specified
1212	* shift level for a specific key and layout.
1213	*
1214	* This API is useful for inverse key transformation; i.e. finding out
1215	* which modifiers need to be active in order to be able to type the
1216	* keysym(s) corresponding to the specific key code, layout and level.
1217	*
1218	* @warning It returns only up to masks_size modifier masks. If the
1219	* buffer passed is too small, some of the possible modifier combinations
1220	* will not be returned.
1221	*
1222	* @param[in] keymap The keymap.
1223	* @param[in] key The keycode of the key.
1224	* @param[in] layout The layout for which to get modifiers.
1225	* @param[in] level The shift level in the layout for which to get the
1226	* modifiers. This should be smaller than:
1227	* @code xkb_keymap_num_levels_for_key(keymap, key) @endcode
1228	* @param[out] masks_out A buffer in which the requested masks should be
1229	* stored.
1230	* @param[out] masks_size The number of elements in the buffer pointed to by
1231	* masks_out.
1232	*
1233	* If @c layout is out of range for this key (that is, larger or equal to
1234	* the value returned by xkb_keymap_num_layouts_for_key()), it is brought
1235	* back into range in a manner consistent with xkb_state_key_get_layout().
1236	*
1237	* @returns The number of modifier masks stored in the masks_out array.
1238	* If the key is not in the keymap or if the specified shift level cannot
1239	* be reached it returns 0 and does not modify the masks_out buffer.
1240	*
1241	* @sa xkb_level_index_t
1242	* @sa xkb_mod_mask_t
1243	* @memberof xkb_keymap
1244	* @since 1.0.0
1245	*/
1246	size_t
1247	xkb_keymap_key_get_mods_for_level(struct xkb_keymap *keymap,
1248	xkb_keycode_t key,
1249	xkb_layout_index_t layout,
1250	xkb_level_index_t level,
1251	xkb_mod_mask_t *masks_out,
1252	size_t masks_size);
1253
1254	/**
1255	* Get the keysyms obtained from pressing a key in a given layout and
1256	* shift level.
1257	*
1258	* This function is like xkb_state_key_get_syms(), only the layout and
1259	* shift level are not derived from the keyboard state but are instead
1260	* specified explicitly.
1261	*
1262	* @param[in] keymap The keymap.
1263	* @param[in] key The keycode of the key.
1264	* @param[in] layout The layout for which to get the keysyms.
1265	* @param[in] level The shift level in the layout for which to get the
1266	* keysyms. This should be smaller than:
1267	* @code xkb_keymap_num_levels_for_key(keymap, key) @endcode
1268	* @param[out] syms_out An immutable array of keysyms corresponding to the
1269	* key in the given layout and shift level.
1270	*
1271	* If @c layout is out of range for this key (that is, larger or equal to
1272	* the value returned by xkb_keymap_num_layouts_for_key()), it is brought
1273	* back into range in a manner consistent with xkb_state_key_get_layout().
1274	*
1275	* @returns The number of keysyms in the syms_out array. If no keysyms
1276	* are produced by the key in the given layout and shift level, returns 0
1277	* and sets syms_out to NULL.
1278	*
1279	* @sa xkb_state_key_get_syms()
1280	* @memberof xkb_keymap
1281	*/
1282	int
1283	xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap,
1284	xkb_keycode_t key,
1285	xkb_layout_index_t layout,
1286	xkb_level_index_t level,
1287	const xkb_keysym_t **syms_out);
1288
1289	/**
1290	* Determine whether a key should repeat or not.
1291	*
1292	* A keymap may specify different repeat behaviors for different keys.
1293	* Most keys should generally exhibit repeat behavior; for example, holding
1294	* the 'a' key down in a text editor should normally insert a single 'a'
1295	* character every few milliseconds, until the key is released. However,
1296	* there are keys which should not or do not need to be repeated. For
1297	* example, repeating modifier keys such as Left/Right Shift or Caps Lock
1298	* is not generally useful or desired.
1299	*
1300	* @returns 1 if the key should repeat, 0 otherwise.
1301	*
1302	* @memberof xkb_keymap
1303	*/
1304	int
1305	xkb_keymap_key_repeats(struct xkb_keymap *keymap, xkb_keycode_t key);
1306
1307	/** @} */
1308
1309	/**
1310	* @defgroup state Keyboard State
1311	* Creating, destroying and manipulating keyboard state objects.
1312	*
1313	* @{
1314	*/
1315
1316	/**
1317	* Create a new keyboard state object.
1318	*
1319	* @param keymap The keymap which the state will use.
1320	*
1321	* @returns A new keyboard state object, or NULL on failure.
1322	*
1323	* @memberof xkb_state
1324	*/
1325	struct xkb_state *
1326	xkb_state_new(struct xkb_keymap *keymap);
1327
1328	/**
1329	* Take a new reference on a keyboard state object.
1330	*
1331	* @returns The passed in object.
1332	*
1333	* @memberof xkb_state
1334	*/
1335	struct xkb_state *
1336	xkb_state_ref(struct xkb_state *state);
1337
1338	/**
1339	* Release a reference on a keybaord state object, and possibly free it.
1340	*
1341	* @param state The state. If it is NULL, this function does nothing.
1342	*
1343	* @memberof xkb_state
1344	*/
1345	void
1346	xkb_state_unref(struct xkb_state *state);
1347
1348	/**
1349	* Get the keymap which a keyboard state object is using.
1350	*
1351	* @returns The keymap which was passed to xkb_state_new() when creating
1352	* this state object.
1353	*
1354	* This function does not take a new reference on the keymap; you must
1355	* explicitly reference it yourself if you plan to use it beyond the
1356	* lifetime of the state.
1357	*
1358	* @memberof xkb_state
1359	*/
1360	struct xkb_keymap *
1361	xkb_state_get_keymap(struct xkb_state *state);
1362
1363	/**
1364	* @page server-client-state Server State and Client State
1365	* @parblock
1366	*
1367	* The xkb_state API is used by two distinct actors in most window-system
1368	* architectures:
1369	*
1370	* 1. A *server* - for example, a Wayland compositor, an X11 server, an evdev
1371	* listener.
1372	*
1373	* Servers maintain the XKB state for a device according to input events from
1374	* the device, such as key presses and releases, and out-of-band events from
1375	* the user, like UI layout switchers.
1376	*
1377	* 2. A *client* - for example, a Wayland client, an X11 client.
1378	*
1379	* Clients do not listen to input from the device; instead, whenever the
1380	* server state changes, the server serializes the state and notifies the
1381	* clients that the state has changed; the clients then update the state
1382	* from the serialization.
1383	*
1384	* Some entry points in the xkb_state API are only meant for servers and some
1385	* are only meant for clients, and the two should generally not be mixed.
1386	*
1387	* @endparblock
1388	*/
1389
1390	/** Specifies the direction of the key (press / release). */
1391	enum xkb_key_direction {
1392	XKB_KEY_UP, /**< The key was released. */
1393	XKB_KEY_DOWN /**< The key was pressed. */
1394	};
1395
1396	/**
1397	* Modifier and layout types for state objects. This enum is bitmaskable,
1398	* e.g. (XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED) is valid to
1399	* exclude locked modifiers.
1400	*
1401	* In XKB, the DEPRESSED components are also known as 'base'.
1402	*/
1403	enum xkb_state_component {
1404	/** Depressed modifiers, i.e. a key is physically holding them. */
1405	XKB_STATE_MODS_DEPRESSED = (1 << 0),
1406	/** Latched modifiers, i.e. will be unset after the next non-modifier
1407	* key press. */
1408	XKB_STATE_MODS_LATCHED = (1 << 1),
1409	/** Locked modifiers, i.e. will be unset after the key provoking the
1410	* lock has been pressed again. */
1411	XKB_STATE_MODS_LOCKED = (1 << 2),
1412	/** Effective modifiers, i.e. currently active and affect key
1413	* processing (derived from the other state components).
1414	* Use this unless you explicitly care how the state came about. */
1415	XKB_STATE_MODS_EFFECTIVE = (1 << 3),
1416	/** Depressed layout, i.e. a key is physically holding it. */
1417	XKB_STATE_LAYOUT_DEPRESSED = (1 << 4),
1418	/** Latched layout, i.e. will be unset after the next non-modifier
1419	* key press. */
1420	XKB_STATE_LAYOUT_LATCHED = (1 << 5),
1421	/** Locked layout, i.e. will be unset after the key provoking the lock
1422	* has been pressed again. */
1423	XKB_STATE_LAYOUT_LOCKED = (1 << 6),
1424	/** Effective layout, i.e. currently active and affects key processing
1425	* (derived from the other state components).
1426	* Use this unless you explicitly care how the state came about. */
1427	XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7),
1428	/** LEDs (derived from the other state components). */
1429	XKB_STATE_LEDS = (1 << 8)
1430	};
1431
1432	/**
1433	* Update the keyboard state to reflect a given key being pressed or
1434	* released.
1435	*
1436	* This entry point is intended for *server* applications and should not be used
1437	* by *client* applications; see @ref server-client-state for details.
1438	*
1439	* A series of calls to this function should be consistent; that is, a call
1440	* with XKB_KEY_DOWN for a key should be matched by an XKB_KEY_UP; if a key
1441	* is pressed twice, it should be released twice; etc. Otherwise (e.g. due
1442	* to missed input events), situations like "stuck modifiers" may occur.
1443	*
1444	* This function is often used in conjunction with the function
1445	* xkb_state_key_get_syms() (or xkb_state_key_get_one_sym()), for example,
1446	* when handling a key event. In this case, you should prefer to get the
1447	* keysyms *before* updating the key, such that the keysyms reported for
1448	* the key event are not affected by the event itself. This is the
1449	* conventional behavior.
1450	*
1451	* @returns A mask of state components that have changed as a result of
1452	* the update. If nothing in the state has changed, returns 0.
1453	*
1454	* @memberof xkb_state
1455	*
1456	* @sa xkb_state_update_mask()
1457	*/
1458	enum xkb_state_component
1459	xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
1460	enum xkb_key_direction direction);
1461
1462	/**
1463	* Update a keyboard state from a set of explicit masks.
1464	*
1465	* This entry point is intended for *client* applications; see @ref
1466	* server-client-state for details. *Server* applications should use
1467	* xkb_state_update_key() instead.
1468	*
1469	* All parameters must always be passed, or the resulting state may be
1470	* incoherent.
1471	*
1472	* The serialization is lossy and will not survive round trips; it must only
1473	* be used to feed client state objects, and must not be used to update the
1474	* server state.
1475	*
1476	* @returns A mask of state components that have changed as a result of
1477	* the update. If nothing in the state has changed, returns 0.
1478	*
1479	* @memberof xkb_state
1480	*
1481	* @sa xkb_state_component
1482	* @sa xkb_state_update_key
1483	*/
1484	enum xkb_state_component
1485	xkb_state_update_mask(struct xkb_state *state,
1486	xkb_mod_mask_t depressed_mods,
1487	xkb_mod_mask_t latched_mods,
1488	xkb_mod_mask_t locked_mods,
1489	xkb_layout_index_t depressed_layout,
1490	xkb_layout_index_t latched_layout,
1491	xkb_layout_index_t locked_layout);
1492
1493	/**
1494	* Get the keysyms obtained from pressing a particular key in a given
1495	* keyboard state.
1496	*
1497	* Get the keysyms for a key according to the current active layout,
1498	* modifiers and shift level for the key, as determined by a keyboard
1499	* state.
1500	*
1501	* @param[in] state The keyboard state object.
1502	* @param[in] key The keycode of the key.
1503	* @param[out] syms_out An immutable array of keysyms corresponding the
1504	* key in the given keyboard state.
1505	*
1506	* As an extension to XKB, this function can return more than one keysym.
1507	* If you do not want to handle this case, you can use
1508	* xkb_state_key_get_one_sym() for a simpler interface.
1509	*
1510	* This function does not perform any @ref keysym-transformations.
1511	* (This might change).
1512	*
1513	* @returns The number of keysyms in the syms_out array. If no keysyms
1514	* are produced by the key in the given keyboard state, returns 0 and sets
1515	* syms_out to NULL.
1516	*
1517	* @memberof xkb_state
1518	*/
1519	int
1520	xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
1521	const xkb_keysym_t **syms_out);
1522
1523	/**
1524	* Get the Unicode/UTF-8 string obtained from pressing a particular key
1525	* in a given keyboard state.
1526	*
1527	* @param[in] state The keyboard state object.
1528	* @param[in] key The keycode of the key.
1529	* @param[out] buffer A buffer to write the string into.
1530	* @param[in] size Size of the buffer.
1531	*
1532	* @warning If the buffer passed is too small, the string is truncated
1533	* (though still NUL-terminated).
1534	*
1535	* @returns The number of bytes required for the string, excluding the
1536	* NUL byte. If there is nothing to write, returns 0.
1537	*
1538	* You may check if truncation has occurred by comparing the return value
1539	* with the size of @p buffer, similarly to the snprintf(3) function.
1540	* You may safely pass NULL and 0 to @p buffer and @p size to find the
1541	* required size (without the NUL-byte).
1542	*
1543	* This function performs Capitalization and Control @ref
1544	* keysym-transformations.
1545	*
1546	* @memberof xkb_state
1547	* @since 0.4.1
1548	*/
1549	int
1550	xkb_state_key_get_utf8(struct xkb_state *state, xkb_keycode_t key,
1551	char *buffer, size_t size);
1552
1553	/**
1554	* Get the Unicode/UTF-32 codepoint obtained from pressing a particular
1555	* key in a a given keyboard state.
1556	*
1557	* @returns The UTF-32 representation for the key, if it consists of only
1558	* a single codepoint. Otherwise, returns 0.
1559	*
1560	* This function performs Capitalization and Control @ref
1561	* keysym-transformations.
1562	*
1563	* @memberof xkb_state
1564	* @since 0.4.1
1565	*/
1566	uint32_t
1567	xkb_state_key_get_utf32(struct xkb_state *state, xkb_keycode_t key);
1568
1569	/**
1570	* Get the single keysym obtained from pressing a particular key in a
1571	* given keyboard state.
1572	*
1573	* This function is similar to xkb_state_key_get_syms(), but intended
1574	* for users which cannot or do not want to handle the case where
1575	* multiple keysyms are returned (in which case this function is
1576	* preferred).
1577	*
1578	* @returns The keysym. If the key does not have exactly one keysym,
1579	* returns XKB_KEY_NoSymbol
1580	*
1581	* This function performs Capitalization @ref keysym-transformations.
1582	*
1583	* @sa xkb_state_key_get_syms()
1584	* @memberof xkb_state
1585	*/
1586	xkb_keysym_t
1587	xkb_state_key_get_one_sym(struct xkb_state *state, xkb_keycode_t key);
1588
1589	/**
1590	* Get the effective layout index for a key in a given keyboard state.
1591	*
1592	* @returns The layout index for the key in the given keyboard state. If
1593	* the given keycode is invalid, or if the key is not included in any
1594	* layout at all, returns XKB_LAYOUT_INVALID.
1595	*
1596	* @invariant If the returned layout is valid, the following always holds:
1597	* @code
1598	* xkb_state_key_get_layout(state, key) < xkb_keymap_num_layouts_for_key(keymap, key)
1599	* @endcode
1600	*
1601	* @memberof xkb_state
1602	*/
1603	xkb_layout_index_t
1604	xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t key);
1605
1606	/**
1607	* Get the effective shift level for a key in a given keyboard state and
1608	* layout.
1609	*
1610	* @param state The keyboard state.
1611	* @param key The keycode of the key.
1612	* @param layout The layout for which to get the shift level. This must be
1613	* smaller than:
1614	* @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
1615	* usually it would be:
1616	* @code xkb_state_key_get_layout(state, key) @endcode
1617	*
1618	* @return The shift level index. If the key or layout are invalid,
1619	* returns XKB_LEVEL_INVALID.
1620	*
1621	* @invariant If the returned level is valid, the following always holds:
1622	* @code
1623	* xkb_state_key_get_level(state, key, layout) < xkb_keymap_num_levels_for_key(keymap, key, layout)
1624	* @endcode
1625	*
1626	* @memberof xkb_state
1627	*/
1628	xkb_level_index_t
1629	xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key,
1630	xkb_layout_index_t layout);
1631
1632	/**
1633	* Match flags for xkb_state_mod_indices_are_active() and
1634	* xkb_state_mod_names_are_active(), specifying the conditions for a
1635	* successful match. XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with
1636	* the other modes.
1637	*/
1638	enum xkb_state_match {
1639	/** Returns true if any of the modifiers are active. */
1640	XKB_STATE_MATCH_ANY = (1 << 0),
1641	/** Returns true if all of the modifiers are active. */
1642	XKB_STATE_MATCH_ALL = (1 << 1),
1643	/** Makes matching non-exclusive, i.e. will not return false if a
1644	* modifier not specified in the arguments is active. */
1645	XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16)
1646	};
1647
1648	/**
1649	* The counterpart to xkb_state_update_mask for modifiers, to be used on
1650	* the server side of serialization.
1651	*
1652	* This entry point is intended for *server* applications; see @ref
1653	* server-client-state for details. *Client* applications should use the
1654	* xkb_state_mod_*_is_active API.
1655	*
1656	* @param state The keyboard state.
1657	* @param components A mask of the modifier state components to serialize.
1658	* State components other than XKB_STATE_MODS_* are ignored.
1659	* If XKB_STATE_MODS_EFFECTIVE is included, all other state components are
1660	* ignored.
1661	*
1662	* @returns A xkb_mod_mask_t representing the given components of the
1663	* modifier state.
1664	*
1665	* @memberof xkb_state
1666	*/
1667	xkb_mod_mask_t
1668	xkb_state_serialize_mods(struct xkb_state *state,
1669	enum xkb_state_component components);
1670
1671	/**
1672	* The counterpart to xkb_state_update_mask for layouts, to be used on
1673	* the server side of serialization.
1674	*
1675	* This entry point is intended for *server* applications; see @ref
1676	* server-client-state for details. *Client* applications should use the
1677	* xkb_state_layout_*_is_active API.
1678	*
1679	* @param state The keyboard state.
1680	* @param components A mask of the layout state components to serialize.
1681	* State components other than XKB_STATE_LAYOUT_* are ignored.
1682	* If XKB_STATE_LAYOUT_EFFECTIVE is included, all other state components are
1683	* ignored.
1684	*
1685	* @returns A layout index representing the given components of the
1686	* layout state.
1687	*
1688	* @memberof xkb_state
1689	*/
1690	xkb_layout_index_t
1691	xkb_state_serialize_layout(struct xkb_state *state,
1692	enum xkb_state_component components);
1693
1694	/**
1695	* Test whether a modifier is active in a given keyboard state by name.
1696	*
1697	* @returns 1 if the modifier is active, 0 if it is not. If the modifier
1698	* name does not exist in the keymap, returns -1.
1699	*
1700	* @memberof xkb_state
1701	*/
1702	int
1703	xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
1704	enum xkb_state_component type);
1705
1706	/**
1707	* Test whether a set of modifiers are active in a given keyboard state by
1708	* name.
1709	*
1710	* @param state The keyboard state.
1711	* @param type The component of the state against which to match the
1712	* given modifiers.
1713	* @param match The manner by which to match the state against the
1714	* given modifiers.
1715	* @param ... The set of of modifier names to test, terminated by a NULL
1716	* argument (sentinel).
1717	*
1718	* @returns 1 if the modifiers are active, 0 if they are not. If any of
1719	* the modifier names do not exist in the keymap, returns -1.
1720	*
1721	* @memberof xkb_state
1722	*/
1723	int
1724	xkb_state_mod_names_are_active(struct xkb_state *state,
1725	enum xkb_state_component type,
1726	enum xkb_state_match match,
1727	...);
1728
1729	/**
1730	* Test whether a modifier is active in a given keyboard state by index.
1731	*
1732	* @returns 1 if the modifier is active, 0 if it is not. If the modifier
1733	* index is invalid in the keymap, returns -1.
1734	*
1735	* @memberof xkb_state
1736	*/
1737	int
1738	xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
1739	enum xkb_state_component type);
1740
1741	/**
1742	* Test whether a set of modifiers are active in a given keyboard state by
1743	* index.
1744	*
1745	* @param state The keyboard state.
1746	* @param type The component of the state against which to match the
1747	* given modifiers.
1748	* @param match The manner by which to match the state against the
1749	* given modifiers.
1750	* @param ... The set of of modifier indices to test, terminated by a
1751	* XKB_MOD_INVALID argument (sentinel).
1752	*
1753	* @returns 1 if the modifiers are active, 0 if they are not. If any of
1754	* the modifier indices are invalid in the keymap, returns -1.
1755	*
1756	* @memberof xkb_state
1757	*/
1758	int
1759	xkb_state_mod_indices_are_active(struct xkb_state *state,
1760	enum xkb_state_component type,
1761	enum xkb_state_match match,
1762	...);
1763
1764	/**
1765	* @page consumed-modifiers Consumed Modifiers
1766	* @parblock
1767	*
1768	* Some functions, like xkb_state_key_get_syms(), look at the state of
1769	* the modifiers in the keymap and derive from it the correct shift level
1770	* to use for the key. For example, in a US layout, pressing the key
1771	* labeled \<A\> while the Shift modifier is active, generates the keysym
1772	* 'A'. In this case, the Shift modifier is said to be "consumed".
1773	* However, the Num Lock modifier does not affect this translation at all,
1774	* even if it is active, so it is not consumed by this translation.
1775	*
1776	* It may be desirable for some application to not reuse consumed modifiers
1777	* for further processing, e.g. for hotkeys or keyboard shortcuts. To
1778	* understand why, consider some requirements from a standard shortcut
1779	* mechanism, and how they are implemented:
1780	*
1781	* 1. The shortcut's modifiers must match exactly to the state. For
1782	* example, it is possible to bind separate actions to \<Alt\>\<Tab\>
1783	* and to \<Alt\>\<Shift\>\<Tab\>. Further, if only \<Alt\>\<Tab\> is
1784	* bound to an action, pressing \<Alt\>\<Shift\>\<Tab\> should not
1785	* trigger the shortcut.
1786	* Effectively, this means that the modifiers are compared using the
1787	* equality operator (==).
1788	*
1789	* 2. Only relevant modifiers are considered for the matching. For example,
1790	* Caps Lock and Num Lock should not generally affect the matching, e.g.
1791	* when matching \<Alt\>\<Tab\> against the state, it does not matter
1792	* whether Num Lock is active or not. These relevant, or "significant",
1793	* modifiers usually include Alt, Control, Shift, Super and similar.
1794	* Effectively, this means that non-significant modifiers are masked out,
1795	* before doing the comparison as described above.
1796	*
1797	* 3. The matching must be independent of the layout/keymap. For example,
1798	* the \<Plus\> (+) symbol is found on the first level on some layouts,
1799	* but requires holding Shift on others. If you simply bind the action
1800	* to the \<Plus\> keysym, it would work for the unshifted kind, but
1801	* not for the others, because the match against Shift would fail. If
1802	* you bind the action to \<Shift\>\<Plus\>, only the shifted kind would
1803	* work. So what is needed is to recognize that Shift is used up in the
1804	* translation of the keysym itself, and therefore should not be included
1805	* in the matching.
1806	* Effectively, this means that consumed modifiers (Shift in this example)
1807	* are masked out as well, before doing the comparison.
1808	*
1809	* In summary, this is approximately how the matching would be performed:
1810	* @code
1811	* (keysym == shortcut_keysym) &&
1812	* ((state_mods & ~consumed_mods & significant_mods) == shortcut_mods)
1813	* @endcode
1814	*
1815	* @c state_mods are the modifiers reported by
1816	* xkb_state_mod_index_is_active() and similar functions.
1817	* @c consumed_mods are the modifiers reported by
1818	* xkb_state_mod_index_is_consumed() and similar functions.
1819	* @c significant_mods are decided upon by the application/toolkit/user;
1820	* it is up to them to decide whether these are configurable or hard-coded.
1821	*
1822	* @endparblock
1823	*/
1824
1825	/**
1826	* Consumed modifiers mode.
1827	*
1828	* There are several possible methods for deciding which modifiers are
1829	* consumed and which are not, each applicable for different systems or
1830	* situations. The mode selects the method to use.
1831	*
1832	* Keep in mind that in all methods, the keymap may decide to "preserve"
1833	* a modifier, meaning it is not reported as consumed even if it would
1834	* have otherwise.
1835	*/
1836	enum xkb_consumed_mode {
1837	/**
1838	* This is the mode defined in the XKB specification and used by libX11.
1839	*
1840	* A modifier is consumed if and only if it *may affect* key translation.
1841	*
1842	* For example, if `Control+Alt+<Backspace>` produces some assigned keysym,
1843	* then when pressing just `<Backspace>`, `Control` and `Alt` are consumed,
1844	* even though they are not active, since if they *were* active they would
1845	* have affected key translation.
1846	*/
1847	XKB_CONSUMED_MODE_XKB,
1848	/**
1849	* This is the mode used by the GTK+ toolkit.
1850	*
1851	* The mode consists of the following two independent heuristics:
1852	*
1853	* - The currently active set of modifiers, excluding modifiers which do
1854	* not affect the key (as described for @ref XKB_CONSUMED_MODE_XKB), are
1855	* considered consumed, if the keysyms produced when all of them are
1856	* active are different from the keysyms produced when no modifiers are
1857	* active.
1858	*
1859	* - A single modifier is considered consumed if the keysyms produced for
1860	* the key when it is the only active modifier are different from the
1861	* keysyms produced when no modifiers are active.
1862	*/
1863	XKB_CONSUMED_MODE_GTK
1864	};
1865
1866	/**
1867	* Get the mask of modifiers consumed by translating a given key.
1868	*
1869	* @param state The keyboard state.
1870	* @param key The keycode of the key.
1871	* @param mode The consumed modifiers mode to use; see enum description.
1872	*
1873	* @returns a mask of the consumed modifiers.
1874	*
1875	* @memberof xkb_state
1876	* @since 0.7.0
1877	*/
1878	xkb_mod_mask_t
1879	xkb_state_key_get_consumed_mods2(struct xkb_state *state, xkb_keycode_t key,
1880	enum xkb_consumed_mode mode);
1881
1882	/**
1883	* Same as xkb_state_key_get_consumed_mods2() with mode XKB_CONSUMED_MODE_XKB.
1884	*
1885	* @memberof xkb_state
1886	* @since 0.4.1
1887	*/
1888	xkb_mod_mask_t
1889	xkb_state_key_get_consumed_mods(struct xkb_state *state, xkb_keycode_t key);
1890
1891	/**
1892	* Test whether a modifier is consumed by keyboard state translation for
1893	* a key.
1894	*
1895	* @param state The keyboard state.
1896	* @param key The keycode of the key.
1897	* @param idx The index of the modifier to check.
1898	* @param mode The consumed modifiers mode to use; see enum description.
1899	*
1900	* @returns 1 if the modifier is consumed, 0 if it is not. If the modifier
1901	* index is not valid in the keymap, returns -1.
1902	*
1903	* @sa xkb_state_mod_mask_remove_consumed()
1904	* @sa xkb_state_key_get_consumed_mods()
1905	* @memberof xkb_state
1906	* @since 0.7.0
1907	*/
1908	int
1909	xkb_state_mod_index_is_consumed2(struct xkb_state *state,
1910	xkb_keycode_t key,
1911	xkb_mod_index_t idx,
1912	enum xkb_consumed_mode mode);
1913
1914	/**
1915	* Same as xkb_state_mod_index_is_consumed2() with mode XKB_CONSUMED_MOD_XKB.
1916	*
1917	* @memberof xkb_state
1918	* @since 0.4.1
1919	*/
1920	int
1921	xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key,
1922	xkb_mod_index_t idx);
1923
1924	/**
1925	* Remove consumed modifiers from a modifier mask for a key.
1926	*
1927	* @deprecated Use xkb_state_key_get_consumed_mods2() instead.
1928	*
1929	* Takes the given modifier mask, and removes all modifiers which are
1930	* consumed for that particular key (as in xkb_state_mod_index_is_consumed()).
1931	*
1932	* @sa xkb_state_mod_index_is_consumed()
1933	* @memberof xkb_state
1934	*/
1935	xkb_mod_mask_t
1936	xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t key,
1937	xkb_mod_mask_t mask);
1938
1939	/**
1940	* Test whether a layout is active in a given keyboard state by name.
1941	*
1942	* @returns 1 if the layout is active, 0 if it is not. If no layout with
1943	* this name exists in the keymap, return -1.
1944	*
1945	* If multiple layouts in the keymap have this name, the one with the lowest
1946	* index is tested.
1947	*
1948	* @sa xkb_layout_index_t
1949	* @memberof xkb_state
1950	*/
1951	int
1952	xkb_state_layout_name_is_active(struct xkb_state *state, const char *name,
1953	enum xkb_state_component type);
1954
1955	/**
1956	* Test whether a layout is active in a given keyboard state by index.
1957	*
1958	* @returns 1 if the layout is active, 0 if it is not. If the layout index
1959	* is not valid in the keymap, returns -1.
1960	*
1961	* @sa xkb_layout_index_t
1962	* @memberof xkb_state
1963	*/
1964	int
1965	xkb_state_layout_index_is_active(struct xkb_state *state,
1966	xkb_layout_index_t idx,
1967	enum xkb_state_component type);
1968
1969	/**
1970	* Test whether a LED is active in a given keyboard state by name.
1971	*
1972	* @returns 1 if the LED is active, 0 if it not. If no LED with this name
1973	* exists in the keymap, returns -1.
1974	*
1975	* @sa xkb_led_index_t
1976	* @memberof xkb_state
1977	*/
1978	int
1979	xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
1980
1981	/**
1982	* Test whether a LED is active in a given keyboard state by index.
1983	*
1984	* @returns 1 if the LED is active, 0 if it not. If the LED index is not
1985	* valid in the keymap, returns -1.
1986	*
1987	* @sa xkb_led_index_t
1988	* @memberof xkb_state
1989	*/
1990	int
1991	xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
1992
1993	/** @} */
1994
1995	/* Leave this include last, so it can pick up our types, etc. */
1996	#include <xkbcommon/xkbcommon-compat.h>
1997
1998	#ifdef __cplusplus
1999	} /* extern "C" */
2000	#endif
2001
2002	#endif /* _XKBCOMMON_H_ */
2003