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