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