2 Copyright 1985, 1987, 1990, 1998 The Open Group
3 Copyright 2008 Dan Nicholson
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:
12 The above copyright notice and this permission notice shall be included in
13 all copies or substantial portions of the Software.
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.
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.
28 /************************************************************
29 Copyright (c) 1993 by Silicon Graphics Computer Systems, Inc.
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.
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.
52 ********************************************************/
55 * Copyright © 2009 Daniel Stone
57 * Permission is hereby granted, free of charge, to any person obtaining a
58 * copy of this software and associated documentation files (the "Software"),
59 * to deal in the Software without restriction, including without limitation
60 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
61 * and/or sell copies of the Software, and to permit persons to whom the
62 * Software is furnished to do so, subject to the following conditions:
64 * The above copyright notice and this permission notice (including the next
65 * paragraph) shall be included in all copies or substantial portions of the
68 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
69 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
70 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
71 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
72 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
73 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
74 * DEALINGS IN THE SOFTWARE.
76 * Author: Daniel Stone <daniel@fooishbar.org>
85 #include <X11/Xfuncproto.h>
86 #include <X11/extensions/XKB.h>
88 typedef uint32_t xkb_keycode_t;
89 typedef uint32_t xkb_keysym_t;
90 typedef uint32_t xkb_mod_index_t;
91 typedef uint32_t xkb_mod_mask_t;
92 typedef uint32_t xkb_group_index_t;
93 typedef uint32_t xkb_led_index_t;
95 #define XKB_MOD_INVALID (0xffffffff)
96 #define XKB_GROUP_INVALID (0xffffffff)
97 #define XKB_KEYCODE_INVALID (0xffffffff)
98 #define XKB_LED_INVALID (0xffffffff)
100 #define XKB_KEYSYM_NO_SYMBOL 0
102 #define XKB_KEYCODE_MAX (0xffffffff - 1)
103 #define xkb_keycode_is_legal_ext(kc) (kc <= XKB_KEYCODE_MAX)
104 #define xkb_keycode_is_legal_x11(kc) (kc <= XKB_KEYCODE_MAX)
105 #define xkb_keymap_keycode_range_is_legal(xkb) \
106 (xkb->max_key_code > 0 && \
107 xkb->max_key_code > xkb->min_key_code && \
108 xkb_keycode_is_legal_ext(xkb->min_key_code) && \
109 xkb_keycode_is_legal_ext(xkb->max_key_code))
113 * Names to compile a keymap with, also known as RMLVO. These names together
114 * should be the primary identifier for a keymap.
116 struct xkb_rule_names {
125 * Legacy names for the components of an XKB keymap, also known as KcCGST.
126 * This is only used in deprecated entrypoints which might be removed or
127 * shuffled off to a support library.
129 struct xkb_component_names {
138 * Opaque context object; may only be created, accessed, manipulated and
139 * destroyed through the xkb_context_*() API.
144 * Opaque keymap object; may only be created, accessed, manipulated and
145 * destroyed through the xkb_state_*() API.
150 * Opaque state object; may only be created, accessed, manipulated and
151 * destroyed through the xkb_state_*() API.
158 * Canonicalises component names by prepending the relevant component from
159 * 'old' to the one in 'names' when the latter has a leading '+' or '|', and
160 * by replacing a '%' with the relevant component, e.g.:
163 * ------------------------------------------
166 * foo+%|baz bar foo+bar|baz
168 * If a component in names needs to be modified, the existing value will be
169 * free()d, and a new one allocated with malloc().
171 _X_EXPORT extern void
172 xkb_canonicalise_components(struct xkb_component_names *names,
173 const struct xkb_component_names *old);
176 * Converts a keysym to a string; will return unknown Unicode codepoints
177 * as "Ua1b2", and other unknown keysyms as "0xabcd1234".
179 _X_EXPORT extern void
180 xkb_keysym_to_string(xkb_keysym_t ks, char *buffer, size_t size);
183 * See xkb_keysym_to_string comments: this function will accept any string
184 * from that function.
186 _X_EXPORT extern xkb_keysym_t
187 xkb_string_to_keysym(const char *s);
189 _X_EXPORT unsigned int
190 xkb_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
191 xkb_keysym_t **syms_out);
194 * @defgroup ctx XKB contexts
195 * Every keymap compilation request must have an XKB context associated with
196 * it. The context keeps around state such as the include path.
202 * Returns a new XKB context, or NULL on failure. If successful, the caller
203 * holds a reference on the context, and must free it when finished with
204 * xkb_context_unref().
206 _X_EXPORT struct xkb_context *
207 xkb_context_new(void);
210 * Appends a new entry to the include path used for keymap compilation.
211 * Returns 1 on success, or 0 if the include path could not be added or is
215 xkb_context_include_path_append(struct xkb_context *context, const char *path);
218 * Appends the default include paths to the context's current include path.
219 * Returns 1 on success, or 0 if the primary include path could not be
223 xkb_context_include_path_append_default(struct xkb_context *context);
226 * Removes all entries from the context's include path, and inserts the
227 * default paths. Returns 1 on success, or 0 if the primary include path
228 * could not be added.
231 xkb_context_include_path_reset(struct xkb_context *context);
234 * Removes all entries from the context's include path.
237 xkb_context_include_path_clear(struct xkb_context *context);
240 * Returns the number of include paths currently active in the context.
242 _X_EXPORT unsigned int
243 xkb_context_num_include_paths(struct xkb_context *context);
246 * Returns the include path at the specified index within the context.
248 _X_EXPORT const char *
249 xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
252 * Takes a new reference on an XKB context.
255 xkb_context_ref(struct xkb_context *context);
258 * Releases a reference on an XKB context, and possibly frees it.
261 xkb_context_unref(struct xkb_context *context);
266 * @defgroup map Keymap management
267 * These utility functions allow you to create and deallocate XKB keymaps.
273 * The primary keymap entry point: creates a new XKB keymap from a set of
274 * RMLVO (Rules + Model + Layout + Variant + Option) names.
276 * You should almost certainly be using this and nothing else to create
279 _X_EXPORT extern struct xkb_desc *
280 xkb_map_new_from_names(struct xkb_context *context,
281 const struct xkb_rule_names *names);
284 * Deprecated entrypoint for legacy users who need to be able to compile
285 * XKB keymaps by KcCGST (Keycodes + Compat + Geometry + Symbols + Types)
288 * You should not use this unless you are the X server. This entrypoint
289 * may well disappear in future releases. Please, please, don't use it.
291 * Geometry will be ignored since xkbcommon does not support it in any way.
293 _X_EXPORT extern struct xkb_desc *
294 xkb_map_new_from_kccgst(struct xkb_context *context,
295 const struct xkb_component_names *kccgst);
297 enum xkb_keymap_format {
298 /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
299 XKB_KEYMAP_FORMAT_TEXT_V1 = 1,
303 * Creates an XKB keymap from a full text XKB keymap passed into the
306 _X_EXPORT extern struct xkb_desc *
307 xkb_map_new_from_fd(struct xkb_context *context,
308 int fd, enum xkb_keymap_format format);
311 * Creates an XKB keymap from a full text XKB keymap serialised into one
314 _X_EXPORT extern struct xkb_desc *
315 xkb_map_new_from_string(struct xkb_context *context,
317 enum xkb_keymap_format format);
320 * Takes a new reference on a keymap.
322 _X_EXPORT extern void
323 xkb_map_ref(struct xkb_desc *xkb);
326 * Releases a reference on a keymap.
328 _X_EXPORT extern void
329 xkb_map_unref(struct xkb_desc *xkb);
334 * @defgroup components XKB state components
335 * Allows enumeration of state components such as modifiers and groups within
336 * the current keymap.
342 * Returns the number of modifiers active in the keymap.
344 _X_EXPORT xkb_mod_index_t
345 xkb_map_num_mods(struct xkb_desc *xkb);
348 * Returns the name of the modifier specified by 'idx', or NULL if invalid.
350 _X_EXPORT const char *
351 xkb_map_mod_get_name(struct xkb_desc *xkb, xkb_mod_index_t idx);
354 * Returns the index of the modifier specified by 'name', or XKB_MOD_INVALID.
356 _X_EXPORT xkb_mod_index_t
357 xkb_map_mod_get_index(struct xkb_desc *xkb, const char *name);
360 * Returns the number of groups active in the keymap.
362 _X_EXPORT xkb_group_index_t
363 xkb_map_num_groups(struct xkb_desc *xkb);
366 * Returns the name of the group specified by 'idx', or NULL if invalid.
368 _X_EXPORT const char *
369 xkb_map_group_get_name(struct xkb_desc *xkb, xkb_group_index_t idx);
372 * Returns the index of the group specified by 'name', or XKB_GROUP_INVALID.
374 _X_EXPORT xkb_group_index_t
375 xkb_map_group_get_index(struct xkb_desc *xkb, const char *name);
378 * Returns the number of groups active for the specified key.
380 _X_EXPORT xkb_group_index_t
381 xkb_key_num_groups(struct xkb_desc *xkb, xkb_keycode_t key);
384 * Returns the number of LEDs in the given map.
386 _X_EXPORT xkb_led_index_t
387 xkb_map_num_leds(struct xkb_desc *xkb);
390 * Returns the name of the LED specified by 'idx', or NULL if invalid.
392 _X_EXPORT const char *
393 xkb_map_led_get_name(struct xkb_desc *xkb, xkb_led_index_t idx);
396 * Returns the index of the LED specified by 'name', or XKB_LED_INVALID.
398 _X_EXPORT xkb_led_index_t
399 xkb_map_led_get_index(struct xkb_desc *xkb, const char *name);
404 * @defgroup state XKB state objects
405 * Creation, destruction and manipulation of keyboard state objects,
406 * representing modifier and group state.
412 * Returns a new XKB state object for use with the given keymap, or NULL on
415 _X_EXPORT struct xkb_state *
416 xkb_state_new(struct xkb_desc *xkb);
419 * Adds a reference to a state object, so it will not be freed until unref.
422 xkb_state_ref(struct xkb_state *state);
425 * Unrefs and potentially deallocates a state object; the caller must not
426 * use the state object after calling this.
429 xkb_state_unref(struct xkb_state *state);
431 enum xkb_key_direction {
437 * Updates a state object to reflect the given key being pressed or released.
440 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
441 enum xkb_key_direction direction);
444 * Modifier and group types for state objects. This enum is bitmaskable,
445 * e.g. (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED) is valid to exclude
448 enum xkb_state_component {
449 /** A key holding this modifier or group is currently physically
450 * depressed; also known as 'base'. */
451 XKB_STATE_DEPRESSED = (1 << 0),
452 /** Modifier or group is latched, i.e. will be unset after the next
453 * non-modifier key press. */
454 XKB_STATE_LATCHED = (1 << 1),
455 /** Modifier or group is locked, i.e. will be unset after the key
456 * provoking the lock has been pressed again. */
457 XKB_STATE_LOCKED = (1 << 2),
458 /** Combinatination of depressed, latched, and locked. */
459 XKB_STATE_EFFECTIVE =
460 (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED | XKB_STATE_LOCKED),
464 * Updates a state object from a set of explicit masks. This entrypoint is
465 * really only for window systems and the like, where a master process
466 * holds an xkb_state, then serialises it over a wire protocol, and clients
467 * then use the serialisation to feed in to their own xkb_state.
469 * All parameters must always be passed, or the resulting state may be
472 * The serialisation is lossy and will not survive round trips; it must only
473 * be used to feed slave state objects, and must not be used to update the
476 * Please do not use this unless you fit the description above.
479 xkb_state_update_mask(struct xkb_state *state,
480 xkb_mod_mask_t base_mods,
481 xkb_mod_mask_t latched_mods,
482 xkb_mod_mask_t locked_mods,
483 xkb_group_index_t base_group,
484 xkb_group_index_t latched_group,
485 xkb_group_index_t locked_group);
488 * The counterpart to xkb_state_update_mask, to be used on the server side
489 * of serialisation. Returns a xkb_mod_mask_t representing the given
490 * component(s) of the state.
492 * This function should not be used in regular clients; please use the
493 * xkb_state_mod_*_is_active or xkb_state_foreach_active_mod API instead.
495 * Can return NULL on failure.
497 _X_EXPORT xkb_mod_mask_t
498 xkb_state_serialise_mods(struct xkb_state *state,
499 enum xkb_state_component component);
502 * The group equivalent of xkb_state_serialise_mods: please see its
505 _X_EXPORT xkb_group_index_t
506 xkb_state_serialise_group(struct xkb_state *state,
507 enum xkb_state_component component);
510 * Returns 1 if the modifier specified by 'name' is active in the manner
511 * specified by 'type', 0 if it is unset, or -1 if the modifier does not
512 * exist in the current map.
515 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
516 enum xkb_state_component type);
519 * Returns 1 if the modifier specified by 'idx' is active in the manner
520 * specified by 'type', 0 if it is unset, or -1 if the modifier does not
521 * exist in the current map.
524 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
525 enum xkb_state_component type);
528 * Returns 1 if the group specified by 'name' is active in the manner
529 * specified by 'type', 0 if it is unset, or -1 if the group does not
530 * exist in the current map.
533 xkb_state_group_name_is_active(struct xkb_state *state, const char *name,
534 enum xkb_state_component type);
537 * Returns 1 if the group specified by 'idx' is active in the manner
538 * specified by 'type', 0 if it is unset, or -1 if the group does not
539 * exist in the current map.
542 xkb_state_group_index_is_active(struct xkb_state *state, xkb_group_index_t idx,
543 enum xkb_state_component type);
546 * Returns 1 if the LED specified by 'name' is active, 0 if it is unset, or
547 * -1 if the LED does not exist in the current map.
550 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
553 * Returns 1 if the LED specified by 'idx' is active, 0 if it is unset, or
554 * -1 if the LED does not exist in the current map.
557 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
563 #endif /* _XKBCOMMON_H_ */