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