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