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 <stddef.h>
  84 #include <stdint.h>
  85
  86 typedef uint32_t xkb_keycode_t;
  87 typedef uint32_t xkb_keysym_t;
  88 typedef uint32_t xkb_mod_index_t;
  89 typedef uint32_t xkb_mod_mask_t;
  90 typedef uint32_t xkb_group_index_t;
  91 typedef uint32_t xkb_led_index_t;
  92
  93 #define XKB_MOD_INVALID                 (0xffffffff)
  94 #define XKB_GROUP_INVALID               (0xffffffff)
  95 #define XKB_KEYCODE_INVALID             (0xffffffff)
  96 #define XKB_LED_INVALID                 (0xffffffff)
  97
  98 #define XKB_KEYSYM_NO_SYMBOL            0
  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  * Names to compile a keymap with, also known as RMLVO.  These names together
 111  * should be the primary identifier for a keymap.
 112  */
 113 struct xkb_rule_names {
 114     const char *rules;
 115     const char *model;
 116     const char *layout;
 117     const char *variant;
 118     const char *options;
 119 };
 120
 121 /**
 122  * Legacy names for the components of an XKB keymap, also known as KcCGST.
 123  * This is only used in deprecated entrypoints which might be removed or
 124  * shuffled off to a support library.
 125  */
 126 struct xkb_component_names {
 127     char *keymap;
 128     char *keycodes;
 129     char *types;
 130     char *compat;
 131     char *symbols;
 132 };
 133
 134 /**
 135  * Opaque context object; may only be created, accessed, manipulated and
 136  * destroyed through the xkb_context_*() API.
 137  */
 138 struct xkb_context;
 139
 140 /**
 141  * Opaque keymap object; may only be created, accessed, manipulated and
 142  * destroyed through the xkb_state_*() API.
 143  */
 144 struct xkb_keymap;
 145
 146 /**
 147  * Opaque state object; may only be created, accessed, manipulated and
 148  * destroyed through the xkb_state_*() API.
 149  */
 150 struct xkb_state;
 151
 152 #ifdef __cplusplus
 153 extern "C" {
 154 #endif
 155
 156 /*
 157  * Canonicalises component names by prepending the relevant component from
 158  * 'old' to the one in 'names' when the latter has a leading '+' or '|', and
 159  * by replacing a '%' with the relevant component, e.g.:
 160  *
 161  * names        old           output
 162  * ------------------------------------------
 163  * +bar         foo           foo+bar
 164  * |quux        baz           baz|quux
 165  * foo+%|baz    bar           foo+bar|baz
 166  *
 167  * If a component in names needs to be modified, the existing value will be
 168  * free()d, and a new one allocated with malloc().
 169  */
 170 void
 171 xkb_canonicalise_components(struct xkb_component_names *names,
 172                             const struct xkb_component_names *old);
 173
 174 /*
 175  * Returns the name for a keysym as a string; will return unknown Unicode
 176  * codepoints as "Ua1b2", and other unknown keysyms as "0xabcd1234".
 177  */
 178 void
 179 xkb_keysym_get_name(xkb_keysym_t ks, char *buffer, size_t size);
 180
 181 /*
 182  * See xkb_keysym_to_string comments: this function will accept any string
 183  * from that function.
 184  */
 185 xkb_keysym_t
 186 xkb_keysym_from_name(const char *s);
 187
 188 /**
 189  * @defgroup ctx XKB contexts
 190  * Every keymap compilation request must have an XKB context associated with
 191  * it.  The context keeps around state such as the include path.
 192  *
 193  * @{
 194  */
 195
 196 enum xkb_context_flags {
 197     /** Create this context with an empty include path. */
 198     XKB_CONTEXT_NO_DEFAULT_INCLUDES = 1,
 199 };
 200
 201 /**
 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().
 205  */
 206 struct xkb_context *
 207 xkb_context_new(enum xkb_context_flags flags);
 208
 209 /**
 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
 212  * inaccessible.
 213  */
 214 int
 215 xkb_context_include_path_append(struct xkb_context *context, const char *path);
 216
 217 /**
 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
 220  * added.
 221  */
 222 int
 223 xkb_context_include_path_append_default(struct xkb_context *context);
 224
 225 /**
 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.
 229  */
 230 int
 231 xkb_context_include_path_reset_defaults(struct xkb_context *context);
 232
 233 /**
 234  * Removes all entries from the context's include path.
 235  */
 236 void
 237 xkb_context_include_path_clear(struct xkb_context *context);
 238
 239 /**
 240  * Returns the number of include paths currently active in the context.
 241  */
 242 unsigned int
 243 xkb_context_num_include_paths(struct xkb_context *context);
 244
 245 /**
 246  * Returns the include path at the specified index within the context.
 247  */
 248 const char *
 249 xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
 250
 251 /**
 252  * Takes a new reference on an XKB context.
 253  */
 254 struct xkb_context *
 255 xkb_context_ref(struct xkb_context *context);
 256
 257 /**
 258  * Releases a reference on an XKB context, and possibly frees it.
 259  */
 260 void
 261 xkb_context_unref(struct xkb_context *context);
 262
 263 /** @} */
 264
 265 /**
 266  * @defgroup map Keymap management
 267  * These utility functions allow you to create and deallocate XKB keymaps.
 268  *
 269  * @{
 270  */
 271
 272 enum xkb_map_compile_flags {
 273     /** Apparently you can't have empty enums.  What a drag. */
 274     XKB_MAP_COMPILE_PLACEHOLDER = 0,
 275 };
 276
 277 /**
 278  * The primary keymap entry point: creates a new XKB keymap from a set of
 279  * RMLVO (Rules + Model + Layout + Variant + Option) names.
 280  *
 281  * You should almost certainly be using this and nothing else to create
 282  * keymaps.
 283  */
 284 struct xkb_keymap *
 285 xkb_map_new_from_names(struct xkb_context *context,
 286                        const struct xkb_rule_names *names,
 287                        enum xkb_map_compile_flags flags);
 288
 289 /**
 290  * Deprecated entrypoint for legacy users who need to be able to compile
 291  * XKB keymaps by KcCGST (Keycodes + Compat + Geometry + Symbols + Types)
 292  * names.
 293  *
 294  * You should not use this unless you are the X server.  This entrypoint
 295  * may well disappear in future releases.  Please, please, don't use it.
 296  *
 297  * Geometry will be ignored since xkbcommon does not support it in any way.
 298  */
 299 struct xkb_keymap *
 300 xkb_map_new_from_kccgst(struct xkb_context *context,
 301                         const struct xkb_component_names *kccgst,
 302                         enum xkb_map_compile_flags flags);
 303
 304 enum xkb_keymap_format {
 305     /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
 306     XKB_KEYMAP_FORMAT_TEXT_V1 = 1,
 307 };
 308
 309 /**
 310  * Creates an XKB keymap from a full text XKB keymap passed into the
 311  * file descriptor.
 312  */
 313 struct xkb_keymap *
 314 xkb_map_new_from_fd(struct xkb_context *context,
 315                     int fd, enum xkb_keymap_format format,
 316                     enum xkb_map_compile_flags flags);
 317
 318 /**
 319  * Creates an XKB keymap from a full text XKB keymap serialised into one
 320  * enormous string.
 321  */
 322 struct xkb_keymap *
 323 xkb_map_new_from_string(struct xkb_context *context,
 324                         const char *string,
 325                         enum xkb_keymap_format format,
 326                         enum xkb_map_compile_flags flags);
 327
 328 /**
 329  * Takes a new reference on a keymap.
 330  */
 331 struct xkb_keymap *
 332 xkb_map_ref(struct xkb_keymap *xkb);
 333
 334 /**
 335  * Releases a reference on a keymap.
 336  */
 337 void
 338 xkb_map_unref(struct xkb_keymap *xkb);
 339
 340 /** @} */
 341
 342 /**
 343  * @defgroup components XKB state components
 344  * Allows enumeration of state components such as modifiers and groups within
 345  * the current keymap.
 346  *
 347  * @{
 348  */
 349
 350 /**
 351  * Returns the number of modifiers active in the keymap.
 352  */
 353 xkb_mod_index_t
 354 xkb_map_num_mods(struct xkb_keymap *xkb);
 355
 356 /**
 357  * Returns the name of the modifier specified by 'idx', or NULL if invalid.
 358  */
 359 const char *
 360 xkb_map_mod_get_name(struct xkb_keymap *xkb, xkb_mod_index_t idx);
 361
 362 /**
 363  * Returns the index of the modifier specified by 'name', or XKB_MOD_INVALID.
 364  */
 365 xkb_mod_index_t
 366 xkb_map_mod_get_index(struct xkb_keymap *xkb, const char *name);
 367
 368 /**
 369  * Returns the number of groups active in the keymap.
 370  */
 371 xkb_group_index_t
 372 xkb_map_num_groups(struct xkb_keymap *xkb);
 373
 374 /**
 375  * Returns the name of the group specified by 'idx', or NULL if invalid.
 376  */
 377 const char *
 378 xkb_map_group_get_name(struct xkb_keymap *xkb, xkb_group_index_t idx);
 379
 380 /**
 381  * Returns the index of the group specified by 'name', or XKB_GROUP_INVALID.
 382  */
 383 xkb_group_index_t
 384 xkb_map_group_get_index(struct xkb_keymap *xkb, const char *name);
 385
 386 /**
 387  * Returns the number of groups active for the specified key.
 388  */
 389 xkb_group_index_t
 390 xkb_key_num_groups(struct xkb_keymap *xkb, xkb_keycode_t key);
 391
 392 /**
 393  * Returns the number of LEDs in the given map.
 394  */
 395 xkb_led_index_t
 396 xkb_map_num_leds(struct xkb_keymap *xkb);
 397
 398 /**
 399  * Returns the name of the LED specified by 'idx', or NULL if invalid.
 400  */
 401 const char *
 402 xkb_map_led_get_name(struct xkb_keymap *xkb, xkb_led_index_t idx);
 403
 404 /**
 405  * Returns the index of the LED specified by 'name', or XKB_LED_INVALID.
 406  */
 407 xkb_led_index_t
 408 xkb_map_led_get_index(struct xkb_keymap *xkb, const char *name);
 409
 410 /** @} */
 411
 412 /**
 413  * @defgroup state XKB state objects
 414  * Creation, destruction and manipulation of keyboard state objects,
 415  * representing modifier and group state.
 416  *
 417  * @{
 418  */
 419
 420 /**
 421  * Returns a new XKB state object for use with the given keymap, or NULL on
 422  * failure.
 423  */
 424 struct xkb_state *
 425 xkb_state_new(struct xkb_keymap *xkb);
 426
 427 /**
 428  * Takes a new reference on a state object.
 429  */
 430 struct xkb_state *
 431 xkb_state_ref(struct xkb_state *state);
 432
 433 /**
 434  * Unrefs and potentially deallocates a state object; the caller must not
 435  * use the state object after calling this.
 436  */
 437 void
 438 xkb_state_unref(struct xkb_state *state);
 439
 440 /**
 441  * Get the keymap from which the state object was created.
 442  */
 443 struct xkb_keymap *
 444 xkb_state_get_map(struct xkb_state *state);
 445
 446 enum xkb_key_direction {
 447     XKB_KEY_UP,
 448     XKB_KEY_DOWN,
 449 };
 450
 451 /**
 452  * Updates a state object to reflect the given key being pressed or released.
 453  */
 454 void
 455 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
 456                      enum xkb_key_direction direction);
 457
 458 /**
 459  * Gives the symbols obtained from pressing a particular key with the given
 460  * state.  *syms_out will be set to point to an array of keysyms, with the
 461  * return value being the number of symbols in *syms_out.  If the return
 462  * value is 0, *syms_out will be set to NULL, as there are no symbols produced
 463  * by this event.
 464  *
 465  * This should be called before xkb_state_update_key.
 466  */
 467 unsigned int
 468 xkb_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
 469                  const xkb_keysym_t **syms_out);
 470
 471 /**
 472  * Modifier and group types for state objects.  This enum is bitmaskable,
 473  * e.g. (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED) is valid to exclude
 474  * locked modifiers.
 475  */
 476 enum xkb_state_component {
 477     /** A key holding this modifier or group is currently physically
 478      *  depressed; also known as 'base'. */
 479     XKB_STATE_DEPRESSED = (1 << 0),
 480     /** Modifier or group is latched, i.e. will be unset after the next
 481      *  non-modifier key press. */
 482     XKB_STATE_LATCHED = (1 << 1),
 483     /** Modifier or group is locked, i.e. will be unset after the key
 484      *  provoking the lock has been pressed again. */
 485     XKB_STATE_LOCKED = (1 << 2),
 486     /** Combinatination of depressed, latched, and locked. */
 487     XKB_STATE_EFFECTIVE =
 488         (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED | XKB_STATE_LOCKED),
 489 };
 490
 491 /**
 492  * Match flags for xkb_state_mod_indices_are_active and
 493  * xkb_state_mod_names_are_active, specifying how the conditions for a
 494  * successful match.  XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with
 495  * the other modes.
 496  */
 497 enum xkb_state_match {
 498     /** Returns true if any of the modifiers are active. */
 499     XKB_STATE_MATCH_ANY = (1 << 0),
 500     /** Returns true if all of the modifiers are active. */
 501     XKB_STATE_MATCH_ALL = (1 << 1),
 502     /** Makes matching non-exclusive, i.e. will not return false if a
 503      *  modifier not specified in the arguments is active. */
 504     XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16),
 505 };
 506
 507 /**
 508  * Updates a state object from a set of explicit masks.  This entrypoint is
 509  * really only for window systems and the like, where a master process
 510  * holds an xkb_state, then serialises it over a wire protocol, and clients
 511  * then use the serialisation to feed in to their own xkb_state.
 512  *
 513  * All parameters must always be passed, or the resulting state may be
 514  * incoherent.
 515  *
 516  * The serialisation is lossy and will not survive round trips; it must only
 517  * be used to feed slave state objects, and must not be used to update the
 518  * master state.
 519  *
 520  * Please do not use this unless you fit the description above.
 521  */
 522 void
 523 xkb_state_update_mask(struct xkb_state *state,
 524                       xkb_mod_mask_t base_mods,
 525                       xkb_mod_mask_t latched_mods,
 526                       xkb_mod_mask_t locked_mods,
 527                       xkb_group_index_t base_group,
 528                       xkb_group_index_t latched_group,
 529                       xkb_group_index_t locked_group);
 530
 531 /**
 532  * The counterpart to xkb_state_update_mask, to be used on the server side
 533  * of serialisation.  Returns a xkb_mod_mask_t representing the given
 534  * component(s) of the state.
 535  *
 536  * This function should not be used in regular clients; please use the
 537  * xkb_state_mod_*_is_active or xkb_state_foreach_active_mod API instead.
 538  *
 539  * Can return NULL on failure.
 540  */
 541 xkb_mod_mask_t
 542 xkb_state_serialise_mods(struct xkb_state *state,
 543                          enum xkb_state_component component);
 544
 545 /**
 546  * The group equivalent of xkb_state_serialise_mods: please see its
 547  * documentation.
 548  */
 549 xkb_group_index_t
 550 xkb_state_serialise_group(struct xkb_state *state,
 551                           enum xkb_state_component component);
 552
 553 /**
 554  * Returns 1 if the modifier specified by 'name' is active in the manner
 555  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 556  * exist in the map.
 557  */
 558 int
 559 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
 560                              enum xkb_state_component type);
 561
 562 /**
 563  * Returns 1 if the modifiers specified by the varargs (treated as
 564  * NULL-terminated pointers to strings) are active in the manner
 565  * specified by 'match', 0 otherwise, or -1 if any of the modifiers
 566  * do not exist in the map.
 567  */
 568 int
 569 xkb_state_mod_names_are_active(struct xkb_state *state,
 570                                enum xkb_state_component type,
 571                                enum xkb_state_match match,
 572                                ...);
 573
 574 /**
 575  * Returns 1 if the modifier specified by 'idx' is active in the manner
 576  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 577  * exist in the current map.
 578  */
 579 int
 580 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
 581                               enum xkb_state_component type);
 582
 583 /**
 584  * Returns 1 if the modifiers specified by the varargs (treated as
 585  * xkb_mod_index_t, terminated with XKB_MOD_INVALID) are active in the manner
 586  * specified by 'match' and 'type', 0 otherwise, or -1 if the modifier does not
 587  * exist in the current map.
 588  */
 589 int
 590 xkb_state_mod_indices_are_active(struct xkb_state *state,
 591                                  enum xkb_state_component type,
 592                                  enum xkb_state_match match,
 593                                  ...);
 594
 595 /**
 596  * Returns 1 if the group specified by 'name' is active in the manner
 597  * specified by 'type', 0 if it is unset, or -1 if the group does not
 598  * exist in the current map.
 599  */
 600 int
 601 xkb_state_group_name_is_active(struct xkb_state *state, const char *name,
 602                                enum xkb_state_component type);
 603
 604 /**
 605  * Returns 1 if the group specified by 'idx' is active in the manner
 606  * specified by 'type', 0 if it is unset, or -1 if the group does not
 607  * exist in the current map.
 608  */
 609 int
 610 xkb_state_group_index_is_active(struct xkb_state *state, xkb_group_index_t idx,
 611                                 enum xkb_state_component type);
 612
 613 /**
 614  * Returns 1 if the LED specified by 'name' is active, 0 if it is unset, or
 615  * -1 if the LED does not exist in the current map.
 616  */
 617 int
 618 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
 619
 620 /**
 621  * Returns 1 if the LED specified by 'idx' is active, 0 if it is unset, or
 622  * -1 if the LED does not exist in the current map.
 623  */
 624 int
 625 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
 626
 627 /** @} */
 628
 629 #ifdef __cplusplus
 630 } /* extern "C" */
 631 #endif
 632
 633 #endif /* _XKBCOMMON_H_ */