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