1/*
2 * For MIT-open-group:
3 * Copyright 1985, 1987, 1990, 1998 The Open Group
4 * Copyright 2008 Dan Nicholson
5 *
6 * For HPND:
7 * Copyright (c) 1993 by Silicon Graphics Computer Systems, Inc.
8 * SPDX-License-Identifier: HPND
9 *
10 * For MIT:
11 * Copyright © 2009-2012 Daniel Stone
12 * Copyright © 2012 Intel Corporation
13 * Copyright © 2012 Ran Benita
14 *
15 * SPDX-License-Identifier: MIT-open-group AND HPND AND MIT
16 *
17 * Author: Daniel Stone <daniel@fooishbar.org>
18 */
19
20#ifndef _XKBCOMMON_H_
21#define _XKBCOMMON_H_
22
23#include <stdbool.h>
24#include <stdint.h>
25#include <stdio.h>
26#include <stdarg.h>
27
28#include <xkbcommon/xkbcommon-names.h>
29#include <xkbcommon/xkbcommon-keysyms.h>
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35#if defined(__GNUC__) && !defined(__CYGWIN__)
36# define XKB_EXPORT __attribute__((visibility("default")))
37#elif defined(_WIN32)
38# define XKB_EXPORT __declspec(dllexport)
39#else
40# define XKB_EXPORT
41#endif
42
43/**
44 * @file
45 * Main libxkbcommon API.
46 */
47
48/**
49 * @struct xkb_context
50 * Opaque top level library context object.
51 *
52 * The context contains various general library data and state, like
53 * logging level and include paths.
54 *
55 * Objects are created in a specific context, and multiple contexts may
56 * coexist simultaneously. Objects from different contexts are completely
57 * separated and do not share any memory or state.
58 */
59struct xkb_context;
60
61/**
62 * @struct xkb_keymap
63 * Opaque compiled keymap object.
64 *
65 * The keymap object holds all of the static keyboard information obtained
66 * from compiling XKB files.
67 *
68 * A keymap is immutable after it is created (besides reference counts, etc.);
69 * if you need to change it, you must create a new one.
70 */
71struct xkb_keymap;
72
73/**
74 * @struct xkb_state
75 * Opaque keyboard state object.
76 *
77 * State objects contain the active state of a keyboard (or keyboards), such
78 * as the currently effective layout and the active modifiers. It acts as a
79 * simple state machine, wherein key presses and releases are the input, and
80 * key symbols (keysyms) are the output.
81 */
82struct xkb_state;
83
84/**
85 * A number used to represent a physical key on a keyboard.
86 *
87 * A standard PC-compatible keyboard might have 102 keys. An appropriate
88 * keymap would assign each of them a keycode, by which the user should
89 * refer to the key throughout the library.
90 *
91 * Historically, the X11 protocol, and consequentially the XKB protocol,
92 * assign only 8 bits for keycodes. This limits the number of different
93 * keys that can be used simultaneously in a single keymap to 256
94 * (disregarding other limitations). This library does not share this limit;
95 * keycodes beyond 255 (*extended* keycodes) are not treated specially.
96 * Keymaps and applications which are compatible with X11 should not use
97 * these keycodes.
98 *
99 * The values of specific keycodes are determined by the keymap and the
100 * underlying input system. For example, with an X11-compatible keymap
101 * and Linux evdev scan codes (see `linux/input.h`), a fixed offset is used:
102 *
103 * The keymap defines a canonical name for each key, plus possible aliases.
104 * Historically, the XKB protocol restricts these names to at most 4 (ASCII)
105 * characters, but this library does not share this limit.
106 *
107 * @code
108 * xkb_keycode_t keycode_A = KEY_A + 8;
109 * @endcode
110 *
111 * @sa xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11()
112 */
113typedef uint32_t xkb_keycode_t;
114
115/**
116 * A number used to represent the symbols generated from a key on a keyboard.
117 *
118 * A key, represented by a keycode, may generate different symbols according
119 * to keyboard state. For example, on a QWERTY keyboard, pressing the key
120 * labled \<A\> generates the symbol ‘a’. If the Shift key is held, it
121 * generates the symbol ‘A’. If a different layout is used, say Greek,
122 * it generates the symbol ‘α’. And so on.
123 *
124 * Each such symbol is represented by a *keysym* (short for “key symbol”).
125 * Note that keysyms are somewhat more general, in that they can also represent
126 * some “function”, such as “Left” or “Right” for the arrow keys. For more
127 * information, see: Appendix A [“KEYSYM Encoding”][encoding] of the X Window
128 * System Protocol.
129 *
130 * Specifically named keysyms can be found in the
131 * xkbcommon/xkbcommon-keysyms.h header file. Their name does not include
132 * the `XKB_KEY_` prefix.
133 *
134 * Besides those, any Unicode/ISO 10646 character in the range U+0100 to
135 * U+10FFFF can be represented by a keysym value in the range 0x01000100 to
136 * 0x0110FFFF. The name of Unicode keysyms is `U<codepoint>`, e.g. `UA1B2`.
137 *
138 * The name of other unnamed keysyms is the hexadecimal representation of
139 * their value, e.g. `0xabcd1234`.
140 *
141 * Keysym names are case-sensitive.
142 *
143 * @note **Encoding:** Keysyms are 32-bit integers with the 3 most significant
144 * bits always set to zero. Thus valid keysyms are in the range
145 * `0 .. 0x1fffffff` = @ref XKB_KEYSYM_MAX.
146 * See: Appendix A [“KEYSYM Encoding”][encoding] of the X Window System Protocol.
147 *
148 * [encoding]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#keysym_encoding
149 *
150 * @ingroup keysyms
151 * @sa `::XKB_KEYSYM_MAX`
152 */
153typedef uint32_t xkb_keysym_t;
154
155/**
156 * Index of a keyboard layout.
157 *
158 * The layout index is a state component which determines which <em>keyboard
159 * layout</em> is active. These may be different alphabets, different key
160 * arrangements, etc.
161 *
162 * Layout indices are consecutive. The first layout has index 0.
163 *
164 * Each layout is not required to have a name, and the names are not
165 * guaranteed to be unique (though they are usually provided and unique).
166 * Therefore, it is not safe to use the name as a unique identifier for a
167 * layout. Layout names are case-sensitive.
168 *
169 * Layout names are specified in the layout’s definition, for example
170 * “English (US)”. These are different from the (conventionally) short names
171 * which are used to locate the layout, for example `us` or `us(intl)`. These
172 * names are not present in a compiled keymap.
173 *
174 * If the user selects layouts from a list generated from the XKB registry
175 * (using libxkbregistry or directly), and this metadata is needed later on, it
176 * is recommended to store it along with the keymap.
177 *
178 * Layouts are also called *groups* by XKB.
179 *
180 * @sa xkb_keymap::xkb_keymap_num_layouts()
181 * @sa xkb_keymap::xkb_keymap_num_layouts_for_key()
182 */
183typedef uint32_t xkb_layout_index_t;
184/** A mask of layout indices. */
185typedef uint32_t xkb_layout_mask_t;
186
187/**
188 * Index of a shift level.
189 *
190 * Any key, in any layout, can have several <em>shift levels</em>. Each
191 * shift level can assign different keysyms to the key. The shift level
192 * to use is chosen according to the current keyboard state; for example,
193 * if no keys are pressed, the first level may be used; if the Left Shift
194 * key is pressed, the second; if Num Lock is pressed, the third; and
195 * many such combinations are possible (see `xkb_mod_index_t`).
196 *
197 * Level indices are consecutive. The first level has index 0.
198 */
199typedef uint32_t xkb_level_index_t;
200
201/**
202 * Index of a modifier.
203 *
204 * A @e modifier is a state component which changes the way keys are
205 * interpreted. A keymap defines a set of modifiers, such as Alt, Shift,
206 * Num Lock or Meta, and specifies which keys may @e activate which
207 * modifiers (in a many-to-many relationship, i.e. a key can activate
208 * several modifiers, and a modifier may be activated by several keys.
209 * Different keymaps do this differently).
210 *
211 * When retrieving the keysyms for a key, the active modifier set is
212 * consulted; this determines the correct shift level to use within the
213 * currently active layout (see `xkb_level_index_t`).
214 *
215 * Modifier indices are consecutive. The first modifier has index 0.
216 *
217 * Each modifier must have a name, and the names are unique. Therefore, it
218 * is safe to use the name as a unique identifier for a modifier. The names
219 * of some common modifiers are provided in the `xkbcommon/xkbcommon-names.h`
220 * header file. Modifier names are case-sensitive.
221 *
222 * @sa xkb_keymap_num_mods()
223 */
224typedef uint32_t xkb_mod_index_t;
225/** A mask of modifier indices. */
226typedef uint32_t xkb_mod_mask_t;
227
228/**
229 * Index of a keyboard LED.
230 *
231 * LEDs are logical objects which may be @e active or @e inactive. They
232 * typically correspond to the lights on the keyboard. Their state is
233 * determined by the current keyboard state.
234 *
235 * LED indices are non-consecutive. The first LED has index 0.
236 *
237 * Each LED must have a name, and the names are unique. Therefore,
238 * it is safe to use the name as a unique identifier for a LED. The names
239 * of some common LEDs are provided in the `xkbcommon/xkbcommon-names.h`
240 * header file. LED names are case-sensitive.
241 *
242 * @warning A given keymap may specify an exact index for a given LED.
243 * Therefore, LED indexing is not necessarily sequential, as opposed to
244 * modifiers and layouts. This means that when iterating over the LEDs
245 * in a keymap using e.g. xkb_keymap::xkb_keymap_num_leds(), some indices might
246 * be invalid.
247 * Given such an index, functions like xkb_keymap::xkb_keymap_led_get_name()
248 * will return `NULL`, and `xkb_state::xkb_state_led_index_is_active()` will
249 * return -1.
250 *
251 * LEDs are also called *indicators* by XKB.
252 *
253 * @sa `xkb_keymap::xkb_keymap_num_leds()`
254 */
255typedef uint32_t xkb_led_index_t;
256/** A mask of LED indices. */
257typedef uint32_t xkb_led_mask_t;
258
259/** Invalid keycode */
260#define XKB_KEYCODE_INVALID (0xffffffff)
261/** Invalid layout index */
262#define XKB_LAYOUT_INVALID (0xffffffff)
263/** Invalid level index */
264#define XKB_LEVEL_INVALID (0xffffffff)
265/** Invalid modifier index */
266#define XKB_MOD_INVALID (0xffffffff)
267/** Invalid LED index */
268#define XKB_LED_INVALID (0xffffffff)
269
270/** Maximum legal keycode */
271#define XKB_KEYCODE_MAX (0xffffffff - 1)
272
273/**
274 * Maximum keysym value
275 *
276 * @since 1.6.0
277 * @sa xkb_keysym_t
278 * @ingroup keysyms
279 */
280#define XKB_KEYSYM_MAX 0x1fffffff
281
282/**
283 * Test whether a value is a valid extended keycode.
284 * @sa xkb_keycode_t
285 **/
286#define xkb_keycode_is_legal_ext(key) ((key) <= XKB_KEYCODE_MAX)
287
288/**
289 * Test whether a value is a valid X11 keycode.
290 * @sa xkb_keycode_t
291 */
292#define xkb_keycode_is_legal_x11(key) ((key) >= 8 && (key) <= 255)
293
294/**
295 * @defgroup rules-api Rules
296 * Utility functions related to *rules*, whose purpose is introduced in:
297 * @ref xkb-the-config "".
298 *
299 * @{
300 */
301
302/**
303 * @struct xkb_rmlvo_builder
304 * Opaque [RMLVO] configuration object.
305 *
306 * It denotes the configuration values by which a user picks a keymap.
307 *
308 * @see [Introduction to RMLVO][RMLVO]
309 * @see @ref rules-api ""
310 * @since 1.11.0
311 *
312 * [RMLVO]: @ref RMLVO-intro
313 */
314struct xkb_rmlvo_builder;
315
316enum xkb_rmlvo_builder_flags {
317 XKB_RMLVO_BUILDER_NO_FLAGS = 0
318};
319
320/**
321 * Create a new [RMLVO] builder.
322 *
323 * @param context The context in which to create the builder.
324 * @param rules The ruleset.
325 * If `NULL` or the empty string `""`, a default value is used.
326 * If the `XKB_DEFAULT_RULES` environment variable is set, it is used
327 * as the default. Otherwise the system default is used.
328 * @param model The keyboard model.
329 * If `NULL` or the empty string `""`, a default value is used.
330 * If the `XKB_DEFAULT_MODEL` environment variable is set, it is used
331 * as the default. Otherwise the system default is used.
332 * @param flags Optional flags for the builder, or 0.
333 *
334 * @returns A `xkb_rmlvo_builder`, or `NULL` if the compilation failed.
335 *
336 * @see `xkb_rule_names` for a detailed description of `rules` and `model`.
337 * @since 1.11.0
338 * @memberof xkb_rmlvo_builder
339 *
340 * [RMLVO]: @ref RMLVO-intro
341 */
342XKB_EXPORT struct xkb_rmlvo_builder*
343xkb_rmlvo_builder_new(struct xkb_context *context,
344 const char *rules, const char *model,
345 enum xkb_rmlvo_builder_flags flags);
346
347/**
348 * Append a layout to the given [RMLVO] builder.
349 *
350 * @param rmlvo The builder to modify.
351 * @param layout The name of the layout.
352 * @param variant The name of the layout variant, or `NULL` to
353 * select the default variant.
354 * @param options An array of options to apply only to this layout, or
355 * `NULL` if there is no such options.
356 * @param options_len The length of @p options.
357 *
358 * @note The options are only effectual if the corresponding ruleset has the
359 * proper rules to handle them as *layout-specific* options.
360 * @note See `rxkb_option_is_layout_specific()` to query whether an option
361 * supports the layout-specific feature.
362 *
363 * @returns `true` if the call succeeded, otherwise `false`.
364 *
365 * @since 1.11.0
366 * @memberof xkb_rmlvo_builder
367 *
368 * [RMLVO]: @ref RMLVO-intro
369 */
370XKB_EXPORT bool
371xkb_rmlvo_builder_append_layout(struct xkb_rmlvo_builder *rmlvo,
372 const char *layout, const char *variant,
373 const char* const* options, size_t options_len);
374
375/**
376 * Append an option to the given [RMLVO] builder.
377 *
378 * @param rmlvo The builder to modify.
379 * @param option The name of the option.
380 *
381 * @returns `true` if the call succeeded, otherwise `false`.
382 *
383 * @since 1.11.0
384 * @memberof xkb_rmlvo_builder
385 *
386 * [RMLVO]: @ref RMLVO-intro
387 */
388XKB_EXPORT bool
389xkb_rmlvo_builder_append_option(struct xkb_rmlvo_builder *rmlvo,
390 const char *option);
391
392/**
393 * Take a new reference on a [RMLVO] builder.
394 *
395 * @param rmlvo The builder to reference.
396 *
397 * @returns The passed in builder.
398 *
399 * @since 1.11.0
400 * @memberof xkb_rmlvo_builder
401 *
402 * [RMLVO]: @ref RMLVO-intro
403 */
404XKB_EXPORT struct xkb_rmlvo_builder *
405xkb_rmlvo_builder_ref(struct xkb_rmlvo_builder *rmlvo);
406
407/**
408 * Release a reference on a [RMLVO] builder, and possibly free it.
409 *
410 * @param rmlvo The builder. If it is `NULL`, this function does nothing.
411 *
412 * @since 1.11.0
413 * @memberof xkb_rmlvo_builder
414 *
415 * [RMLVO]: @ref RMLVO-intro
416 */
417XKB_EXPORT void
418xkb_rmlvo_builder_unref(struct xkb_rmlvo_builder *rmlvo);
419
420/**
421 * Names to compile a keymap with, also known as [RMLVO].
422 *
423 * The names are the common configuration values by which a user picks
424 * a keymap.
425 *
426 * If the entire struct is `NULL`, then each field is taken to be `NULL`.
427 * You should prefer passing `NULL` instead of choosing your own defaults.
428 *
429 * @see [Introduction to RMLVO][RMLVO]
430 * @see @ref rules-api ""
431 *
432 * [RMLVO]: @ref RMLVO-intro
433 */
434struct xkb_rule_names {
435 /**
436 * The rules file to use. The rules file describes how to interpret
437 * the values of the model, layout, variant and options fields.
438 *
439 * If `NULL` or the empty string `""`, a default value is used.
440 * If the `XKB_DEFAULT_RULES` environment variable is set, it is used
441 * as the default. Otherwise the system default is used.
442 */
443 const char *rules;
444 /**
445 * The keyboard model by which to interpret keycodes and LEDs.
446 *
447 * If `NULL` or the empty string `""`, a default value is used.
448 * If the `XKB_DEFAULT_MODEL` environment variable is set, it is used
449 * as the default. Otherwise the system default is used.
450 */
451 const char *model;
452 /**
453 * A comma separated list of layouts (languages) to include in the
454 * keymap.
455 *
456 * If `NULL` or the empty string `""`, a default value is used.
457 * If the `XKB_DEFAULT_LAYOUT` environment variable is set, it is used
458 * as the default. Otherwise the system default is used.
459 */
460 const char *layout;
461 /**
462 * A comma separated list of variants, one per layout, which may
463 * modify or augment the respective layout in various ways.
464 *
465 * Generally, should either be empty or have the same number of values
466 * as the number of layouts. You may use empty values as in `intl,,neo`.
467 *
468 * If `NULL` or the empty string `""`, and a default value is also used
469 * for the layout, a default value is used. Otherwise no variant is
470 * used.
471 * If the `XKB_DEFAULT_VARIANT` environment variable is set, it is used
472 * as the default. Otherwise the system default is used.
473 */
474 const char *variant;
475 /**
476 * A comma separated list of options, through which the user specifies
477 * non-layout related preferences, like which key combinations are used
478 * for switching layouts, or which key is the Compose key.
479 *
480 * If `NULL`, a default value is used. If the empty string `""`, no
481 * options are used.
482 * If the `XKB_DEFAULT_OPTIONS` environment variable is set, it is used
483 * as the default. Otherwise the system default is used.
484 *
485 * Each option can additionally have a *layout index specifier*, so that it
486 * applies only if matching the given layout. The index is specified by
487 * appending `!` immediately after the option name, then the 1-indexed
488 * target layout in decimal format: e.g. `ns:option!2`. When no layout is
489 * specified, it matches any layout.
490 *
491 * @note The layout index specifier is only effectual if the corresponding
492 * ruleset has the proper rules to handle the option as *layout-specific*.
493 * @note See `rxkb_option_is_layout_specific()` to query whether an option
494 * supports the layout-specific feature.
495 *
496 * @since 1.11.0: Layout index specifier using `!`.
497 */
498 const char *options;
499};
500
501/**
502 * Keymap components, also known as [KcCGST].
503 *
504 * The components are the result of the [RMLVO] resolution.
505 *
506 * @see [Introduction to RMLVO][RMLVO]
507 * @see [Introduction to KcCGST][KcCGST]
508 * @see @ref rules-api ""
509 *
510 * [RMLVO]: @ref RMLVO-intro
511 * [KcCGST]: @ref KcCGST-intro
512 */
513struct xkb_component_names {
514 char *keycodes;
515 char *compatibility;
516 char *geometry;
517 char *symbols;
518 char *types;
519};
520
521/**
522 * Resolve [RMLVO] names to [KcCGST] components.
523 *
524 * This function is used primarily for *debugging*. See
525 * `xkb_keymap::xkb_keymap_new_from_names2()` for creating keymaps from
526 * [RMLVO] names.
527 *
528 * @param[in] context The context in which to resolve the names.
529 * @param[in] rmlvo_in The [RMLVO] names to use.
530 * @param[out] rmlvo_out The [RMLVO] names actually used after resolving
531 * missing values.
532 * @param[out] components_out The [KcCGST] components resulting of the [RMLVO]
533 * resolution.
534 *
535 * @c rmlvo_out and @c components can be omitted by using `NULL`, but not both.
536 *
537 * If @c components is not `NULL`, it is filled with dynamically-allocated
538 * strings that should be freed by the caller.
539 *
540 * @returns `true` if the [RMLVO] names could be resolved, `false` otherwise.
541 *
542 * @see [Introduction to RMLVO][RMLVO]
543 * @see [Introduction to KcCGST][KcCGST]
544 * @see xkb_rule_names
545 * @see xkb_component_names
546 * @see xkb_keymap::xkb_keymap_new_from_names2()
547 *
548 * @since 1.9.0
549 * @memberof xkb_component_names
550 *
551 * [RMLVO]: @ref RMLVO-intro
552 * [KcCGST]: @ref KcCGST-intro
553 */
554XKB_EXPORT bool
555xkb_components_names_from_rules(struct xkb_context *context,
556 const struct xkb_rule_names *rmlvo_in,
557 struct xkb_rule_names *rmlvo_out,
558 struct xkb_component_names *components_out);
559
560/** @} */
561
562/**
563 * @defgroup keysyms Keysyms
564 * Utility functions related to *keysyms* (short for “key symbols”).
565 *
566 * @{
567 */
568
569/**
570 * @page keysym-transformations Keysym Transformations
571 *
572 * Keysym translation is subject to several *keysym transformations*,
573 * as described in the XKB specification. These are:
574 *
575 * <dl>
576 * <dt>Capitalization transformation</dt>
577 * <dd>
578 * If the Caps Lock modifier is
579 * active and was not consumed by the translation process, keysyms
580 * are transformed to their upper-case form (if applicable).
581 * Similarly, the UTF-8/UTF-32 string produced is capitalized.
582 *
583 * This is described in:
584 * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Lock_Modifier
585 * </dd>
586 * <dt>Control transformation</dt>
587 * <dd>
588 * If the Control modifier is active and
589 * was not consumed by the translation process, the string produced
590 * is transformed to its matching ASCII control character (if
591 * applicable). Keysyms are not affected.
592 *
593 * This is described in:
594 * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier
595 * </dd>
596 * </dl>
597 *
598 * Each relevant function discusses which transformations it performs.
599 *
600 * These transformations are not applicable when a key produces multiple
601 * keysyms.
602 */
603
604
605/**
606 * Get the name of a keysym.
607 *
608 * For a description of how keysyms are named, see @ref xkb_keysym_t.
609 *
610 * @param[in] keysym The keysym.
611 * @param[out] buffer A string buffer to write the name into.
612 * @param[in] size Size of the buffer.
613 *
614 * @warning If the buffer passed is too small, the string is truncated
615 * (though still `NULL`-terminated); a size of at least 64 bytes is recommended.
616 *
617 * @returns The number of bytes in the name, excluding the `NULL` byte. If
618 * the keysym is invalid, returns -1.
619 *
620 * You may check if truncation has occurred by comparing the return value
621 * with the length of buffer, similarly to the `snprintf(3)` function.
622 *
623 * @sa `xkb_keysym_t`
624 */
625XKB_EXPORT int
626xkb_keysym_get_name(xkb_keysym_t keysym, char *buffer, size_t size);
627
628/** Flags for xkb_keysym_from_name(). */
629enum xkb_keysym_flags {
630 /** Do not apply any flags. */
631 XKB_KEYSYM_NO_FLAGS = 0,
632 /** Find keysym by case-insensitive search. */
633 XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0)
634};
635
636/**
637 * Get a keysym from its name.
638 *
639 * @param name The name of a keysym. See remarks in `xkb_keysym_get_name()`;
640 * this function will accept any name returned by that function.
641 * @param flags A set of flags controlling how the search is done. If
642 * invalid flags are passed, this will fail with `XKB_KEY_NoSymbol`.
643 *
644 * If you use the `::XKB_KEYSYM_CASE_INSENSITIVE` flag and two keysym names
645 * differ only by case, then the lower-case keysym name is returned. For
646 * instance, for KEY_a and KEY_A, this function would return KEY_a for the
647 * case-insensitive search. If this functionality is needed, it is
648 * recommended to first call this function without this flag; and if that
649 * fails, only then to try with this flag, while possibly warning the user
650 * he had misspelled the name, and might get wrong results.
651 *
652 * Case folding is done according to the C locale; the current locale is not
653 * consulted.
654 *
655 * @returns The keysym. If the name is invalid, returns `XKB_KEY_NoSymbol`.
656 *
657 * @sa xkb_keysym_t
658 * @since 1.9.0: Enable support for C0 and C1 control characters in the Unicode
659 * notation.
660 */
661XKB_EXPORT xkb_keysym_t
662xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags);
663
664/**
665 * Get the Unicode/UTF-8 representation of a keysym.
666 *
667 * @param[in] keysym The keysym.
668 * @param[out] buffer A buffer to write the UTF-8 string into.
669 * @param[in] size The size of buffer. Must be at least 5.
670 *
671 * @returns The number of bytes written to the buffer (including the
672 * terminating byte). If the keysym does not have a Unicode
673 * representation, returns 0. If the buffer is too small, returns -1.
674 *
675 * This function does not perform any @ref keysym-transformations.
676 * Therefore, prefer to use `xkb_state::xkb_state_key_get_utf8()` if possible.
677 *
678 * @sa `xkb_state::xkb_state_key_get_utf8()`
679 */
680XKB_EXPORT int
681xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size);
682
683/**
684 * Get the Unicode/UTF-32 representation of a keysym.
685 *
686 * @returns The Unicode/UTF-32 representation of keysym, which is also
687 * compatible with UCS-4. If the keysym does not have a Unicode
688 * representation, returns 0.
689 *
690 * This function does not perform any @ref keysym-transformations.
691 * Therefore, prefer to use xkb_state_key_get_utf32() if possible.
692 *
693 * @sa `xkb_state::xkb_state_key_get_utf32()`
694 */
695XKB_EXPORT uint32_t
696xkb_keysym_to_utf32(xkb_keysym_t keysym);
697
698/**
699 * Get the keysym corresponding to a Unicode/UTF-32 codepoint.
700 *
701 * @returns The keysym corresponding to the specified Unicode
702 * codepoint, or XKB_KEY_NoSymbol if there is none.
703 *
704 * This function is the inverse of @ref xkb_keysym_to_utf32. In cases
705 * where a single codepoint corresponds to multiple keysyms, returns
706 * the keysym with the lowest value.
707 *
708 * Unicode codepoints which do not have a special (legacy) keysym
709 * encoding use a direct encoding scheme. These keysyms don’t usually
710 * have an associated keysym constant (`XKB_KEY_*`).
711 *
712 * @sa `xkb_keysym_to_utf32()`
713 * @since 1.0.0
714 * @since 1.9.0: Enable support for all noncharacters.
715 */
716XKB_EXPORT xkb_keysym_t
717xkb_utf32_to_keysym(uint32_t ucs);
718
719/**
720 * Convert a keysym to its uppercase form.
721 *
722 * If there is no such form, the keysym is returned unchanged.
723 *
724 * The conversion rules are the *simple* (i.e. one-to-one) Unicode case
725 * mappings (with some exceptions, see hereinafter) and do not depend
726 * on the locale. If you need the special case mappings (i.e. not
727 * one-to-one or locale-dependent), prefer to work with the Unicode
728 * representation instead, when possible.
729 *
730 * Exceptions to the Unicode mappings:
731 *
732 * | Lower keysym | Lower letter | Upper keysym | Upper letter | Comment |
733 * | ------------ | ------------ | ------------ | ------------ | ------- |
734 * | `ssharp` | `U+00DF`: ß | `U1E9E` | `U+1E9E`: ẞ | [Council for German Orthography] |
735 *
736 * [Council for German Orthography]: https://www.rechtschreibrat.com/regeln-und-woerterverzeichnis/
737 *
738 * @since 0.8.0: Initial implementation, based on `libX11`.
739 * @since 1.8.0: Use Unicode 16.0 mappings for complete Unicode coverage.
740 * @since 1.12.0: Update to Unicode 17.0.
741 */
742XKB_EXPORT xkb_keysym_t
743xkb_keysym_to_upper(xkb_keysym_t ks);
744
745/**
746 * Convert a keysym to its lowercase form.
747 *
748 * If there is no such form, the keysym is returned unchanged.
749 *
750 * The conversion rules are the *simple* (i.e. one-to-one) Unicode case
751 * mappings and do not depend on the locale. If you need the special
752 * case mappings (i.e. not one-to-one or locale-dependent), prefer to
753 * work with the Unicode representation instead, when possible.
754 *
755 * @since 0.8.0: Initial implementation, based on `libX11`.
756 * @since 1.8.0: Use Unicode 16.0 mappings for complete Unicode coverage.
757 * @since 1.12.0: Update to Unicode 17.0.
758 */
759XKB_EXPORT xkb_keysym_t
760xkb_keysym_to_lower(xkb_keysym_t ks);
761
762/** @} */
763
764/**
765 * @defgroup context Library Context
766 * Creating, destroying and using library contexts.
767 *
768 * Every keymap compilation request must have a context associated with
769 * it. The context keeps around state such as the include path.
770 *
771 * @{
772 */
773
774/**
775 * @page envvars Environment Variables
776 *
777 * The user may set some environment variables which affect the library:
778 *
779 * - `XKB_CONFIG_ROOT`, `XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH`,
780 * `XKB_CONFIG_VERSIONED_EXTENSIONS_PATH`, `XKB_CONFIG_EXTRA_PATH`,
781 * `XDG_CONFIG_DIR`, `HOME` - see @ref include-path.
782 * - `XKB_LOG_LEVEL` - see `xkb_context::xkb_context_set_log_level()`.
783 * - `XKB_LOG_VERBOSITY` - see `xkb_context::xkb_context_set_log_verbosity()`.
784 * - `XKB_DEFAULT_RULES`, `XKB_DEFAULT_MODEL`, `XKB_DEFAULT_LAYOUT`,
785 * `XKB_DEFAULT_VARIANT`, `XKB_DEFAULT_OPTIONS` - see `xkb_rule_names`.
786 */
787
788/** Flags for context creation. */
789enum xkb_context_flags {
790 /** Do not apply any context flags. */
791 XKB_CONTEXT_NO_FLAGS = 0,
792 /**
793 * Create this context with an empty include path.
794 *
795 * This may be useful e.g.:
796 * - to have full control over the included paths;
797 * - for clients that do not need to access the XKB directories, e.g.
798 * if only retrieving keymap from the Wayland or X server. It avoids
799 * potential issues with directory access permissions.
800 */
801 XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
802 /**
803 * Don’t take RMLVO names from the environment.
804 *
805 * @since 0.3.0
806 */
807 XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1),
808 /**
809 * Disable the use of secure_getenv for this context, so that privileged
810 * processes can use environment variables. Client uses at their own risk.
811 *
812 * @since 1.5.0
813 */
814 XKB_CONTEXT_NO_SECURE_GETENV = (1 << 2)
815};
816
817/**
818 * Create a new context.
819 *
820 * @param flags Optional flags for the context, or 0.
821 *
822 * @returns A new context, or `NULL` on failure.
823 *
824 * @memberof xkb_context
825 */
826XKB_EXPORT struct xkb_context *
827xkb_context_new(enum xkb_context_flags flags);
828
829/**
830 * Take a new reference on a context.
831 *
832 * @returns The passed in context.
833 *
834 * @memberof xkb_context
835 */
836XKB_EXPORT struct xkb_context *
837xkb_context_ref(struct xkb_context *context);
838
839/**
840 * Release a reference on a context, and possibly free it.
841 *
842 * @param context The context. If it is `NULL`, this function does nothing.
843 *
844 * @memberof xkb_context
845 */
846XKB_EXPORT void
847xkb_context_unref(struct xkb_context *context);
848
849/**
850 * Store custom user data in the context.
851 *
852 * This may be useful in conjunction with `xkb_context::xkb_context_set_log_fn()`
853 * or other callbacks.
854 *
855 * @memberof xkb_context
856 */
857XKB_EXPORT void
858xkb_context_set_user_data(struct xkb_context *context, void *user_data);
859
860/**
861 * Retrieves stored user data from the context.
862 *
863 * @returns The stored user data. If the user data wasn’t set, or the
864 * passed in context is `NULL`, returns `NULL`.
865 *
866 * This may be useful to access private user data from callbacks like a
867 * custom logging function.
868 *
869 * @memberof xkb_context
870 **/
871XKB_EXPORT void *
872xkb_context_get_user_data(struct xkb_context *context);
873
874/** @} */
875
876/**
877 * @defgroup include-path Include Paths
878 * Manipulating the include paths in a context.
879 *
880 * The include paths are the file-system paths that are searched when an
881 * include statement is encountered during keymap compilation.
882 *
883 * The default include paths are, in that lookup order:
884 *
885 * <dl>
886 * <dt>User</dt>
887 * <dd>
888 * - The path `$XDG_CONFIG_HOME/xkb`, where `$XDG_CONFIG_HOME` is the value of
889 * the environment variable `XDG_CONFIG_HOME`, with the usual fallback to
890 * `$HOME/.config/` if unset.
891 *
892 * See @ref custom-configuration "" for further information.
893 * - @deprecated The *legacy* path `$HOME/.xkb`, where `$HOME` is the value of
894 * the environment variable `HOME`.
895 * <!-- [HACK] blank required by Doxygen -->
896 *
897 * </dd>
898 * <dt>System</dt>
899 * <dd>
900 * - The `XKB_CONFIG_EXTRA_PATH` environment variable, if defined, otherwise the
901 * system configuration directory, defined at library configuration time
902 * (usually `/etc/xkb`).
903 *
904 * One can adapt the @ref custom-configuration "" instructions by replacing
905 * `$XDG_CONFIG_HOME` with the system configuration directory in the
906 * file locations.
907 * - Each subdirectory of each XKB extensions directory (versioned, then
908 * unversioned if no corresponding versioned subdirectory), listed in
909 * lexicographic order. The extensions directories are defined by the
910 * environment variables `XKB_CONFIG_VERSIONED_EXTENSIONS_PATH` and
911 * `XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH` and default to the system XKB
912 * root extensions directories, defined at library configuration time (usually
913 * `/usr/share/xkeyboard-config-<VERSION>.d` and
914 * `/usr/share/xkeyboard-config.d`).
915 *
916 * See @ref packaging-keyboard-layouts "" for further information.
917 * - The `XKB_CONFIG_ROOT` environment variable, if defined, otherwise
918 * the system XKB root, defined at library configuration time
919 * (usually `/usr/share/xkeyboard-config-<VERSION>` or `/usr/share/X11/xkb`).
920 *
921 * @warning Do not modify the system XKB root files, because they will be
922 * overwritten by any update of the `xkeyboard-config`/`xkb-data` package.
923 * - Since 1.12.2: if the previous path failed, it fallbacks to the *legacy X11
924 * path* defined at compilation time (usually `/usr/share/X11/xkb`). This
925 * fallback is skipped is `XKB_CONFIG_ROOT` is explicitly set to an empty
926 * string.
927 * </dd>
928 * </dl>
929 *
930 * @{
931 */
932
933/**
934 * Append a new entry to the context’s include path.
935 *
936 * @returns 1 on success, or 0 if the include path could not be added or is
937 * inaccessible.
938 *
939 * @memberof xkb_context
940 */
941XKB_EXPORT int
942xkb_context_include_path_append(struct xkb_context *context, const char *path);
943
944/**
945 * Append the default include paths to the context’s include path.
946 *
947 * @returns 1 on success, or 0 if no default include path could be added.
948 *
949 * @memberof xkb_context
950 */
951XKB_EXPORT int
952xkb_context_include_path_append_default(struct xkb_context *context);
953
954/**
955 * Reset the context’s include path to the default.
956 *
957 * Removes all entries from the context’s include path, and inserts the
958 * default paths.
959 *
960 * @returns 1 on success, or 0 if the primary include path could not be added.
961 *
962 * @memberof xkb_context
963 */
964XKB_EXPORT int
965xkb_context_include_path_reset_defaults(struct xkb_context *context);
966
967/**
968 * Remove all entries from the context’s include path.
969 *
970 * @memberof xkb_context
971 */
972XKB_EXPORT void
973xkb_context_include_path_clear(struct xkb_context *context);
974
975/**
976 * Get the number of paths in the context’s include path.
977 *
978 * @memberof xkb_context
979 */
980XKB_EXPORT unsigned int
981xkb_context_num_include_paths(struct xkb_context *context);
982
983/**
984 * Get a specific include path from the context’s include path.
985 *
986 * @returns The include path at the specified index. If the index is
987 * invalid, returns NULL.
988 *
989 * @memberof xkb_context
990 */
991XKB_EXPORT const char *
992xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
993
994/** @} */
995
996/**
997 * @defgroup logging Logging Handling
998 * Manipulating how logging from this library is handled.
999 *
1000 * @{
1001 */
1002
1003/** Specifies a logging level. */
1004enum xkb_log_level {
1005 XKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
1006 XKB_LOG_LEVEL_ERROR = 20, /**< Log all errors. */
1007 XKB_LOG_LEVEL_WARNING = 30, /**< Log warnings and errors. */
1008 XKB_LOG_LEVEL_INFO = 40, /**< Log information, warnings, and errors. */
1009 XKB_LOG_LEVEL_DEBUG = 50 /**< Log everything. */
1010};
1011
1012/**
1013 * Set the current logging level.
1014 *
1015 * @param context The context in which to set the logging level.
1016 * @param level The logging level to use. Only messages from this level
1017 * and below will be logged.
1018 *
1019 * The default level is `::XKB_LOG_LEVEL_ERROR`. The environment variable
1020 * `XKB_LOG_LEVEL`, if set in the time the context was created, overrides the
1021 * default value. It may be specified as a level number or name.
1022 *
1023 * @memberof xkb_context
1024 */
1025XKB_EXPORT void
1026xkb_context_set_log_level(struct xkb_context *context,
1027 enum xkb_log_level level);
1028
1029/**
1030 * Get the current logging level.
1031 *
1032 * @memberof xkb_context
1033 */
1034XKB_EXPORT enum xkb_log_level
1035xkb_context_get_log_level(struct xkb_context *context);
1036
1037/**
1038 * Sets the current logging verbosity.
1039 *
1040 * The library can generate a number of warnings which are not helpful to
1041 * ordinary users of the library. The verbosity may be increased if more
1042 * information is desired (e.g. when developing a new keymap).
1043 *
1044 * The default verbosity is 0. The environment variable `XKB_LOG_VERBOSITY`,
1045 * if set in the time the context was created, overrides the default value.
1046 *
1047 * @param context The context in which to use the set verbosity.
1048 * @param verbosity The verbosity to use. Currently used values are
1049 * 1 to 10, higher values being more verbose. 0 would result in no verbose
1050 * messages being logged.
1051 *
1052 * Most verbose messages are of level `::XKB_LOG_LEVEL_WARNING` or lower.
1053 *
1054 * @memberof xkb_context
1055 */
1056XKB_EXPORT void
1057xkb_context_set_log_verbosity(struct xkb_context *context, int verbosity);
1058
1059/**
1060 * Get the current logging verbosity of the context.
1061 *
1062 * @memberof xkb_context
1063 */
1064XKB_EXPORT int
1065xkb_context_get_log_verbosity(struct xkb_context *context);
1066
1067/**
1068 * Set a custom function to handle logging messages.
1069 *
1070 * @param context The context in which to use the set logging function.
1071 * @param log_fn The function that will be called for logging messages.
1072 * Passing `NULL` restores the default function, which logs to stderr.
1073 *
1074 * By default, log messages from this library are printed to stderr. This
1075 * function allows you to replace the default behavior with a custom
1076 * handler. The handler is only called with messages which match the
1077 * current logging level and verbosity settings for the context.
1078 * level is the logging level of the message. @a format and @a args are
1079 * the same as in the `vprintf(3)` function.
1080 *
1081 * You may use `xkb_context::xkb_context_set_user_data()` on the context, and
1082 * then call `xkb_context::xkb_context_get_user_data()` from within the logging
1083 * function to provide it with additional private context.
1084 *
1085 * @memberof xkb_context
1086 */
1087XKB_EXPORT void
1088xkb_context_set_log_fn(struct xkb_context *context,
1089 void (*log_fn)(struct xkb_context *context,
1090 enum xkb_log_level level,
1091 const char *format, va_list args));
1092
1093/** @} */
1094
1095/**
1096 * @defgroup keymap Keymap Creation
1097 * Creating and destroying keymaps.
1098 *
1099 * @{
1100 */
1101
1102/** Flags for keymap compilation. */
1103enum xkb_keymap_compile_flags {
1104 /** Do not apply any flags. */
1105 XKB_KEYMAP_COMPILE_NO_FLAGS = 0
1106};
1107
1108/**
1109 * The possible keymap formats.
1110 *
1111 * See @ref keymap-text-format-v1-v2 "" for the complete description of the
1112 * formats and @ref keymap-support "" for detailed differences between the
1113 * formats.
1114 *
1115 * @remark A keymap can be parsed in one format and serialized in another,
1116 * thanks to automatic fallback mechanisms.
1117 *
1118 * <table>
1119 * <caption>
1120 * Keymap format to use depending on the target protocol
1121 * </caption>
1122 * <thead>
1123 * <tr>
1124 * <th colspan="2">Protocol</th>
1125 * <th colspan="2">libxkbcommon keymap format</th>
1126 * </tr>
1127 * <tr>
1128 * <th>Name</th>
1129 * <th>Keymap format</th>
1130 * <th>Parsing</th>
1131 * <th>Serialization</th>
1132 * </tr>
1133 * </thead>
1134 * <tbody>
1135 * <tr>
1136 * <th>X11</th>
1137 * <td>XKB</td>
1138 * <td>
1139 * `::XKB_KEYMAP_FORMAT_TEXT_V1`
1140 * </td>
1141 * <td>
1142 * *Always* use `::XKB_KEYMAP_FORMAT_TEXT_V1`, since the other formats are
1143 * incompatible.
1144 * </td>
1145 * </tr>
1146 * <tr>
1147 * <th>Wayland</th>
1148 * <td><code>[xkb_v1]</code></td>
1149 * <td>
1150 * <dl>
1151 * <dt>Wayland compositors<dt>
1152 * <dd>
1153 * The format depends on the keyboard layout database (usually [xkeyboard-config]).
1154 * Note that since v2 is a superset of v1, compositors are encouraged to use
1155 * `::XKB_KEYMAP_FORMAT_TEXT_V2` whenever possible.
1156 * </dd>
1157 * <dt>Client apps</dt>
1158 * <dd>
1159 * Clients should use `::XKB_KEYMAP_FORMAT_TEXT_V1` to parse the keymap sent
1160 * by a Wayland compositor, at least until `::XKB_KEYMAP_FORMAT_TEXT_V2`
1161 * stabilizes.
1162 * </dd>
1163 * </td>
1164 * <td>
1165 * At the time of writing (July 2025), the Wayland <code>[xkb_v1]</code> keymap
1166 * format is only defined as “libxkbcommon compatible”. In theory it enables
1167 * flexibility, but the set of supported features varies depending on the
1168 * libxkbcommon version and libxkbcommon keymap format used. Unfortunately there
1169 * is currently no Wayland API for keymap format *negotiation*.
1170 *
1171 * Therefore the **recommended** serialization format is
1172 * `::XKB_KEYMAP_FORMAT_TEXT_V1`, in order to ensure maximum compatibility for
1173 * interchange.
1174 *
1175 * Serializing using `::XKB_KEYMAP_FORMAT_TEXT_V2` should be considered
1176 * **experimental**, as some clients may fail to parse the resulting string.
1177 * </td>
1178 * </tr>
1179 * </tbody>
1180 * </table>
1181 *
1182 * [xkb_v1]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard-enum-keymap_format
1183 * [xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
1184 */
1185enum xkb_keymap_format {
1186 /**
1187 * The classic XKB text format, as generated by `xkbcomp -xkb`.
1188 *
1189 * @important This format should *always* be used when *serializing* a
1190 * keymap for **X11**.
1191 *
1192 * @important For the **Wayland** <code>[xkb_v1]</code> format, it is
1193 * advised to use this format as well for serializing, in order to ensure
1194 * maximum compatibility for interchange.
1195 *
1196 * [xkb_v1]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard-enum-keymap_format
1197 */
1198 XKB_KEYMAP_FORMAT_TEXT_V1 = 1,
1199 /**
1200 * Xkbcommon extensions of the classic XKB text format, **incompatible with
1201 * X11**.
1202 *
1203 * @important Do *not* use when *serializing* a keymap for **X11**
1204 * (incompatible).
1205 *
1206 * @important Considered *experimental* when *serializing* for **Wayland**:
1207 * at the time of writing (July 2025), there is only one XKB keymap format
1208 * <code>[xkb_v1]</code> in Wayland and no Wayland API for keymap format
1209 * *negotiation*, so the clients may not be able to parse the keymap if it
1210 * uses v2-specific features. Therefore a compositor may *parse* keymaps
1211 * using `::XKB_KEYMAP_FORMAT_TEXT_V2` but it should serialize them using
1212 * `::XKB_KEYMAP_FORMAT_TEXT_V1` and rely on the automatic *fallback*
1213 * mechanisms.
1214 *
1215 * @since 1.11.0
1216 *
1217 * [xkb_v1]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard-enum-keymap_format
1218 */
1219 XKB_KEYMAP_FORMAT_TEXT_V2 = 2
1220};
1221
1222/**
1223 * Create a keymap from a [RMLVO] builder.
1224 *
1225 * The primary keymap entry point: creates a new XKB keymap from a set of
1226 * [RMLVO] \(Rules + Model + Layouts + Variants + Options) names.
1227 *
1228 * @param rmlvo The [RMLVO] builder to use. See `xkb_rmlvo_builder`.
1229 * @param format The text format of the keymap file to compile.
1230 * @param flags Optional flags for the keymap, or 0.
1231 *
1232 * @returns A keymap compiled according to the [RMLVO] names, or `NULL` if
1233 * the compilation failed.
1234 *
1235 * @since 1.11.0
1236 * @sa `xkb_keymap_new_from_names2()`
1237 * @sa `xkb_rmlvo_builder`
1238 * @memberof xkb_keymap
1239 *
1240 * [RMLVO]: @ref RMLVO-intro
1241 */
1242XKB_EXPORT struct xkb_keymap *
1243xkb_keymap_new_from_rmlvo(const struct xkb_rmlvo_builder *rmlvo,
1244 enum xkb_keymap_format format,
1245 enum xkb_keymap_compile_flags flags);
1246
1247/**
1248 * Create a keymap from [RMLVO] names.
1249 *
1250 * Same as `xkb_keymap_new_from_names2()`, but with the keymap format fixed to:
1251 * `::XKB_KEYMAP_FORMAT_TEXT_V2`.
1252 *
1253 * @deprecated Use `xkb_keymap_new_from_names2()` instead.
1254 * @since 1.11.0: Deprecated
1255 * @since 1.11.0: Use internally `::XKB_KEYMAP_FORMAT_TEXT_V2` instead of
1256 * `::XKB_KEYMAP_FORMAT_TEXT_V1`
1257 * @sa `xkb_keymap_new_from_names2()`
1258 * @sa `xkb_rule_names`
1259 * @sa `xkb_keymap_new_from_rmlvo()`
1260 * @memberof xkb_keymap
1261 *
1262 * [RMLVO]: @ref RMLVO-intro
1263 */
1264XKB_EXPORT struct xkb_keymap *
1265xkb_keymap_new_from_names(struct xkb_context *context,
1266 const struct xkb_rule_names *names,
1267 enum xkb_keymap_compile_flags flags);
1268
1269/**
1270 * Create a keymap from [RMLVO] names.
1271 *
1272 * The primary keymap entry point: creates a new XKB keymap from a set of
1273 * [RMLVO] \(Rules + Model + Layouts + Variants + Options) names.
1274 *
1275 * @param context The context in which to create the keymap.
1276 * @param names The [RMLVO] names to use. See xkb_rule_names.
1277 * @param format The text format of the keymap file to compile.
1278 * @param flags Optional flags for the keymap, or 0.
1279 *
1280 * @returns A keymap compiled according to the [RMLVO] names, or `NULL` if
1281 * the compilation failed.
1282 *
1283 * @sa `xkb_rule_names`
1284 * @sa `xkb_keymap_new_from_rmlvo()`
1285 * @memberof xkb_keymap
1286 * @since 1.11.0
1287 *
1288 * [RMLVO]: @ref RMLVO-intro
1289 */
1290XKB_EXPORT struct xkb_keymap *
1291xkb_keymap_new_from_names2(struct xkb_context *context,
1292 const struct xkb_rule_names *names,
1293 enum xkb_keymap_format format,
1294 enum xkb_keymap_compile_flags flags);
1295
1296/**
1297 * Create a keymap from a keymap file.
1298 *
1299 * @param context The context in which to create the keymap.
1300 * @param file The keymap file to compile.
1301 * @param format The text format of the keymap file to compile.
1302 * @param flags Optional flags for the keymap, or 0.
1303 *
1304 * @returns A keymap compiled from the given XKB keymap file, or `NULL` if
1305 * the compilation failed.
1306 *
1307 * The file must contain a complete keymap. For example, in the
1308 * `::XKB_KEYMAP_FORMAT_TEXT_V1` format, this means the file must contain one
1309 * top level `%xkb_keymap` section, which in turn contains other required
1310 * sections.
1311 *
1312 * @memberof xkb_keymap
1313 */
1314XKB_EXPORT struct xkb_keymap *
1315xkb_keymap_new_from_file(struct xkb_context *context, FILE *file,
1316 enum xkb_keymap_format format,
1317 enum xkb_keymap_compile_flags flags);
1318
1319/**
1320 * Create a keymap from a keymap string.
1321 *
1322 * This is just like `xkb_keymap_new_from_file()`, but instead of a file, gets
1323 * the keymap as one enormous string.
1324 *
1325 * @see `xkb_keymap_new_from_file()`
1326 * @memberof xkb_keymap
1327 */
1328XKB_EXPORT struct xkb_keymap *
1329xkb_keymap_new_from_string(struct xkb_context *context, const char *string,
1330 enum xkb_keymap_format format,
1331 enum xkb_keymap_compile_flags flags);
1332
1333/**
1334 * Create a keymap from a memory buffer.
1335 *
1336 * This is just like `xkb_keymap_new_from_string()`, but takes a length argument
1337 * so the input string does not have to be zero-terminated.
1338 *
1339 * @see `xkb_keymap_new_from_string()`
1340 * @memberof xkb_keymap
1341 * @since 0.3.0
1342 */
1343XKB_EXPORT struct xkb_keymap *
1344xkb_keymap_new_from_buffer(struct xkb_context *context, const char *buffer,
1345 size_t length, enum xkb_keymap_format format,
1346 enum xkb_keymap_compile_flags flags);
1347
1348/**
1349 * Take a new reference on a keymap.
1350 *
1351 * @returns The passed in keymap.
1352 *
1353 * @memberof xkb_keymap
1354 */
1355XKB_EXPORT struct xkb_keymap *
1356xkb_keymap_ref(struct xkb_keymap *keymap);
1357
1358/**
1359 * Release a reference on a keymap, and possibly free it.
1360 *
1361 * @param keymap The keymap. If it is `NULL`, this function does nothing.
1362 *
1363 * @memberof xkb_keymap
1364 */
1365XKB_EXPORT void
1366xkb_keymap_unref(struct xkb_keymap *keymap);
1367
1368/**
1369 * Get the keymap as a string in the format from which it was created.
1370 * @sa `xkb_keymap::xkb_keymap_get_as_string()`
1371 **/
1372#define XKB_KEYMAP_USE_ORIGINAL_FORMAT ((enum xkb_keymap_format) -1)
1373
1374/**
1375 * Flags to control keymap serialization.
1376 *
1377 * @since 1.12.0
1378 */
1379enum xkb_keymap_serialize_flags {
1380 /** Do not apply any flags. */
1381 XKB_KEYMAP_SERIALIZE_NO_FLAGS = 0,
1382 /** Enable pretty-printing */
1383 XKB_KEYMAP_SERIALIZE_PRETTY = (1 << 0),
1384 /** Do not drop unused bits (key types, compatibility entries) */
1385 XKB_KEYMAP_SERIALIZE_KEEP_UNUSED = (1 << 1),
1386};
1387
1388/**
1389 * Get the compiled keymap as a string.
1390 *
1391 * Same as `xkb_keymap::xkb_keymap_get_as_string2()` using
1392 * `::XKB_KEYMAP_SERIALIZE_NO_FLAGS`.
1393 *
1394 * @since 1.12.0: Drop unused types and compatibility entries and do not
1395 * pretty-print.
1396 *
1397 * @sa `xkb_keymap::xkb_keymap_get_as_string2()`
1398 * @memberof xkb_keymap
1399 */
1400XKB_EXPORT char *
1401xkb_keymap_get_as_string(struct xkb_keymap *keymap,
1402 enum xkb_keymap_format format);
1403
1404/**
1405 * Get the compiled keymap as a string.
1406 *
1407 * @param keymap The keymap to get as a string.
1408 * @param format The keymap format to use for the string. You can pass
1409 * in the special value `::XKB_KEYMAP_USE_ORIGINAL_FORMAT` to use the format
1410 * from which the keymap was originally created. When used as an *interchange*
1411 * format such as Wayland <code>[xkb_v1]</code>, the format should be explicit.
1412 * @param flags Optional flags to control the serialization, or 0.
1413 *
1414 * @returns The keymap as a `NULL`-terminated string, or `NULL` if unsuccessful.
1415 *
1416 * The returned string may be fed back into `xkb_keymap_new_from_string()`
1417 * to get the exact same keymap (possibly in another process, etc.).
1418 *
1419 * The returned string is *dynamically allocated* and should be freed by the
1420 * caller.
1421 *
1422 * @since 1.12.0
1423 *
1424 * @sa `xkb_keymap_get_as_string()`
1425 * @sa `xkb_keymap_new_from_string()`
1426 * @memberof xkb_keymap
1427 *
1428 * [xkb_v1]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard-enum-keymap_format
1429 */
1430XKB_EXPORT char *
1431xkb_keymap_get_as_string2(struct xkb_keymap *keymap,
1432 enum xkb_keymap_format format,
1433 enum xkb_keymap_serialize_flags flags);
1434
1435/** @} */
1436
1437/**
1438 * @defgroup components Keymap Components
1439 * Enumeration of state components in a keymap.
1440 *
1441 * @{
1442 */
1443
1444/**
1445 * Get the minimum keycode in the keymap.
1446 *
1447 * @sa xkb_keycode_t
1448 * @memberof xkb_keymap
1449 * @since 0.3.1
1450 */
1451XKB_EXPORT xkb_keycode_t
1452xkb_keymap_min_keycode(struct xkb_keymap *keymap);
1453
1454/**
1455 * Get the maximum keycode in the keymap.
1456 *
1457 * @sa xkb_keycode_t
1458 * @memberof xkb_keymap
1459 * @since 0.3.1
1460 */
1461XKB_EXPORT xkb_keycode_t
1462xkb_keymap_max_keycode(struct xkb_keymap *keymap);
1463
1464/**
1465 * The iterator used by `xkb_keymap_key_for_each()`.
1466 *
1467 * @sa xkb_keymap_key_for_each
1468 * @memberof xkb_keymap
1469 * @since 0.3.1
1470 */
1471typedef void
1472(*xkb_keymap_key_iter_t)(struct xkb_keymap *keymap, xkb_keycode_t key,
1473 void *data);
1474
1475/**
1476 * Run a specified function for every valid keycode in the keymap. If a
1477 * keymap is sparse, this function may be called fewer than
1478 * (max_keycode - min_keycode + 1) times.
1479 *
1480 * @sa xkb_keymap_min_keycode()
1481 * @sa xkb_keymap_max_keycode()
1482 * @sa xkb_keycode_t
1483 * @memberof xkb_keymap
1484 * @since 0.3.1
1485 */
1486XKB_EXPORT void
1487xkb_keymap_key_for_each(struct xkb_keymap *keymap, xkb_keymap_key_iter_t iter,
1488 void *data);
1489
1490/**
1491 * Find the name of the key with the given keycode.
1492 *
1493 * This function always returns the canonical name of the key (see
1494 * description in `xkb_keycode_t`).
1495 *
1496 * @returns The key name. If no key with this keycode exists,
1497 * returns `NULL`.
1498 *
1499 * @sa xkb_keycode_t
1500 * @memberof xkb_keymap
1501 * @since 0.6.0
1502 */
1503XKB_EXPORT const char *
1504xkb_keymap_key_get_name(struct xkb_keymap *keymap, xkb_keycode_t key);
1505
1506/**
1507 * Find the keycode of the key with the given name.
1508 *
1509 * The name can be either a canonical name or an alias.
1510 *
1511 * @returns The keycode. If no key with this name exists,
1512 * returns `::XKB_KEYCODE_INVALID`.
1513 *
1514 * @sa xkb_keycode_t
1515 * @memberof xkb_keymap
1516 * @since 0.6.0
1517 */
1518XKB_EXPORT xkb_keycode_t
1519xkb_keymap_key_by_name(struct xkb_keymap *keymap, const char *name);
1520
1521/**
1522 * Get the number of modifiers in the keymap.
1523 *
1524 * @sa xkb_mod_index_t
1525 * @memberof xkb_keymap
1526 */
1527XKB_EXPORT xkb_mod_index_t
1528xkb_keymap_num_mods(struct xkb_keymap *keymap);
1529
1530/**
1531 * Get the name of a modifier by index.
1532 *
1533 * @returns The name. If the index is invalid, returns `NULL`.
1534 *
1535 * @sa xkb_mod_index_t
1536 * @memberof xkb_keymap
1537 */
1538XKB_EXPORT const char *
1539xkb_keymap_mod_get_name(struct xkb_keymap *keymap, xkb_mod_index_t idx);
1540
1541/**
1542 * Get the index of a modifier by name.
1543 *
1544 * @returns The index. If no modifier with this name exists, returns
1545 * `::XKB_MOD_INVALID`.
1546 *
1547 * @sa xkb_mod_index_t
1548 * @memberof xkb_keymap
1549 */
1550XKB_EXPORT xkb_mod_index_t
1551xkb_keymap_mod_get_index(struct xkb_keymap *keymap, const char *name);
1552
1553/**
1554 * Get the encoding of a modifier by name.
1555 *
1556 * In X11 terminology it corresponds to the mapping to the *[real modifiers]*.
1557 *
1558 * @returns The encoding of a modifier. Note that it may be 0 if the name does
1559 * not exist or if the modifier is not mapped.
1560 *
1561 * @since 1.10.0
1562 * @sa `xkb_keymap_mod_get_mask2()`
1563 * @memberof xkb_keymap
1564 *
1565 * [real modifiers]: @ref real-modifier-def
1566 */
1567XKB_EXPORT xkb_mod_mask_t
1568xkb_keymap_mod_get_mask(struct xkb_keymap *keymap, const char *name);
1569
1570/**
1571 * Get the encoding of a modifier by index.
1572 *
1573 * In X11 terminology it corresponds to the mapping to the *[real modifiers]*.
1574 *
1575 * @returns The encoding of a modifier. Note that it may be 0 if the modifier is
1576 * not mapped.
1577 *
1578 * @since 1.11.0
1579 * @sa `xkb_keymap_mod_get_mask()`
1580 * @memberof xkb_keymap
1581 *
1582 * [real modifiers]: @ref real-modifier-def
1583 */
1584XKB_EXPORT xkb_mod_mask_t
1585xkb_keymap_mod_get_mask2(struct xkb_keymap *keymap, xkb_mod_index_t idx);
1586
1587/**
1588 * Get the number of layouts in the keymap.
1589 *
1590 * @sa `xkb_layout_index_t`
1591 * @sa `xkb_rule_names`
1592 * @sa `xkb_keymap_num_layouts_for_key()`
1593 * @memberof xkb_keymap
1594 */
1595XKB_EXPORT xkb_layout_index_t
1596xkb_keymap_num_layouts(struct xkb_keymap *keymap);
1597
1598/**
1599 * Get the name of a layout by index.
1600 *
1601 * @returns The name. If the index is invalid, or the layout does not have
1602 * a name, returns `NULL`.
1603 *
1604 * @sa xkb_layout_index_t
1605 * For notes on layout names.
1606 * @memberof xkb_keymap
1607 */
1608XKB_EXPORT const char *
1609xkb_keymap_layout_get_name(struct xkb_keymap *keymap, xkb_layout_index_t idx);
1610
1611/**
1612 * Get the index of a layout by name.
1613 *
1614 * @returns The index. If no layout exists with this name, returns
1615 * `::XKB_LAYOUT_INVALID`. If more than one layout in the keymap has this name,
1616 * returns the lowest index among them.
1617 *
1618 * @sa `xkb_layout_index_t` for notes on layout names.
1619 * @memberof xkb_keymap
1620 */
1621XKB_EXPORT xkb_layout_index_t
1622xkb_keymap_layout_get_index(struct xkb_keymap *keymap, const char *name);
1623
1624/**
1625 * Get the number of LEDs in the keymap.
1626 *
1627 * @warning The range [ 0...`xkb_keymap_num_leds()` ) includes all of the LEDs
1628 * in the keymap, but may also contain inactive LEDs. When iterating over
1629 * this range, you need the handle this case when calling functions such as
1630 * `xkb_keymap_led_get_name()` or `xkb_state::xkb_state_led_index_is_active()`.
1631 *
1632 * @sa xkb_led_index_t
1633 * @memberof xkb_keymap
1634 */
1635XKB_EXPORT xkb_led_index_t
1636xkb_keymap_num_leds(struct xkb_keymap *keymap);
1637
1638/**
1639 * Get the name of a LED by index.
1640 *
1641 * @returns The name. If the index is invalid, returns `NULL`.
1642 *
1643 * @memberof xkb_keymap
1644 */
1645XKB_EXPORT const char *
1646xkb_keymap_led_get_name(struct xkb_keymap *keymap, xkb_led_index_t idx);
1647
1648/**
1649 * Get the index of a LED by name.
1650 *
1651 * @returns The index. If no LED with this name exists, returns
1652 * `::XKB_LED_INVALID`.
1653 *
1654 * @memberof xkb_keymap
1655 */
1656XKB_EXPORT xkb_led_index_t
1657xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name);
1658
1659/**
1660 * Get the number of layouts for a specific key.
1661 *
1662 * This number can be different from `xkb_keymap_num_layouts()`, but is always
1663 * smaller. It is the appropriate value to use when iterating over the
1664 * layouts of a key.
1665 *
1666 * @sa xkb_layout_index_t
1667 * @memberof xkb_keymap
1668 */
1669XKB_EXPORT xkb_layout_index_t
1670xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key);
1671
1672/**
1673 * Get the number of shift levels for a specific key and layout.
1674 *
1675 * If @c layout is out of range for this key (that is, larger or equal to
1676 * the value returned by `xkb_keymap_num_layouts_for_key()`), it is brought
1677 * back into range in a manner consistent with
1678 * `xkb_state::xkb_state_key_get_layout()`.
1679 *
1680 * @sa xkb_level_index_t
1681 * @memberof xkb_keymap
1682 */
1683XKB_EXPORT xkb_level_index_t
1684xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key,
1685 xkb_layout_index_t layout);
1686
1687/**
1688 * Retrieves every possible modifier mask that produces the specified
1689 * shift level for a specific key and layout.
1690 *
1691 * This API is useful for inverse key transformation; i.e. finding out
1692 * which modifiers need to be active in order to be able to type the
1693 * keysym(s) corresponding to the specific key code, layout and level.
1694 *
1695 * @warning It returns only up to masks_size modifier masks. If the
1696 * buffer passed is too small, some of the possible modifier combinations
1697 * will not be returned.
1698 *
1699 * @param[in] keymap The keymap.
1700 * @param[in] key The keycode of the key.
1701 * @param[in] layout The layout for which to get modifiers.
1702 * @param[in] level The shift level in the layout for which to get the
1703 * modifiers. This should be smaller than:
1704 * @code xkb_keymap_num_levels_for_key(keymap, key) @endcode
1705 * @param[out] masks_out A buffer in which the requested masks should be
1706 * stored.
1707 * @param[out] masks_size The number of elements in the buffer pointed to by
1708 * masks_out.
1709 *
1710 * If @c layout is out of range for this key (that is, larger or equal to
1711 * the value returned by `xkb_keymap_num_layouts_for_key()`), it is brought
1712 * back into range in a manner consistent with
1713 * `xkb_state::xkb_state_key_get_layout()`.
1714 *
1715 * @returns The number of modifier masks stored in the masks_out array.
1716 * If the key is not in the keymap or if the specified shift level cannot
1717 * be reached it returns 0 and does not modify the masks_out buffer.
1718 *
1719 * @sa xkb_level_index_t
1720 * @sa xkb_mod_mask_t
1721 * @memberof xkb_keymap
1722 * @since 1.0.0
1723 */
1724XKB_EXPORT size_t
1725xkb_keymap_key_get_mods_for_level(struct xkb_keymap *keymap,
1726 xkb_keycode_t key,
1727 xkb_layout_index_t layout,
1728 xkb_level_index_t level,
1729 xkb_mod_mask_t *masks_out,
1730 size_t masks_size);
1731
1732/**
1733 * Get the keysyms obtained from pressing a key in a given layout and
1734 * shift level.
1735 *
1736 * This function is like `xkb_state::xkb_state_key_get_syms()`, only the layout
1737 * and shift level are not derived from the keyboard state but are instead
1738 * specified explicitly.
1739 *
1740 * @param[in] keymap The keymap.
1741 * @param[in] key The keycode of the key.
1742 * @param[in] layout The layout for which to get the keysyms.
1743 * @param[in] level The shift level in the layout for which to get the
1744 * keysyms. This should be smaller than:
1745 * @code xkb_keymap_num_levels_for_key(keymap, key) @endcode
1746 * @param[out] syms_out An immutable array of keysyms corresponding to the
1747 * key in the given layout and shift level.
1748 *
1749 * If @c layout is out of range for this key (that is, larger or equal to
1750 * the value returned by `xkb_keymap_num_layouts_for_key()`), it is brought
1751 * back into range in a manner consistent with
1752 * `xkb_state::xkb_state_key_get_layout()`.
1753 *
1754 * @returns The number of keysyms in the syms_out array. If no keysyms
1755 * are produced by the key in the given layout and shift level, returns 0
1756 * and sets @p syms_out to `NULL`.
1757 *
1758 * @sa `xkb_state::xkb_state_key_get_syms()`
1759 * @memberof xkb_keymap
1760 */
1761XKB_EXPORT int
1762xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap,
1763 xkb_keycode_t key,
1764 xkb_layout_index_t layout,
1765 xkb_level_index_t level,
1766 const xkb_keysym_t **syms_out);
1767
1768/**
1769 * Determine whether a key should repeat or not.
1770 *
1771 * A keymap may specify different repeat behaviors for different keys.
1772 * Most keys should generally exhibit repeat behavior; for example, holding
1773 * the `a` key down in a text editor should normally insert a single ‘a’
1774 * character every few milliseconds, until the key is released. However,
1775 * there are keys which should not or do not need to be repeated. For
1776 * example, repeating modifier keys such as Left/Right Shift or Caps Lock
1777 * is not generally useful or desired.
1778 *
1779 * @returns 1 if the key should repeat, 0 otherwise.
1780 *
1781 * @memberof xkb_keymap
1782 */
1783XKB_EXPORT int
1784xkb_keymap_key_repeats(struct xkb_keymap *keymap, xkb_keycode_t key);
1785
1786/** @} */
1787
1788/**
1789 * @defgroup state Keyboard State
1790 * Creating, destroying and manipulating keyboard state objects.
1791 *
1792 * @{
1793 */
1794
1795/**
1796 * Create a new keyboard state object.
1797 *
1798 * @param keymap The keymap which the state will use.
1799 *
1800 * @returns A new keyboard state object, or `NULL` on failure.
1801 *
1802 * @memberof xkb_state
1803 */
1804XKB_EXPORT struct xkb_state *
1805xkb_state_new(struct xkb_keymap *keymap);
1806
1807/**
1808 * Take a new reference on a keyboard state object.
1809 *
1810 * @returns The passed in object.
1811 *
1812 * @memberof xkb_state
1813 */
1814XKB_EXPORT struct xkb_state *
1815xkb_state_ref(struct xkb_state *state);
1816
1817/**
1818 * Release a reference on a keyboard state object, and possibly free it.
1819 *
1820 * @param state The state. If it is `NULL`, this function does nothing.
1821 *
1822 * @memberof xkb_state
1823 */
1824XKB_EXPORT void
1825xkb_state_unref(struct xkb_state *state);
1826
1827/**
1828 * Get the keymap which a keyboard state object is using.
1829 *
1830 * @returns The keymap which was passed to `xkb_state_new()` when creating
1831 * this state object.
1832 *
1833 * This function does not take a new reference on the keymap; you must
1834 * explicitly reference it yourself if you plan to use it beyond the
1835 * lifetime of the state.
1836 *
1837 * @memberof xkb_state
1838 */
1839XKB_EXPORT struct xkb_keymap *
1840xkb_state_get_keymap(struct xkb_state *state);
1841
1842/**
1843 * @page server-client-state Server State and Client State
1844 * @parblock
1845 *
1846 * The xkb_state API is used by two distinct actors in most window-system
1847 * architectures:
1848 *
1849 * 1. A *server* - for example, a Wayland compositor, an X11 server, an evdev
1850 * listener.
1851 *
1852 * Servers maintain the XKB state for a device according to input events from
1853 * the device, such as key presses and releases, and out-of-band events from
1854 * the user, like UI layout switchers.
1855 *
1856 * 2. A *client* - for example, a Wayland client, an X11 client.
1857 *
1858 * Clients do not listen to input from the device; instead, whenever the
1859 * server state changes, the server serializes the state and notifies the
1860 * clients that the state has changed; the clients then update the state
1861 * from the serialization.
1862 *
1863 * Some entry points in the xkb_state API are only meant for servers and some
1864 * are only meant for clients, and the two should generally not be mixed.
1865 *
1866 * @endparblock
1867 */
1868
1869/** Specifies the direction of the key (press / release). */
1870enum xkb_key_direction {
1871 XKB_KEY_UP, /**< The key was released. */
1872 XKB_KEY_DOWN /**< The key was pressed. */
1873};
1874
1875/**
1876 * Modifier and layout types for state objects. This enum is bitmaskable,
1877 * e.g. (`::XKB_STATE_MODS_DEPRESSED` | `::XKB_STATE_MODS_LATCHED`) is valid to
1878 * exclude locked modifiers.
1879 *
1880 * In XKB, the `DEPRESSED` components are also known as *base*.
1881 */
1882enum xkb_state_component {
1883 /** Depressed modifiers, i.e. a key is physically holding them. */
1884 XKB_STATE_MODS_DEPRESSED = (1 << 0),
1885 /** Latched modifiers, i.e. will be unset after the next non-modifier
1886 * key press. */
1887 XKB_STATE_MODS_LATCHED = (1 << 1),
1888 /** Locked modifiers, i.e. will be unset after the key provoking the
1889 * lock has been pressed again. */
1890 XKB_STATE_MODS_LOCKED = (1 << 2),
1891 /** Effective modifiers, i.e. currently active and affect key
1892 * processing (derived from the other state components).
1893 * Use this unless you explicitly care how the state came about. */
1894 XKB_STATE_MODS_EFFECTIVE = (1 << 3),
1895 /** Depressed layout, i.e. a key is physically holding it. */
1896 XKB_STATE_LAYOUT_DEPRESSED = (1 << 4),
1897 /** Latched layout, i.e. will be unset after the next non-modifier
1898 * key press. */
1899 XKB_STATE_LAYOUT_LATCHED = (1 << 5),
1900 /** Locked layout, i.e. will be unset after the key provoking the lock
1901 * has been pressed again. */
1902 XKB_STATE_LAYOUT_LOCKED = (1 << 6),
1903 /** Effective layout, i.e. currently active and affects key processing
1904 * (derived from the other state components).
1905 * Use this unless you explicitly care how the state came about. */
1906 XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7),
1907 /** LEDs (derived from the other state components). */
1908 XKB_STATE_LEDS = (1 << 8)
1909};
1910
1911/**
1912 * Update the keyboard state to reflect a given key being pressed or
1913 * released.
1914 *
1915 * This entry point is intended for *server* applications and should not be used
1916 * by *client* applications; see @ref server-client-state for details.
1917 *
1918 * A series of calls to this function should be consistent; that is, a call
1919 * with `::XKB_KEY_DOWN` for a key should be matched by an `::XKB_KEY_UP`; if a
1920 * key is pressed twice, it should be released twice; etc. Otherwise (e.g. due
1921 * to missed input events), situations like “stuck modifiers” may occur.
1922 *
1923 * This function is often used in conjunction with the function
1924 * `xkb_state_key_get_syms()` (or `xkb_state_key_get_one_sym()`), for example,
1925 * when handling a key event. In this case, you should prefer to get the
1926 * keysyms *before* updating the key, such that the keysyms reported for
1927 * the key event are not affected by the event itself. This is the
1928 * conventional behavior.
1929 *
1930 * @returns A mask of state components that have changed as a result of
1931 * the update. If nothing in the state has changed, returns 0.
1932 *
1933 * @memberof xkb_state
1934 *
1935 * @sa `xkb_state_update_mask()`
1936 */
1937XKB_EXPORT enum xkb_state_component
1938xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
1939 enum xkb_key_direction direction);
1940
1941/**
1942 * Update the keyboard state to change the latched and locked state of
1943 * the modifiers and layout.
1944 *
1945 * This entry point is intended for *server* applications and should not be used
1946 * by *client* applications; see @ref server-client-state for details.
1947 *
1948 * Use this function to update the latched and locked state according to
1949 * “out of band” (non-device) inputs, such as UI layout switchers.
1950 *
1951 * @par Layout out of range
1952 * @parblock
1953 *
1954 * If the effective layout, after taking into account the depressed, latched and
1955 * locked layout, is out of range (negative or greater than the maximum layout),
1956 * it is brought into range. Currently, the layout is wrapped using integer
1957 * modulus (with negative values wrapping from the end). The wrapping behavior
1958 * may be made configurable in the future.
1959 *
1960 * @endparblock
1961 *
1962 * @param state The keyboard state object.
1963 * @param affect_latched_mods
1964 * @param latched_mods
1965 * Modifiers to set as latched or unlatched. Only modifiers in
1966 * @p affect_latched_mods are considered.
1967 * @param affect_latched_layout
1968 * @param latched_layout
1969 * Layout to latch. Only considered if @p affect_latched_layout is true.
1970 * Maybe be out of range (including negative) -- see note above.
1971 * @param affect_locked_mods
1972 * @param locked_mods
1973 * Modifiers to set as locked or unlocked. Only modifiers in
1974 * @p affect_locked_mods are considered.
1975 * @param affect_locked_layout
1976 * @param locked_layout
1977 * Layout to lock. Only considered if @p affect_locked_layout is true.
1978 * Maybe be out of range (including negative) -- see note above.
1979 *
1980 * @returns A mask of state components that have changed as a result of
1981 * the update. If nothing in the state has changed, returns 0.
1982 *
1983 * @memberof xkb_state
1984 *
1985 * @sa xkb_state_update_mask()
1986 */
1987XKB_EXPORT enum xkb_state_component
1988xkb_state_update_latched_locked(struct xkb_state *state,
1989 xkb_mod_mask_t affect_latched_mods,
1990 xkb_mod_mask_t latched_mods,
1991 bool affect_latched_layout,
1992 int32_t latched_layout,
1993 xkb_mod_mask_t affect_locked_mods,
1994 xkb_mod_mask_t locked_mods,
1995 bool affect_locked_layout,
1996 int32_t locked_layout);
1997
1998/**
1999 * Update a keyboard state from a set of explicit masks.
2000 *
2001 * This entry point is intended for *client* applications; see @ref
2002 * server-client-state for details. *Server* applications should use
2003 * `xkb_state_update_key()` instead.
2004 *
2005 * All parameters must always be passed, or the resulting state may be
2006 * incoherent.
2007 *
2008 * @warning The serialization is lossy and will not survive round trips; it must
2009 * only be used to feed client state objects, and must not be used to update the
2010 * server state.
2011 *
2012 * @returns A mask of state components that have changed as a result of
2013 * the update. If nothing in the state has changed, returns 0.
2014 *
2015 * @memberof xkb_state
2016 *
2017 * @sa `xkb_state_component`
2018 * @sa `xkb_state_update_key()`
2019 */
2020XKB_EXPORT enum xkb_state_component
2021xkb_state_update_mask(struct xkb_state *state,
2022 xkb_mod_mask_t depressed_mods,
2023 xkb_mod_mask_t latched_mods,
2024 xkb_mod_mask_t locked_mods,
2025 xkb_layout_index_t depressed_layout,
2026 xkb_layout_index_t latched_layout,
2027 xkb_layout_index_t locked_layout);
2028
2029/**
2030 * Get the keysyms obtained from pressing a particular key in a given
2031 * keyboard state.
2032 *
2033 * Get the keysyms for a key according to the current active layout,
2034 * modifiers and shift level for the key, as determined by a keyboard
2035 * state.
2036 *
2037 * @param[in] state The keyboard state object.
2038 * @param[in] key The keycode of the key.
2039 * @param[out] syms_out An immutable array of keysyms corresponding the
2040 * key in the given keyboard state.
2041 *
2042 * As an extension to XKB, this function can return more than one keysym.
2043 * If you do not want to handle this case, you can use
2044 * `xkb_state_key_get_one_sym()` for a simpler interface.
2045 *
2046 * @returns The number of keysyms in the syms_out array. If no keysyms
2047 * are produced by the key in the given keyboard state, returns 0 and sets
2048 * syms_out to `NULL`.
2049 *
2050 * This function performs Capitalization @ref keysym-transformations.
2051 *
2052 * @memberof xkb_state
2053 *
2054 * @since 1.9.0 This function now performs @ref keysym-transformations.
2055 */
2056XKB_EXPORT int
2057xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
2058 const xkb_keysym_t **syms_out);
2059
2060/**
2061 * Get the Unicode/UTF-8 string obtained from pressing a particular key
2062 * in a given keyboard state.
2063 *
2064 * @param[in] state The keyboard state object.
2065 * @param[in] key The keycode of the key.
2066 * @param[out] buffer A buffer to write the string into.
2067 * @param[in] size Size of the buffer.
2068 *
2069 * @warning If the buffer passed is too small, the string is truncated
2070 * (though still `NULL`-terminated).
2071 *
2072 * @returns The number of bytes required for the string, excluding the
2073 * `NULL` byte. If there is nothing to write, returns 0.
2074 *
2075 * You may check if truncation has occurred by comparing the return value
2076 * with the size of @p buffer, similarly to the `snprintf(3)` function.
2077 * You may safely pass `NULL` and 0 to @p buffer and @p size to find the
2078 * required size (without the `NULL`-byte).
2079 *
2080 * This function performs Capitalization and Control @ref
2081 * keysym-transformations.
2082 *
2083 * @memberof xkb_state
2084 * @since 0.4.1
2085 */
2086XKB_EXPORT int
2087xkb_state_key_get_utf8(struct xkb_state *state, xkb_keycode_t key,
2088 char *buffer, size_t size);
2089
2090/**
2091 * Get the Unicode/UTF-32 codepoint obtained from pressing a particular
2092 * key in a a given keyboard state.
2093 *
2094 * @returns The UTF-32 representation for the key, if it consists of only
2095 * a single codepoint. Otherwise, returns 0.
2096 *
2097 * This function performs Capitalization and Control @ref
2098 * keysym-transformations.
2099 *
2100 * @memberof xkb_state
2101 * @since 0.4.1
2102 */
2103XKB_EXPORT uint32_t
2104xkb_state_key_get_utf32(struct xkb_state *state, xkb_keycode_t key);
2105
2106/**
2107 * Get the single keysym obtained from pressing a particular key in a
2108 * given keyboard state.
2109 *
2110 * This function is similar to `xkb_state_key_get_syms()`, but intended
2111 * for users which cannot or do not want to handle the case where
2112 * multiple keysyms are returned (in which case this function is
2113 * preferred).
2114 *
2115 * @returns The keysym. If the key does not have exactly one keysym,
2116 * returns `XKB_KEY_NoSymbol`.
2117 *
2118 * This function performs Capitalization @ref keysym-transformations.
2119 *
2120 * @sa xkb_state_key_get_syms()
2121 * @memberof xkb_state
2122 */
2123XKB_EXPORT xkb_keysym_t
2124xkb_state_key_get_one_sym(struct xkb_state *state, xkb_keycode_t key);
2125
2126/**
2127 * Get the effective layout index for a key in a given keyboard state.
2128 *
2129 * @returns The layout index for the key in the given keyboard state. If
2130 * the given keycode is invalid, or if the key is not included in any
2131 * layout at all, returns `::XKB_LAYOUT_INVALID`.
2132 *
2133 * @invariant If the returned layout is valid, the following always holds:
2134 * @code
2135 * xkb_state_key_get_layout(state, key) < xkb_keymap_num_layouts_for_key(keymap, key)
2136 * @endcode
2137 *
2138 * @memberof xkb_state
2139 */
2140XKB_EXPORT xkb_layout_index_t
2141xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t key);
2142
2143/**
2144 * Get the effective shift level for a key in a given keyboard state and
2145 * layout.
2146 *
2147 * @param state The keyboard state.
2148 * @param key The keycode of the key.
2149 * @param layout The layout for which to get the shift level. This must be
2150 * smaller than:
2151 * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
2152 * usually it would be:
2153 * @code xkb_state_key_get_layout(state, key) @endcode
2154 *
2155 * @return The shift level index. If the key or layout are invalid,
2156 * returns `::XKB_LEVEL_INVALID`.
2157 *
2158 * @invariant If the returned level is valid, the following always holds:
2159 * @code
2160 * xkb_state_key_get_level(state, key, layout) < xkb_keymap_num_levels_for_key(keymap, key, layout)
2161 * @endcode
2162 *
2163 * @memberof xkb_state
2164 */
2165XKB_EXPORT xkb_level_index_t
2166xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key,
2167 xkb_layout_index_t layout);
2168
2169/**
2170 * Match flags for `xkb_state::xkb_state_mod_indices_are_active()` and
2171 * `xkb_state::xkb_state_mod_names_are_active()`, specifying the conditions for a
2172 * successful match. `::XKB_STATE_MATCH_NON_EXCLUSIVE` is bitmaskable with
2173 * the other modes.
2174 */
2175enum xkb_state_match {
2176 /** Returns true if any of the modifiers are active. */
2177 XKB_STATE_MATCH_ANY = (1 << 0),
2178 /** Returns true if all of the modifiers are active. */
2179 XKB_STATE_MATCH_ALL = (1 << 1),
2180 /** Makes matching non-exclusive, i.e. will not return false if a
2181 * modifier not specified in the arguments is active. */
2182 XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16)
2183};
2184
2185/**
2186 * The counterpart to `xkb_state::xkb_state_update_mask()` for modifiers, to be
2187 * used on the server side of serialization.
2188 *
2189 * This entry point is intended for *server* applications; see @ref
2190 * server-client-state for details. *Client* applications should use the
2191 * `xkb_state_mod_*_is_active` API.
2192 *
2193 * @param state The keyboard state.
2194 * @param components A mask of the modifier state components to serialize.
2195 * State components other than `XKB_STATE_MODS_*` are ignored.
2196 * If `::XKB_STATE_MODS_EFFECTIVE` is included, all other state components are
2197 * ignored.
2198 *
2199 * @returns A `xkb_mod_mask_t` representing the given components of the
2200 * modifier state.
2201 *
2202 * @memberof xkb_state
2203 */
2204XKB_EXPORT xkb_mod_mask_t
2205xkb_state_serialize_mods(struct xkb_state *state,
2206 enum xkb_state_component components);
2207
2208/**
2209 * The counterpart to `xkb_state::xkb_state_update_mask()` for layouts, to be
2210 * used on the server side of serialization.
2211 *
2212 * This entry point is intended for *server* applications; see @ref
2213 * server-client-state for details. *Client* applications should use the
2214 * xkb_state_layout_*_is_active API.
2215 *
2216 * @param state The keyboard state.
2217 * @param components A mask of the layout state components to serialize.
2218 * State components other than `XKB_STATE_LAYOUT_*` are ignored.
2219 * If `::XKB_STATE_LAYOUT_EFFECTIVE` is included, all other state components are
2220 * ignored.
2221 *
2222 * @returns A layout index representing the given components of the
2223 * layout state.
2224 *
2225 * @memberof xkb_state
2226 */
2227XKB_EXPORT xkb_layout_index_t
2228xkb_state_serialize_layout(struct xkb_state *state,
2229 enum xkb_state_component components);
2230
2231/**
2232 * Test whether a modifier is active in a given keyboard state by name.
2233 *
2234 * @warning For [virtual modifiers], this function may *overmatch* in case
2235 * there are virtual modifiers with overlapping mappings to [real modifiers].
2236 *
2237 * @returns 1 if the modifier is active, 0 if it is not. If the modifier
2238 * name does not exist in the keymap, returns -1.
2239 *
2240 * @memberof xkb_state
2241 *
2242 * @since 0.1.0: Works only with *real* modifiers
2243 * @since 1.8.0: Works also with *virtual* modifiers
2244 *
2245 * [virtual modifiers]: @ref virtual-modifier-def
2246 * [real modifiers]: @ref real-modifier-def
2247 */
2248XKB_EXPORT int
2249xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
2250 enum xkb_state_component type);
2251
2252/**
2253 * Test whether a set of modifiers are active in a given keyboard state by
2254 * name.
2255 *
2256 * @warning For [virtual modifiers], this function may *overmatch* in case
2257 * there are virtual modifiers with overlapping mappings to [real modifiers].
2258 *
2259 * @param state The keyboard state.
2260 * @param type The component of the state against which to match the
2261 * given modifiers.
2262 * @param match The manner by which to match the state against the
2263 * given modifiers.
2264 * @param ... The set of of modifier names to test, terminated by a NULL
2265 * argument (sentinel).
2266 *
2267 * @returns 1 if the modifiers are active, 0 if they are not. If any of
2268 * the modifier names do not exist in the keymap, returns -1.
2269 *
2270 * @memberof xkb_state
2271 *
2272 * @since 0.1.0: Works only with *real* modifiers
2273 * @since 1.8.0: Works also with *virtual* modifiers
2274 *
2275 * [virtual modifiers]: @ref virtual-modifier-def
2276 * [real modifiers]: @ref real-modifier-def
2277 */
2278XKB_EXPORT int
2279xkb_state_mod_names_are_active(struct xkb_state *state,
2280 enum xkb_state_component type,
2281 enum xkb_state_match match,
2282 ...);
2283
2284/**
2285 * Test whether a modifier is active in a given keyboard state by index.
2286 *
2287 * @warning For [virtual modifiers], this function may *overmatch* in case
2288 * there are virtual modifiers with overlapping mappings to [real modifiers].
2289 *
2290 * @returns 1 if the modifier is active, 0 if it is not. If the modifier
2291 * index is invalid in the keymap, returns -1.
2292 *
2293 * @memberof xkb_state
2294 *
2295 * @since 0.1.0: Works only with *real* modifiers
2296 * @since 1.8.0: Works also with *virtual* modifiers
2297 *
2298 * [virtual modifiers]: @ref virtual-modifier-def
2299 * [real modifiers]: @ref real-modifier-def
2300 */
2301XKB_EXPORT int
2302xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
2303 enum xkb_state_component type);
2304
2305/**
2306 * Test whether a set of modifiers are active in a given keyboard state by
2307 * index.
2308 *
2309 * @warning For [virtual modifiers], this function may *overmatch* in case
2310 * there are virtual modifiers with overlapping mappings to [real modifiers].
2311 *
2312 * @param state The keyboard state.
2313 * @param type The component of the state against which to match the
2314 * given modifiers.
2315 * @param match The manner by which to match the state against the
2316 * given modifiers.
2317 * @param ... The set of of modifier indices to test, terminated by a
2318 * `::XKB_MOD_INVALID` argument (sentinel).
2319 *
2320 * @returns 1 if the modifiers are active, 0 if they are not. If any of
2321 * the modifier indices are invalid in the keymap, returns -1.
2322 *
2323 * @memberof xkb_state
2324 *
2325 * @since 0.1.0: Works only with *real* modifiers
2326 * @since 1.8.0: Works also with *virtual* modifiers
2327 *
2328 * [virtual modifiers]: @ref virtual-modifier-def
2329 * [real modifiers]: @ref real-modifier-def
2330 */
2331XKB_EXPORT int
2332xkb_state_mod_indices_are_active(struct xkb_state *state,
2333 enum xkb_state_component type,
2334 enum xkb_state_match match,
2335 ...);
2336
2337/**
2338 * @page consumed-modifiers Consumed Modifiers
2339 * @parblock
2340 *
2341 * Some functions, like `xkb_state::xkb_state_key_get_syms()`, look at the state
2342 * of the modifiers in the keymap and derive from it the correct shift level
2343 * to use for the key. For example, in a US layout, pressing the key
2344 * labeled `<A>` while the Shift modifier is active, generates the keysym
2345 * `A`. In this case, the Shift modifier is said to be *consumed*.
2346 * However, the Num Lock modifier does not affect this translation at all,
2347 * even if it is active, so it is not consumed by this translation.
2348 *
2349 * It may be desirable for some application to not reuse consumed modifiers
2350 * for further processing, e.g. for hotkeys or keyboard shortcuts. To
2351 * understand why, consider some requirements from a standard shortcut
2352 * mechanism, and how they are implemented:
2353 *
2354 * 1. The shortcut’s modifiers must match exactly to the state. For
2355 * example, it is possible to bind separate actions to `<Alt><Tab>`
2356 * and to `<Alt><Shift><Tab>`. Further, if only `<Alt><Tab>` is
2357 * bound to an action, pressing `<Alt><Shift><Tab>` should not
2358 * trigger the shortcut.
2359 * Effectively, this means that the modifiers are compared using the
2360 * equality operator (`==`).
2361 *
2362 * 2. Only relevant modifiers are considered for the matching. For example,
2363 * Caps Lock and Num Lock should not generally affect the matching, e.g.
2364 * when matching `<Alt><Tab>` against the state, it does not matter
2365 * whether Num Lock is active or not. These relevant, or *significant*,
2366 * modifiers usually include Alt, Control, Shift, Super and similar.
2367 * Effectively, this means that non-significant modifiers are masked out,
2368 * before doing the comparison as described above.
2369 *
2370 * 3. The matching must be independent of the layout/keymap. For example,
2371 * the `<Plus>` (+) symbol is found on the first level on some layouts,
2372 * but requires holding Shift on others. If you simply bind the action
2373 * to the `<Plus>` keysym, it would work for the unshifted kind, but
2374 * not for the others, because the match against Shift would fail. If
2375 * you bind the action to `<Shift><Plus>`, only the shifted kind would
2376 * work. So what is needed is to recognize that Shift is used up in the
2377 * translation of the keysym itself, and therefore should not be included
2378 * in the matching.
2379 * Effectively, this means that consumed modifiers (Shift in this example)
2380 * are masked out as well, before doing the comparison.
2381 *
2382 * In summary, this is approximately how the matching would be performed:
2383 *
2384 * ```c
2385 * (keysym == shortcut_keysym) &&
2386 * ((state_mods & ~consumed_mods & significant_mods) == shortcut_mods)
2387 * ```
2388 *
2389 * @c state_mods are the modifiers reported by
2390 * `xkb_state::xkb_state_mod_index_is_active()` and similar functions.
2391 * @c consumed_mods are the modifiers reported by
2392 * `xkb_state::xkb_state_mod_index_is_consumed()` and similar functions.
2393 * @c significant_mods are decided upon by the application/toolkit/user;
2394 * it is up to them to decide whether these are configurable or hard-coded.
2395 *
2396 * @endparblock
2397 */
2398
2399/**
2400 * Consumed modifiers mode.
2401 *
2402 * There are several possible methods for deciding which modifiers are
2403 * consumed and which are not, each applicable for different systems or
2404 * situations. The mode selects the method to use.
2405 *
2406 * Keep in mind that in all methods, the keymap may decide to *preserve*
2407 * a modifier, meaning it is not reported as consumed even if it would
2408 * have otherwise.
2409 */
2410enum xkb_consumed_mode {
2411 /**
2412 * This is the mode defined in the XKB specification and used by libX11.
2413 *
2414 * A modifier is consumed if and only if it *may affect* key translation.
2415 *
2416 * For example, if `Control+Alt+<Backspace>` produces some assigned keysym,
2417 * then when pressing just `<Backspace>`, `Control` and `Alt` are consumed,
2418 * even though they are not active, since if they *were* active they would
2419 * have affected key translation.
2420 */
2421 XKB_CONSUMED_MODE_XKB,
2422 /**
2423 * This is the mode used by the GTK+ toolkit.
2424 *
2425 * The mode consists of the following two independent heuristics:
2426 *
2427 * - The currently active set of modifiers, excluding modifiers which do
2428 * not affect the key (as described for @ref XKB_CONSUMED_MODE_XKB), are
2429 * considered consumed, if the keysyms produced when all of them are
2430 * active are different from the keysyms produced when no modifiers are
2431 * active.
2432 *
2433 * - A single modifier is considered consumed if the keysyms produced for
2434 * the key when it is the only active modifier are different from the
2435 * keysyms produced when no modifiers are active.
2436 */
2437 XKB_CONSUMED_MODE_GTK
2438};
2439
2440/**
2441 * Get the mask of modifiers consumed by translating a given key.
2442 *
2443 * @param state The keyboard state.
2444 * @param key The keycode of the key.
2445 * @param mode The consumed modifiers mode to use; see enum description.
2446 *
2447 * @returns a mask of the consumed [real modifiers] modifiers.
2448 *
2449 * @memberof xkb_state
2450 * @since 0.7.0
2451 *
2452 * [real modifiers]: @ref real-modifier-def
2453 */
2454XKB_EXPORT xkb_mod_mask_t
2455xkb_state_key_get_consumed_mods2(struct xkb_state *state, xkb_keycode_t key,
2456 enum xkb_consumed_mode mode);
2457
2458/**
2459 * Same as `xkb_state_key_get_consumed_mods2()` with mode `::XKB_CONSUMED_MODE_XKB`.
2460 *
2461 * @memberof xkb_state
2462 * @since 0.4.1
2463 */
2464XKB_EXPORT xkb_mod_mask_t
2465xkb_state_key_get_consumed_mods(struct xkb_state *state, xkb_keycode_t key);
2466
2467/**
2468 * Test whether a modifier is consumed by keyboard state translation for
2469 * a key.
2470 *
2471 * @warning For [virtual modifiers], this function may *overmatch* in case
2472 * there are virtual modifiers with overlapping mappings to [real modifiers].
2473 *
2474 * @param state The keyboard state.
2475 * @param key The keycode of the key.
2476 * @param idx The index of the modifier to check.
2477 * @param mode The consumed modifiers mode to use; see enum description.
2478 *
2479 * @returns 1 if the modifier is consumed, 0 if it is not. If the modifier
2480 * index is not valid in the keymap, returns -1.
2481 *
2482 * @sa xkb_state_mod_mask_remove_consumed()
2483 * @sa xkb_state_key_get_consumed_mods()
2484 * @memberof xkb_state
2485 * @since 0.7.0: Works only with *real* modifiers
2486 * @since 1.8.0: Works also with *virtual* modifiers
2487 *
2488 * [virtual modifiers]: @ref virtual-modifier-def
2489 * [real modifiers]: @ref real-modifier-def
2490 */
2491XKB_EXPORT int
2492xkb_state_mod_index_is_consumed2(struct xkb_state *state,
2493 xkb_keycode_t key,
2494 xkb_mod_index_t idx,
2495 enum xkb_consumed_mode mode);
2496
2497/**
2498 * Same as `xkb_state_mod_index_is_consumed2()` with mode `::XKB_CONSUMED_MOD_XKB`.
2499 *
2500 * @warning For [virtual modifiers], this function may *overmatch* in case
2501 * there are virtual modifiers with overlapping mappings to [real modifiers].
2502 *
2503 * @memberof xkb_state
2504 * @since 0.4.1: Works only with *real* modifiers
2505 * @since 1.8.0: Works also with *virtual* modifiers
2506 *
2507 * [virtual modifiers]: @ref virtual-modifier-def
2508 * [real modifiers]: @ref real-modifier-def
2509 */
2510XKB_EXPORT int
2511xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key,
2512 xkb_mod_index_t idx);
2513
2514/**
2515 * Remove consumed modifiers from a modifier mask for a key.
2516 *
2517 * @deprecated Use `xkb_state_key_get_consumed_mods2()` instead.
2518 *
2519 * Takes the given modifier mask, and removes all modifiers which are
2520 * consumed for that particular key (as in `xkb_state_mod_index_is_consumed()`).
2521 *
2522 * @returns a mask of [real modifiers] modifiers.
2523 *
2524 * @sa xkb_state_mod_index_is_consumed()
2525 * @memberof xkb_state
2526 * @since 0.5.0: Works only with *real* modifiers
2527 * @since 1.8.0: Works also with *virtual* modifiers
2528 *
2529 * [real modifiers]: @ref real-modifier-def
2530 */
2531XKB_EXPORT xkb_mod_mask_t
2532xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t key,
2533 xkb_mod_mask_t mask);
2534
2535/**
2536 * Test whether a layout is active in a given keyboard state by name.
2537 *
2538 * @returns 1 if the layout is active, 0 if it is not. If no layout with
2539 * this name exists in the keymap, return -1.
2540 *
2541 * If multiple layouts in the keymap have this name, the one with the lowest
2542 * index is tested.
2543 *
2544 * @sa xkb_layout_index_t
2545 * @memberof xkb_state
2546 */
2547XKB_EXPORT int
2548xkb_state_layout_name_is_active(struct xkb_state *state, const char *name,
2549 enum xkb_state_component type);
2550
2551/**
2552 * Test whether a layout is active in a given keyboard state by index.
2553 *
2554 * @returns 1 if the layout is active, 0 if it is not. If the layout index
2555 * is not valid in the keymap, returns -1.
2556 *
2557 * @sa xkb_layout_index_t
2558 * @memberof xkb_state
2559 */
2560XKB_EXPORT int
2561xkb_state_layout_index_is_active(struct xkb_state *state,
2562 xkb_layout_index_t idx,
2563 enum xkb_state_component type);
2564
2565/**
2566 * Test whether a LED is active in a given keyboard state by name.
2567 *
2568 * @returns 1 if the LED is active, 0 if it not. If no LED with this name
2569 * exists in the keymap, returns -1.
2570 *
2571 * @sa xkb_led_index_t
2572 * @memberof xkb_state
2573 */
2574XKB_EXPORT int
2575xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
2576
2577/**
2578 * Test whether a LED is active in a given keyboard state by index.
2579 *
2580 * @returns 1 if the LED is active, 0 if it not. If the LED index is not
2581 * valid in the keymap, returns -1.
2582 *
2583 * @sa xkb_led_index_t
2584 * @memberof xkb_state
2585 */
2586XKB_EXPORT int
2587xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
2588
2589/** @} */
2590
2591/* Leave this include last, so it can pick up our types, etc. */
2592#include <xkbcommon/xkbcommon-compat.h>
2593
2594#ifdef __cplusplus
2595} /* extern "C" */
2596#endif
2597
2598#endif /* _XKBCOMMON_H_ */