include/xkbcommon/xkbcommon.h

   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 Daniel Stone
  56  *
  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:
  63  *
  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
  66  * Software.
  67  *
  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.
  75  *
  76  * Author: Daniel Stone <daniel@fooishbar.org>
  77  */
  78
  79
  80 #ifndef _XKBCOMMON_H_
  81 #define _XKBCOMMON_H_
  82
  83 #include <stdint.h>
  84 #include <stdio.h>
  85 #include <X11/Xfuncproto.h>
  86 #include <X11/extensions/XKB.h>
  87
  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;
  94
  95 #define XKB_MOD_INVALID                 (0xffffffff)
  96 #define XKB_GROUP_INVALID               (0xffffffff)
  97 #define XKB_KEYCODE_INVALID             (0xffffffff)
  98 #define XKB_LED_INVALID                 (0xffffffff)
  99
 100 #define XKB_KEYCODE_MAX                 (0xffffffff - 1)
 101 #define xkb_keycode_is_legal_ext(kc)    (kc <= XKB_KEYCODE_MAX)
 102 #define xkb_keycode_is_legal_x11(kc)    (kc <= XKB_KEYCODE_MAX)
 103 #define xkb_keymap_keycode_range_is_legal(xkb) \
 104     (xkb->max_key_code > 0 && \
 105      xkb->max_key_code > xkb->min_key_code && \
 106      xkb_keycode_is_legal_ext(xkb->min_key_code) && \
 107      xkb_keycode_is_legal_ext(xkb->max_key_code))
 108
 109
 110 /**
 111  * Names to compile a keymap with, also known as RMLVO.  These names together
 112  * should be the primary identifier for a keymap.
 113  */
 114 struct xkb_rule_names {
 115     const char *rules;
 116     const char *model;
 117     const char *layout;
 118     const char *variant;
 119     const char *options;
 120 };
 121
 122 /**
 123  * Legacy names for the components of an XKB keymap, also known as KcCGST.
 124  * This is only used in deprecated entrypoints which might be removed or
 125  * shuffled off to a support library.
 126  */
 127 struct xkb_component_names {
 128     char *keymap;
 129     char *keycodes;
 130     char *types;
 131     char *compat;
 132     char *symbols;
 133 };
 134
 135 /**
 136  * Opaque state object, may only be created, accessed, manipulated and
 137  * destroyed through the xkb_state_*() API.
 138  */
 139 struct xkb_state;
 140
 141 _XFUNCPROTOBEGIN
 142
 143 /*
 144  * Canonicalises component names by prepending the relevant component from
 145  * 'old' to the one in 'names' when the latter has a leading '+' or '|', and
 146  * by replacing a '%' with the relevant component, e.g.:
 147  *
 148  * names        old           output
 149  * ------------------------------------------
 150  * +bar         foo           foo+bar
 151  * |quux        baz           baz|quux
 152  * foo+%|baz    bar           foo+bar|baz
 153  *
 154  * If a component in names needs to be modified, the existing value will be
 155  * free()d, and a new one allocated with malloc().
 156  */
 157 _X_EXPORT extern void
 158 xkb_canonicalise_components(struct xkb_component_names *names,
 159                             const struct xkb_component_names *old);
 160
 161 /*
 162  * Converts a keysym to a string; will return unknown Unicode codepoints
 163  * as "Ua1b2", and other unknown keysyms as "0xabcd1234".
 164  */
 165 _X_EXPORT extern void
 166 xkb_keysym_to_string(xkb_keysym_t ks, char *buffer, size_t size);
 167
 168 /*
 169  * See xkb_keysym_to_string comments: this function will accept any string
 170  * from that function.
 171  */
 172 _X_EXPORT extern xkb_keysym_t
 173 xkb_string_to_keysym(const char *s);
 174
 175 _X_EXPORT unsigned int
 176 xkb_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
 177                  xkb_keysym_t **syms_out);
 178
 179 /**
 180  * @defgroup map Keymap management
 181  * These utility functions allow you to create and deallocate XKB keymaps.
 182  *
 183  * @{
 184  */
 185
 186 /**
 187  * The primary keymap entry point: creates a new XKB keymap from a set of
 188  * RMLVO (Rules + Model + Layout + Variant + Option) names.
 189  *
 190  * You should almost certainly be using this and nothing else to create
 191  * keymaps.
 192  */
 193 _X_EXPORT extern struct xkb_desc *
 194 xkb_map_new_from_names(const struct xkb_rule_names *names);
 195
 196 /**
 197  * Deprecated entrypoint for legacy users who need to be able to compile
 198  * XKB keymaps by KcCGST (Keycodes + Compat + Geometry + Symbols + Types)
 199  * names.
 200  *
 201  * You should not use this unless you are the X server.  This entrypoint
 202  * may well disappear in future releases.  Please, please, don't use it.
 203  *
 204  * Geometry will be ignored since xkbcommon does not support it in any way.
 205  */
 206 _X_EXPORT extern struct xkb_desc *
 207 xkb_map_new_from_kccgst(const struct xkb_component_names *kccgst);
 208
 209 enum xkb_keymap_format {
 210     /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
 211     XKB_KEYMAP_FORMAT_TEXT_V1 = 1,
 212 };
 213
 214 /**
 215  * Creates an XKB keymap from a full text XKB keymap passed into the
 216  * file descriptor.
 217  */
 218 _X_EXPORT extern struct xkb_desc *
 219 xkb_map_new_from_fd(int fd, enum xkb_keymap_format format);
 220
 221 /**
 222  * Creates an XKB keymap from a full text XKB keymap serialised into one
 223  * enormous string.
 224  */
 225 _X_EXPORT extern struct xkb_desc *
 226 xkb_map_new_from_string(const char *string, enum xkb_keymap_format format);
 227
 228 /**
 229  * Takes a new reference on a keymap.
 230  */
 231 _X_EXPORT extern void
 232 xkb_map_ref(struct xkb_desc *xkb);
 233
 234 /**
 235  * Releases a reference on a keymap.
 236  */
 237 _X_EXPORT extern void
 238 xkb_map_unref(struct xkb_desc *xkb);
 239
 240 /** @} */
 241
 242 /**
 243  * @defgroup components XKB state components
 244  * Allows enumeration of state components such as modifiers and groups within
 245  * the current keymap.
 246  *
 247  * @{
 248  */
 249
 250 /**
 251  * Returns the number of modifiers active in the keymap.
 252  */
 253 _X_EXPORT xkb_mod_index_t
 254 xkb_map_num_mods(struct xkb_desc *xkb);
 255
 256 /**
 257  * Returns the name of the modifier specified by 'idx', or NULL if invalid.
 258  */
 259 _X_EXPORT const char *
 260 xkb_map_mod_get_name(struct xkb_desc *xkb, xkb_mod_index_t idx);
 261
 262 /**
 263  * Returns the index of the modifier specified by 'name', or XKB_MOD_INVALID.
 264  */
 265 _X_EXPORT xkb_mod_index_t
 266 xkb_map_mod_get_index(struct xkb_desc *xkb, const char *name);
 267
 268 /**
 269  * Returns the number of groups active in the keymap.
 270  */
 271 _X_EXPORT xkb_group_index_t
 272 xkb_map_num_groups(struct xkb_desc *xkb);
 273
 274 /**
 275  * Returns the name of the group specified by 'idx', or NULL if invalid.
 276  */
 277 _X_EXPORT const char *
 278 xkb_map_group_get_name(struct xkb_desc *xkb, xkb_group_index_t idx);
 279
 280 /**
 281  * Returns the index of the group specified by 'name', or XKB_GROUP_INVALID.
 282  */
 283 _X_EXPORT xkb_group_index_t
 284 xkb_map_group_get_index(struct xkb_desc *xkb, const char *name);
 285
 286 /**
 287  * Returns the number of groups active for the specified key.
 288  */
 289 _X_EXPORT xkb_group_index_t
 290 xkb_key_num_groups(struct xkb_desc *xkb, xkb_keycode_t key);
 291
 292 /**
 293  * Returns the number of LEDs in the given map.
 294  */
 295 _X_EXPORT xkb_led_index_t
 296 xkb_map_num_leds(struct xkb_desc *xkb);
 297
 298 /**
 299  * Returns the name of the LED specified by 'idx', or NULL if invalid.
 300  */
 301 _X_EXPORT const char *
 302 xkb_map_led_get_name(struct xkb_desc *xkb, xkb_led_index_t idx);
 303
 304 /**
 305  * Returns the index of the LED specified by 'name', or XKB_LED_INVALID.
 306  */
 307 _X_EXPORT xkb_led_index_t
 308 xkb_map_led_get_index(struct xkb_desc *xkb, const char *name);
 309
 310 /** @} */
 311
 312 /**
 313  * @defgroup state XKB state objects
 314  * Creation, destruction and manipulation of keyboard state objects,
 315  * representing modifier and group state.
 316  *
 317  * @{
 318  */
 319
 320 /**
 321  * Returns a new XKB state object for use with the given keymap, or NULL on
 322  * failure.
 323  */
 324 _X_EXPORT struct xkb_state *
 325 xkb_state_new(struct xkb_desc *xkb);
 326
 327 /**
 328  * Adds a reference to a state object, so it will not be freed until unref.
 329  */
 330 _X_EXPORT void
 331 xkb_state_ref(struct xkb_state *state);
 332
 333 /**
 334  * Unrefs and potentially deallocates a state object; the caller must not
 335  * use the state object after calling this.
 336  */
 337 _X_EXPORT void
 338 xkb_state_unref(struct xkb_state *state);
 339
 340 enum xkb_key_direction {
 341     XKB_KEY_UP,
 342     XKB_KEY_DOWN,
 343 };
 344
 345 /**
 346  * Updates a state object to reflect the given key being pressed or released.
 347  */
 348 _X_EXPORT void
 349 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
 350                      enum xkb_key_direction direction);
 351
 352 /**
 353  * Modifier and group types for state objects.  This enum is bitmaskable,
 354  * e.g. (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED) is valid to exclude
 355  * locked modifiers.
 356  */
 357 enum xkb_state_component {
 358     /** A key holding this modifier or group is currently physically
 359      *  depressed; also known as 'base'. */
 360     XKB_STATE_DEPRESSED = (1 << 0),
 361     /** Modifier or group is latched, i.e. will be unset after the next
 362      *  non-modifier key press. */
 363     XKB_STATE_LATCHED = (1 << 1),
 364     /** Modifier or group is locked, i.e. will be unset after the key
 365      *  provoking the lock has been pressed again. */
 366     XKB_STATE_LOCKED = (1 << 2),
 367     /** Combinatination of depressed, latched, and locked. */
 368     XKB_STATE_EFFECTIVE =
 369         (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED | XKB_STATE_LOCKED),
 370 };
 371
 372 /**
 373  * Updates a state object from a set of explicit masks.  This entrypoint is
 374  * really only for window systems and the like, where a master process
 375  * holds an xkb_state, then serialises it over a wire protocol, and clients
 376  * then use the serialisation to feed in to their own xkb_state.
 377  *
 378  * All parameters must always be passed, or the resulting state may be
 379  * incoherent.
 380  *
 381  * The serialisation is lossy and will not survive round trips; it must only
 382  * be used to feed slave state objects, and must not be used to update the
 383  * master state.
 384  *
 385  * Please do not use this unless you fit the description above.
 386  */
 387 _X_EXPORT void
 388 xkb_state_update_mask(struct xkb_state *state,
 389                       xkb_mod_mask_t base_mods,
 390                       xkb_mod_mask_t latched_mods,
 391                       xkb_mod_mask_t locked_mods,
 392                       xkb_group_index_t base_group,
 393                       xkb_group_index_t latched_group,
 394                       xkb_group_index_t locked_group);
 395
 396 /**
 397  * The counterpart to xkb_state_update_mask, to be used on the server side
 398  * of serialisation.  Returns a xkb_mod_mask_t representing the given
 399  * component(s) of the state.
 400  *
 401  * This function should not be used in regular clients; please use the
 402  * xkb_state_mod_*_is_active or xkb_state_foreach_active_mod API instead.
 403  *
 404  * Can return NULL on failure.
 405  */
 406 _X_EXPORT xkb_mod_mask_t
 407 xkb_state_serialise_mods(struct xkb_state *state,
 408                          enum xkb_state_component component);
 409
 410 /**
 411  * The group equivalent of xkb_state_serialise_mods: please see its
 412  * documentation.
 413  */
 414 _X_EXPORT xkb_group_index_t
 415 xkb_state_serialise_group(struct xkb_state *state,
 416                           enum xkb_state_component component);
 417
 418 /**
 419  * Returns 1 if the modifier specified by 'name' is active in the manner
 420  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 421  * exist in the current map.
 422  */
 423 _X_EXPORT int
 424 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
 425                              enum xkb_state_component type);
 426
 427 /**
 428  * Returns 1 if the modifier specified by 'idx' is active in the manner
 429  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 430  * exist in the current map.
 431  */
 432 _X_EXPORT int
 433 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
 434                               enum xkb_state_component type);
 435
 436 /**
 437  * Returns 1 if the group specified by 'name' is active in the manner
 438  * specified by 'type', 0 if it is unset, or -1 if the group does not
 439  * exist in the current map.
 440  */
 441 _X_EXPORT int
 442 xkb_state_group_name_is_active(struct xkb_state *state, const char *name,
 443                                enum xkb_state_component type);
 444
 445 /**
 446  * Returns 1 if the group specified by 'idx' is active in the manner
 447  * specified by 'type', 0 if it is unset, or -1 if the group does not
 448  * exist in the current map.
 449  */
 450 _X_EXPORT int
 451 xkb_state_group_index_is_active(struct xkb_state *state, xkb_group_index_t idx,
 452                                 enum xkb_state_component type);
 453
 454 /**
 455  * Returns 1 if the LED specified by 'name' is active, 0 if it is unset, or
 456  * -1 if the LED does not exist in the current map.
 457  */
 458 _X_EXPORT int
 459 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
 460
 461 /**
 462  * Returns 1 if the LED specified by 'idx' is active, 0 if it is unset, or
 463  * -1 if the LED does not exist in the current map.
 464  */
 465 _X_EXPORT int
 466 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
 467
 468 /** @} */
 469
 470 _XFUNCPROTOEND
 471
 472 #endif /* _XKBCOMMON_H_ */