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