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