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