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-2012 Daniel Stone
  56  * Copyright © 2012 Intel Corporation
  57  *
  58  * Permission is hereby granted, free of charge, to any person obtaining a
  59  * copy of this software and associated documentation files (the "Software"),
  60  * to deal in the Software without restriction, including without limitation
  61  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  62  * and/or sell copies of the Software, and to permit persons to whom the
  63  * Software is furnished to do so, subject to the following conditions:
  64  *
  65  * The above copyright notice and this permission notice (including the next
  66  * paragraph) shall be included in all copies or substantial portions of the
  67  * Software.
  68  *
  69  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  70  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  71  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  72  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  73  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  74  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  75  * DEALINGS IN THE SOFTWARE.
  76  *
  77  * Author: Daniel Stone <daniel@fooishbar.org>
  78  */
  79
  80 #ifndef _XKBCOMMON_H_
  81 #define _XKBCOMMON_H_
  82
  83 #include <stdint.h>
  84 #include <stdio.h>
  85 #include <stdarg.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_layout_index_t;
  95 typedef uint32_t xkb_layout_mask_t;
  96 typedef uint32_t xkb_level_index_t;
  97 typedef uint32_t xkb_led_index_t;
  98 typedef uint32_t xkb_led_mask_t;
  99
 100 #define XKB_MOD_INVALID     (0xffffffff)
 101 #define XKB_LAYOUT_INVALID  (0xffffffff)
 102 #define XKB_KEYCODE_INVALID (0xffffffff)
 103 #define XKB_LEVEL_INVALID   (0xffffffff)
 104 #define XKB_LED_INVALID     (0xffffffff)
 105
 106 #define XKB_KEYCODE_MAX     (0xffffffff - 1)
 107 #define xkb_keycode_is_legal_ext(kc) (kc <= XKB_KEYCODE_MAX)
 108 #define xkb_keycode_is_legal_x11(kc) (kc >= 8 && kc <= 255)
 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  * Opaque context object; may only be created, accessed, manipulated and
 124  * destroyed through the xkb_context_*() API.
 125  */
 126 struct xkb_context;
 127
 128 /**
 129  * Opaque keymap object; may only be created, accessed, manipulated and
 130  * destroyed through the xkb_state_*() API.
 131  */
 132 struct xkb_keymap;
 133
 134 /**
 135  * Opaque state object; may only be created, accessed, manipulated and
 136  * destroyed through the xkb_state_*() API.
 137  */
 138 struct xkb_state;
 139
 140 #ifdef __cplusplus
 141 extern "C" {
 142 #endif
 143
 144 /*
 145  * Returns the name for a keysym as a string; will return unknown Unicode
 146  * codepoints as "Ua1b2", and other unknown keysyms as "0xabcd1234".
 147  * If the buffer passed is too small, the string is truncated; a size of
 148  * at least 32 bytes is recommended.
 149  */
 150 void
 151 xkb_keysym_get_name(xkb_keysym_t ks, char *buffer, size_t size);
 152
 153 /*
 154  * See xkb_keysym_get_name comments: this function will accept any string
 155  * from that function.
 156  */
 157 xkb_keysym_t
 158 xkb_keysym_from_name(const char *s);
 159
 160 /**
 161  * Return the printable representation of the keystring in Unicode/UTF-8.
 162  * The buffer passed must be at least 7 bytes long.  The return value
 163  * is the number of bytes written to the buffer.  A return value of zero
 164  * means that the keysym does not have a known printable Unicode
 165  * representation, and a return value of -1 means that the buffer was too
 166  * small to contain the return.
 167  */
 168 int
 169 xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size);
 170
 171 /**
 172  * Returns the Unicode/UTF-32 representation of the provided keysym, which is
 173  * also compatible with UCS-4.  A return value of zero means the keysym does
 174  * not have a known printable Unicode representation.
 175  */
 176 uint32_t
 177 xkb_keysym_to_utf32(xkb_keysym_t keysym);
 178
 179 /**
 180  * @defgroup context XKB contexts
 181  * Every keymap compilation request must have an XKB context associated with
 182  * it.  The context keeps around state such as the include path.
 183  *
 184  * @{
 185  */
 186
 187 enum xkb_context_flags {
 188     /** Create this context with an empty include path. */
 189     XKB_CONTEXT_NO_DEFAULT_INCLUDES = 1,
 190 };
 191
 192 /**
 193  * Returns a new XKB context, or NULL on failure.  If successful, the caller
 194  * holds a reference on the context, and must free it when finished with
 195  * xkb_context_unref().
 196  */
 197 struct xkb_context *
 198 xkb_context_new(enum xkb_context_flags flags);
 199
 200 /**
 201  * Appends a new entry to the include path used for keymap compilation.
 202  * Returns 1 on success, or 0 if the include path could not be added or is
 203  * inaccessible.
 204  */
 205 int
 206 xkb_context_include_path_append(struct xkb_context *context, const char *path);
 207
 208 /**
 209  * Appends the default include paths to the context's current include path.
 210  * Returns 1 on success, or 0 if the primary include path could not be
 211  * added.
 212  */
 213 int
 214 xkb_context_include_path_append_default(struct xkb_context *context);
 215
 216 /**
 217  * Removes all entries from the context's include path, and inserts the
 218  * default paths.  Returns 1 on success, or 0 if the primary include path
 219  * could not be added.
 220  */
 221 int
 222 xkb_context_include_path_reset_defaults(struct xkb_context *context);
 223
 224 /**
 225  * Removes all entries from the context's include path.
 226  */
 227 void
 228 xkb_context_include_path_clear(struct xkb_context *context);
 229
 230 /**
 231  * Returns the number of include paths currently active in the context.
 232  */
 233 unsigned int
 234 xkb_context_num_include_paths(struct xkb_context *context);
 235
 236 /**
 237  * Returns the include path at the specified index within the context.
 238  */
 239 const char *
 240 xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
 241
 242 /**
 243  * Takes a new reference on an XKB context.
 244  */
 245 struct xkb_context *
 246 xkb_context_ref(struct xkb_context *context);
 247
 248 /**
 249  * Releases a reference on an XKB context, and possibly frees it.
 250  */
 251 void
 252 xkb_context_unref(struct xkb_context *context);
 253
 254 /** @} */
 255
 256 /**
 257  * @defgroup logging Logging handling
 258  * These functions allow you to manipulate how logging from this library
 259  * will be handled.
 260  *
 261  * @{
 262  */
 263
 264 enum xkb_log_level {
 265     /** Log critical internal errors only */
 266     XKB_LOG_LEVEL_CRITICAL = 10,
 267     /** Log all errors */
 268     XKB_LOG_LEVEL_ERROR = 20,
 269     /** Log warnings and errors */
 270     XKB_LOG_LEVEL_WARNING = 30,
 271     /** Log information, warnings, and errors */
 272     XKB_LOG_LEVEL_INFO = 40,
 273     /** Log all the things */
 274     XKB_LOG_LEVEL_DEBUG = 50,
 275 };
 276
 277 /**
 278  * Sets the function to be called for logging messages.
 279  * Passing NULL restores the default function, which logs to stderr.
 280  **/
 281 void
 282 xkb_context_set_log_fn(struct xkb_context *context,
 283                        void (*log_fn)(struct xkb_context *context,
 284                                       enum xkb_log_level level,
 285                                       const char *format, va_list args));
 286 /**
 287  * Sets the current logging level.  The value controls which messages
 288  * are logged.  The default level is XKB_LOG_LEVEL_ERROR.
 289  *
 290  * The environment variable XKB_LOG, if set, overrides the default value
 291  * and may be specified as a level number or name.
 292  */
 293 void
 294 xkb_context_set_log_level(struct xkb_context *context,
 295                           enum xkb_log_level level);
 296
 297 /**
 298  * Returns the current logging level.
 299  */
 300 enum xkb_log_level
 301 xkb_context_get_log_level(struct xkb_context *context);
 302
 303 /**
 304  * Sets the current logging verbosity, a value from 0 to 10.
 305  *
 306  * The library can generate a number of warnings which are not helpful to
 307  * ordinary users of the library.  The verbosity may be increased if more
 308  * information is desired (e.g. when developing a keymap).  Defaults to 0.
 309  * The environment variable XKB_VERBOSITY, if set, overrdies the default
 310  * value.
 311  *
 312  * Note that most verbose messages are of level XKB_LOG_LEVEL_WARNING
 313  * or lower.
 314  */
 315 void
 316 xkb_context_set_log_verbosity(struct xkb_context *ctx, int verbosity);
 317
 318 /**
 319  * Returns the current logging verbosity.
 320  */
 321 int
 322 xkb_context_get_log_verbosity(struct xkb_context *ctx);
 323
 324 /**
 325  * Retrieves stored data pointer from the context.  This might be useful
 326  * to access from callbacks like a custom logging function.
 327  *
 328  * If context is NULL, returns NULL.
 329  **/
 330 void *
 331 xkb_context_get_user_data(struct xkb_context *context);
 332
 333 /**
 334  * Store custom user data in the context.
 335  */
 336 void
 337 xkb_context_set_user_data(struct xkb_context *context, void *user_data);
 338
 339 /** @} */
 340
 341 /**
 342  * @defgroup map Keymap management
 343  * These utility functions allow you to create and deallocate XKB keymaps.
 344  *
 345  * @{
 346  */
 347
 348 enum xkb_keymap_compile_flags {
 349     /** Apparently you can't have empty enums.  What a drag. */
 350     XKB_MAP_COMPILE_PLACEHOLDER = 0,
 351 };
 352
 353 /**
 354  * The primary keymap entry point: creates a new XKB keymap from a set of
 355  * RMLVO (Rules + Model + Layout + Variant + Option) names.
 356  *
 357  * You should almost certainly be using this and nothing else to create
 358  * keymaps.
 359  */
 360 struct xkb_keymap *
 361 xkb_keymap_new_from_names(struct xkb_context *context,
 362                           const struct xkb_rule_names *names,
 363                           enum xkb_keymap_compile_flags flags);
 364
 365 enum xkb_keymap_format {
 366     /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
 367     XKB_KEYMAP_FORMAT_TEXT_V1 = 1,
 368 };
 369
 370 /**
 371  * Creates an XKB keymap from a full text XKB keymap passed into the
 372  * file.
 373  */
 374 struct xkb_keymap *
 375 xkb_keymap_new_from_file(struct xkb_context *context, FILE *file,
 376                          enum xkb_keymap_format format,
 377                          enum xkb_keymap_compile_flags flags);
 378
 379 /**
 380  * Creates an XKB keymap from a full text XKB keymap serialized into one
 381  * enormous string.
 382  */
 383 struct xkb_keymap *
 384 xkb_keymap_new_from_string(struct xkb_context *context, const char *string,
 385                            enum xkb_keymap_format format,
 386                            enum xkb_keymap_compile_flags flags);
 387
 388 /**
 389  * Returns the compiled XKB map as a string which can later be fed back into
 390  * xkb_map_new_from_string to return the exact same keymap.
 391  */
 392 char *
 393 xkb_keymap_get_as_string(struct xkb_keymap *keymap);
 394
 395 /**
 396  * Takes a new reference on a keymap.
 397  */
 398 struct xkb_keymap *
 399 xkb_keymap_ref(struct xkb_keymap *keymap);
 400
 401 /**
 402  * Releases a reference on a keymap.
 403  */
 404 void
 405 xkb_keymap_unref(struct xkb_keymap *keymap);
 406
 407 /** @} */
 408
 409 /**
 410  * @defgroup components XKB state components
 411  * Allows enumeration of state components such as modifiers and groups within
 412  * the current keymap.
 413  *
 414  * @{
 415  */
 416
 417 /**
 418  * Returns the number of modifiers active in the keymap.
 419  */
 420 xkb_mod_index_t
 421 xkb_keymap_num_mods(struct xkb_keymap *keymap);
 422
 423 /**
 424  * Returns the name of the modifier specified by 'idx', or NULL if invalid.
 425  */
 426 const char *
 427 xkb_keymap_mod_get_name(struct xkb_keymap *keymap, xkb_mod_index_t idx);
 428
 429 /**
 430  * Returns the index of the modifier specified by 'name', or XKB_MOD_INVALID.
 431  */
 432 xkb_mod_index_t
 433 xkb_keymap_mod_get_index(struct xkb_keymap *keymap, const char *name);
 434
 435 /**
 436  * Returns the number of groups active in the keymap.
 437  */
 438 xkb_layout_index_t
 439 xkb_keymap_num_layouts(struct xkb_keymap *keymap);
 440
 441 /**
 442  * Returns the name of the group specified by 'idx', or NULL if invalid.
 443  */
 444 const char *
 445 xkb_keymap_layout_get_name(struct xkb_keymap *keymap, xkb_layout_index_t idx);
 446
 447 /**
 448  * Returns the index of the layout specified by 'name', or XKB_LAYOUT_INVALID.
 449  */
 450 xkb_layout_index_t
 451 xkb_keymap_layout_get_index(struct xkb_keymap *keymap, const char *name);
 452
 453 /**
 454  * Returns the number of layouts active for the specified key.
 455  */
 456 xkb_layout_index_t
 457 xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key);
 458
 459 /**
 460  * Returns the number of levels active for the specified key and layout.
 461  */
 462 xkb_level_index_t
 463 xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key,
 464                               xkb_layout_index_t layout);
 465
 466 /**
 467  * Returns 1 if the key should repeat, or 0 otherwise.
 468  */
 469 int
 470 xkb_keymap_key_repeats(struct xkb_keymap *keymap, xkb_keycode_t key);
 471
 472 /**
 473  * Returns the number of LEDs in the given map.
 474  */
 475 xkb_led_index_t
 476 xkb_keymap_num_leds(struct xkb_keymap *keymap);
 477
 478 /**
 479  * Returns the name of the LED specified by 'idx', or NULL if invalid.
 480  */
 481 const char *
 482 xkb_keymap_led_get_name(struct xkb_keymap *keymap, xkb_led_index_t idx);
 483
 484 /**
 485  * Returns the index of the LED specified by 'name', or XKB_LED_INVALID.
 486  */
 487 xkb_led_index_t
 488 xkb_keymap_led_get_index(struct xkb_keymap *keymap, const char *name);
 489
 490 /** @} */
 491
 492 /**
 493  * @defgroup state XKB state objects
 494  * Creation, destruction and manipulation of keyboard state objects,
 495  * representing modifier and group state.
 496  *
 497  * @{
 498  */
 499
 500 /**
 501  * Returns a new XKB state object for use with the given keymap, or NULL on
 502  * failure.
 503  */
 504 struct xkb_state *
 505 xkb_state_new(struct xkb_keymap *keymap);
 506
 507 /**
 508  * Takes a new reference on a state object.
 509  */
 510 struct xkb_state *
 511 xkb_state_ref(struct xkb_state *state);
 512
 513 /**
 514  * Unrefs and potentially deallocates a state object; the caller must not
 515  * use the state object after calling this.
 516  */
 517 void
 518 xkb_state_unref(struct xkb_state *state);
 519
 520 /**
 521  * Get the keymap from which the state object was created.  Does not take
 522  * a new reference on the map; you must explicitly reference it yourself
 523  * if you plan to use it beyond the lifetime of the state.
 524  */
 525 struct xkb_keymap *
 526 xkb_state_get_keymap(struct xkb_state *state);
 527
 528 enum xkb_key_direction {
 529     XKB_KEY_UP,
 530     XKB_KEY_DOWN,
 531 };
 532
 533 /**
 534  * Updates a state object to reflect the given key being pressed or released.
 535  */
 536 void
 537 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
 538                      enum xkb_key_direction direction);
 539
 540 /**
 541  * Gives the symbols obtained from pressing a particular key with the given
 542  * state.  *syms_out will be set to point to an array of keysyms, with the
 543  * return value being the number of symbols in *syms_out.  If the return
 544  * value is 0, *syms_out will be set to NULL, as there are no symbols produced
 545  * by this event.
 546  */
 547 int
 548 xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
 549                        const xkb_keysym_t **syms_out);
 550
 551 /**
 552  * Returns the layout number that would be active for a particular key with
 553  * the given state.
 554  */
 555 xkb_layout_index_t
 556 xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t key);
 557
 558 /**
 559  * Returns the level number that would be active for a particular key with
 560  * the given state and layout number, usually obtained from
 561  * xkb_state_key_get_layout.
 562  */
 563 xkb_level_index_t
 564 xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t key,
 565                         xkb_layout_index_t layout);
 566
 567 /**
 568  * Gives the symbols obtained from pressing a particular key with the given
 569  * layout and level.  *syms_out will be set to point to an array of keysyms,
 570  * with the return value being the number of symbols in *syms_out.  If the
 571  * return value is 0, *syms_out will be set to NULL, as there are no symbols
 572  * produced by this event.
 573  */
 574 int
 575 xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap,
 576                                  xkb_keycode_t key,
 577                                  xkb_layout_index_t layout,
 578                                  xkb_level_index_t level,
 579                                  const xkb_keysym_t **syms_out);
 580
 581 /**
 582  * Modifier and group types for state objects.  This enum is bitmaskable,
 583  * e.g. (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED) is valid to exclude
 584  * locked modifiers.
 585  */
 586 enum xkb_state_component {
 587     /** A key holding this modifier or group is currently physically
 588      *  depressed; also known as 'base'. */
 589     XKB_STATE_DEPRESSED = (1 << 0),
 590     /** Modifier or group is latched, i.e. will be unset after the next
 591      *  non-modifier key press. */
 592     XKB_STATE_LATCHED = (1 << 1),
 593     /** Modifier or group is locked, i.e. will be unset after the key
 594      *  provoking the lock has been pressed again. */
 595     XKB_STATE_LOCKED = (1 << 2),
 596     /** Combinatination of depressed, latched, and locked. */
 597     XKB_STATE_EFFECTIVE =
 598         (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED | XKB_STATE_LOCKED),
 599 };
 600
 601 /**
 602  * Match flags for xkb_state_mod_indices_are_active and
 603  * xkb_state_mod_names_are_active, specifying how the conditions for a
 604  * successful match.  XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with
 605  * the other modes.
 606  */
 607 enum xkb_state_match {
 608     /** Returns true if any of the modifiers are active. */
 609     XKB_STATE_MATCH_ANY = (1 << 0),
 610     /** Returns true if all of the modifiers are active. */
 611     XKB_STATE_MATCH_ALL = (1 << 1),
 612     /** Makes matching non-exclusive, i.e. will not return false if a
 613      *  modifier not specified in the arguments is active. */
 614     XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16),
 615 };
 616
 617 /**
 618  * Updates a state object from a set of explicit masks.  This entrypoint is
 619  * really only for window systems and the like, where a master process
 620  * holds an xkb_state, then serializes it over a wire protocol, and clients
 621  * then use the serialization to feed in to their own xkb_state.
 622  *
 623  * All parameters must always be passed, or the resulting state may be
 624  * incoherent.
 625  *
 626  * The serialization is lossy and will not survive round trips; it must only
 627  * be used to feed slave state objects, and must not be used to update the
 628  * master state.
 629  *
 630  * Please do not use this unless you fit the description above.
 631  */
 632 void
 633 xkb_state_update_mask(struct xkb_state *state, xkb_mod_mask_t base_mods,
 634                       xkb_mod_mask_t latched_mods, xkb_mod_mask_t locked_mods,
 635                       xkb_layout_index_t base_group,
 636                       xkb_layout_index_t latched_group,
 637                       xkb_layout_index_t locked_group);
 638
 639 /**
 640  * The counterpart to xkb_state_update_mask, to be used on the server side
 641  * of serialization.  Returns a xkb_mod_mask_t representing the given
 642  * component(s) of the state.
 643  *
 644  * This function should not be used in regular clients; please use the
 645  * xkb_state_mod_*_is_active or xkb_state_foreach_active_mod API instead.
 646  *
 647  * Can return NULL on failure.
 648  */
 649 xkb_mod_mask_t
 650 xkb_state_serialize_mods(struct xkb_state *state,
 651                          enum xkb_state_component component);
 652
 653 /**
 654  * The group equivalent of xkb_state_serialize_mods: please see its
 655  * documentation.
 656  */
 657 xkb_layout_index_t
 658 xkb_state_serialize_layout(struct xkb_state *state,
 659                            enum xkb_state_component component);
 660
 661 /**
 662  * Returns 1 if the modifier specified by 'name' is active in the manner
 663  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 664  * exist in the map.
 665  */
 666 int
 667 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
 668                              enum xkb_state_component type);
 669
 670 /**
 671  * Returns 1 if the modifiers specified by the varargs (NULL-terminated
 672  * strings, with a NULL sentinel) are active in the manner specified by
 673  * 'match', 0 otherwise, or -1 if any of the modifiers do not exist in
 674  * the map.
 675  */
 676 int
 677 xkb_state_mod_names_are_active(struct xkb_state *state,
 678                                enum xkb_state_component type,
 679                                enum xkb_state_match match,
 680                                ...);
 681
 682 /**
 683  * Returns 1 if the modifier specified by 'idx' is active in the manner
 684  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 685  * exist in the current map.
 686  */
 687 int
 688 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
 689                               enum xkb_state_component type);
 690
 691 /**
 692  * Returns 1 if the modifiers specified by the varargs (of type
 693  * xkb_mod_index_t, with a XKB_MOD_INVALID sentinel) are active in the
 694  * manner specified by 'match' and 'type', 0 otherwise, or -1 if any of
 695  * the modifiers do not exist in the map.
 696  */
 697 int
 698 xkb_state_mod_indices_are_active(struct xkb_state *state,
 699                                  enum xkb_state_component type,
 700                                  enum xkb_state_match match,
 701                                  ...);
 702
 703 /**
 704  * Returns 1 if the modifier specified by 'idx' is used in the
 705  * translation of the keycode 'key' to the key symbols obtained by
 706  * pressing it (as in xkb_key_get_syms), given the current state.
 707  * Returns 0 otherwise.
 708  */
 709 int
 710 xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key,
 711                                 xkb_mod_index_t idx);
 712
 713 /**
 714  * Takes the given modifier mask, and removes all modifiers which are
 715  * marked as 'consumed' (see xkb_key_mod_index_is_consumed definition)
 716  * for that particular key.
 717  */
 718 xkb_mod_mask_t
 719 xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t key,
 720                                    xkb_mod_mask_t mask);
 721
 722 /**
 723  * Returns 1 if the group specified by 'name' is active in the manner
 724  * specified by 'type', 0 if it is unset, or -1 if the group does not
 725  * exist in the current map.
 726  */
 727 int
 728 xkb_state_layout_name_is_active(struct xkb_state *state, const char *name,
 729                                 enum xkb_state_component type);
 730
 731 /**
 732  * Returns 1 if the group specified by 'idx' is active in the manner
 733  * specified by 'type', 0 if it is unset, or -1 if the group does not
 734  * exist in the current map.
 735  */
 736 int
 737 xkb_state_layout_index_is_active(struct xkb_state *state,
 738                                  xkb_layout_index_t idx,
 739                                  enum xkb_state_component type);
 740
 741 /**
 742  * Returns 1 if the LED specified by 'name' is active, 0 if it is unset, or
 743  * -1 if the LED does not exist in the current map.
 744  */
 745 int
 746 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
 747
 748 /**
 749  * Returns 1 if the LED specified by 'idx' is active, 0 if it is unset, or
 750  * -1 if the LED does not exist in the current map.
 751  */
 752 int
 753 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
 754
 755 /** @} */
 756
 757 /* Leave this include last, so it can pick up our types, etc. */
 758 #include <xkbcommon/xkbcommon-compat.h>
 759
 760 #ifdef __cplusplus
 761 } /* extern "C" */
 762 #endif
 763
 764 #endif /* _XKBCOMMON_H_ */