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