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