src/state.c

   1 /************************************************************
   2  * Copyright (c) 1993 by Silicon Graphics Computer Systems, Inc.
   3  *
   4  * Permission to use, copy, modify, and distribute this
   5  * software and its documentation for any purpose and without
   6  * fee is hereby granted, provided that the above copyright
   7  * notice appear in all copies and that both that copyright
   8  * notice and this permission notice appear in supporting
   9  * documentation, and that the name of Silicon Graphics not be
  10  * used in advertising or publicity pertaining to distribution
  11  * of the software without specific prior written permission.
  12  * Silicon Graphics makes no representation about the suitability
  13  * of this software for any purpose. It is provided "as is"
  14  * without any express or implied warranty.
  15  *
  16  * SILICON GRAPHICS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
  17  * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  18  * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SILICON
  19  * GRAPHICS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  20  * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  21  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  22  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION  WITH
  23  * THE USE OR PERFORMANCE OF THIS SOFTWARE.
  24  *
  25  ********************************************************/
  26
  27 /*
  28  * Copyright © 2012 Intel Corporation
  29  * Copyright © 2012 Ran Benita <ran234@gmail.com>
  30  *
  31  * Permission is hereby granted, free of charge, to any person obtaining a
  32  * copy of this software and associated documentation files (the "Software"),
  33  * to deal in the Software without restriction, including without limitation
  34  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  35  * and/or sell copies of the Software, and to permit persons to whom the
  36  * Software is furnished to do so, subject to the following conditions:
  37  *
  38  * The above copyright notice and this permission notice (including the next
  39  * paragraph) shall be included in all copies or substantial portions of the
  40  * Software.
  41  *
  42  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  43  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  44  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  45  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  46  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  47  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  48  * DEALINGS IN THE SOFTWARE.
  49  *
  50  * Author: Daniel Stone <daniel@fooishbar.org>
  51  */
  52
  53 /*
  54  * This is a bastardised version of xkbActions.c from the X server which
  55  * does not support, for the moment:
  56  *   - AccessX sticky/debounce/etc (will come later)
  57  *   - pointer keys (may come later)
  58  *   - key redirects (unlikely)
  59  *   - messages (very unlikely)
  60  */
  61
  62 #include "keymap.h"
  63 #include "keysym.h"
  64 #include "utf8.h"
  65
  66 struct xkb_filter {
  67     union xkb_action action;
  68     const struct xkb_key *key;
  69     uint32_t priv;
  70     bool (*func)(struct xkb_state *state,
  71                  struct xkb_filter *filter,
  72                  const struct xkb_key *key,
  73                  enum xkb_key_direction direction);
  74     int refcnt;
  75 };
  76
  77 struct state_components {
  78     /* These may be negative, because of -1 group actions. */
  79     int32_t base_group; /**< depressed */
  80     int32_t latched_group;
  81     int32_t locked_group;
  82     xkb_layout_index_t group; /**< effective */
  83
  84     xkb_mod_mask_t base_mods; /**< depressed */
  85     xkb_mod_mask_t latched_mods;
  86     xkb_mod_mask_t locked_mods;
  87     xkb_mod_mask_t mods; /**< effective */
  88
  89     xkb_led_mask_t leds;
  90 };
  91
  92 struct xkb_state {
  93     /*
  94      * Before updating the state, we keep a copy of just this struct. This
  95      * allows us to report which components of the state have changed.
  96      */
  97     struct state_components components;
  98
  99     /*
 100      * At each event, we accumulate all the needed modifications to the base
 101      * modifiers, and apply them at the end. These keep track of this state.
 102      */
 103     xkb_mod_mask_t set_mods;
 104     xkb_mod_mask_t clear_mods;
 105
 106     /*
 107      * We mustn't clear a base modifier if there's another depressed key
 108      * which affects it, e.g. given this sequence
 109      * < Left Shift down, Right Shift down, Left Shift Up >
 110      * the modifier should still be set. This keeps the count.
 111      */
 112     int16_t mod_key_count[XKB_MAX_MODS];
 113
 114     int refcnt;
 115     darray(struct xkb_filter) filters;
 116     struct xkb_keymap *keymap;
 117 };
 118
 119 /*
 120  * If the virtual modifiers are not bound to anything, the entry
 121  * is not active and should be skipped. xserver does this with
 122  * cached entry->active field.
 123  */
 124 static bool
 125 entry_is_active(const struct xkb_key_type_entry *entry)
 126 {
 127     return entry->mods.mods == 0 || entry->mods.mask != 0;
 128 }
 129
 130 static const struct xkb_key_type_entry *
 131 get_entry_for_key_state(struct xkb_state *state, const struct xkb_key *key,
 132                         xkb_layout_index_t group)
 133 {
 134     const struct xkb_key_type *type = key->groups[group].type;
 135     xkb_mod_mask_t active_mods = state->components.mods & type->mods.mask;
 136
 137     for (unsigned i = 0; i < type->num_entries; i++)
 138         if (entry_is_active(&type->entries[i]) &&
 139             type->entries[i].mods.mask == active_mods)
 140             return &type->entries[i];
 141
 142     return NULL;
 143 }
 144
 145 /**
 146  * Returns the level to use for the given key and state, or
 147  * XKB_LEVEL_INVALID.
 148  */
 149 XKB_EXPORT xkb_level_index_t
 150 xkb_state_key_get_level(struct xkb_state *state, xkb_keycode_t kc,
 151                         xkb_layout_index_t layout)
 152 {
 153     const struct xkb_key *key = XkbKey(state->keymap, kc);
 154     const struct xkb_key_type_entry *entry;
 155
 156     if (!key || layout >= key->num_groups)
 157         return XKB_LEVEL_INVALID;
 158
 159     /* If we don't find an explicit match the default is 0. */
 160     entry = get_entry_for_key_state(state, key, layout);
 161     if (!entry)
 162         return 0;
 163
 164     return entry->level;
 165 }
 166
 167 xkb_layout_index_t
 168 XkbWrapGroupIntoRange(int32_t group,
 169                       xkb_layout_index_t num_groups,
 170                       enum xkb_range_exceed_type out_of_range_group_action,
 171                       xkb_layout_index_t out_of_range_group_number)
 172 {
 173     if (num_groups == 0)
 174         return XKB_LAYOUT_INVALID;
 175
 176     if (group >= 0 && (xkb_layout_index_t) group < num_groups)
 177         return group;
 178
 179     switch (out_of_range_group_action) {
 180     case RANGE_REDIRECT:
 181         if (out_of_range_group_number >= num_groups)
 182             return 0;
 183         return out_of_range_group_number;
 184
 185     case RANGE_SATURATE:
 186         if (group < 0)
 187             return 0;
 188         else
 189             return num_groups - 1;
 190
 191     case RANGE_WRAP:
 192     default:
 193         /*
 194          * C99 says a negative dividend in a modulo operation always
 195          * gives a negative result.
 196          */
 197         if (group < 0)
 198             return ((int) num_groups + (group % (int) num_groups));
 199         else
 200             return group % num_groups;
 201     }
 202 }
 203
 204 /**
 205  * Returns the layout to use for the given key and state, taking
 206  * wrapping/clamping/etc into account, or XKB_LAYOUT_INVALID.
 207  */
 208 XKB_EXPORT xkb_layout_index_t
 209 xkb_state_key_get_layout(struct xkb_state *state, xkb_keycode_t kc)
 210 {
 211     const struct xkb_key *key = XkbKey(state->keymap, kc);
 212
 213     if (!key)
 214         return XKB_LAYOUT_INVALID;
 215
 216     return XkbWrapGroupIntoRange(state->components.group, key->num_groups,
 217                                  key->out_of_range_group_action,
 218                                  key->out_of_range_group_number);
 219 }
 220
 221 static const union xkb_action *
 222 xkb_key_get_action(struct xkb_state *state, const struct xkb_key *key)
 223 {
 224     static const union xkb_action dummy = { .type = ACTION_TYPE_NONE };
 225
 226     xkb_layout_index_t layout;
 227     xkb_level_index_t level;
 228
 229     layout = xkb_state_key_get_layout(state, key->keycode);
 230     if (layout == XKB_LAYOUT_INVALID)
 231         return &dummy;
 232
 233     level = xkb_state_key_get_level(state, key->keycode, layout);
 234     if (level == XKB_LEVEL_INVALID)
 235         return &dummy;
 236
 237     return &key->groups[layout].levels[level].action;
 238 }
 239
 240 static struct xkb_filter *
 241 xkb_filter_new(struct xkb_state *state)
 242 {
 243     struct xkb_filter *filter = NULL, *iter;
 244
 245     darray_foreach(iter, state->filters) {
 246         if (iter->func)
 247             continue;
 248         filter = iter;
 249         break;
 250     }
 251
 252     if (!filter) {
 253         darray_resize0(state->filters, darray_size(state->filters) + 1);
 254         filter = &darray_item(state->filters, darray_size(state->filters) -1);
 255     }
 256
 257     filter->refcnt = 1;
 258     return filter;
 259 }
 260
 261 /***====================================================================***/
 262
 263 static bool
 264 xkb_filter_group_set_func(struct xkb_state *state,
 265                           struct xkb_filter *filter,
 266                           const struct xkb_key *key,
 267                           enum xkb_key_direction direction)
 268 {
 269     if (key != filter->key) {
 270         filter->action.group.flags &= ~ACTION_LOCK_CLEAR;
 271         return true;
 272     }
 273
 274     if (direction == XKB_KEY_DOWN) {
 275         filter->refcnt++;
 276         return false;
 277     }
 278     else if (--filter->refcnt > 0) {
 279         return false;
 280     }
 281
 282     state->components.base_group = filter->priv;
 283
 284     if (filter->action.group.flags & ACTION_LOCK_CLEAR)
 285         state->components.locked_group = 0;
 286
 287     filter->func = NULL;
 288     return true;
 289 }
 290
 291 static void
 292 xkb_filter_group_set_new(struct xkb_state *state, struct xkb_filter *filter)
 293 {
 294     filter->priv = state->components.base_group;
 295     if (filter->action.group.flags & ACTION_ABSOLUTE_SWITCH)
 296         state->components.base_group = filter->action.group.group;
 297     else
 298         state->components.base_group += filter->action.group.group;
 299 }
 300
 301 static bool
 302 xkb_filter_group_lock_func(struct xkb_state *state,
 303                            struct xkb_filter *filter,
 304                            const struct xkb_key *key,
 305                            enum xkb_key_direction direction)
 306 {
 307     if (key != filter->key)
 308         return true;
 309
 310     if (direction == XKB_KEY_DOWN) {
 311         filter->refcnt++;
 312         return false;
 313     }
 314     if (--filter->refcnt > 0)
 315         return false;
 316
 317     filter->func = NULL;
 318     return true;
 319 }
 320
 321 static void
 322 xkb_filter_group_lock_new(struct xkb_state *state, struct xkb_filter *filter)
 323 {
 324     if (filter->action.group.flags & ACTION_ABSOLUTE_SWITCH)
 325         state->components.locked_group = filter->action.group.group;
 326     else
 327         state->components.locked_group += filter->action.group.group;
 328 }
 329
 330 static bool
 331 xkb_filter_mod_set_func(struct xkb_state *state,
 332                         struct xkb_filter *filter,
 333                         const struct xkb_key *key,
 334                         enum xkb_key_direction direction)
 335 {
 336     if (key != filter->key) {
 337         filter->action.mods.flags &= ~ACTION_LOCK_CLEAR;
 338         return true;
 339     }
 340
 341     if (direction == XKB_KEY_DOWN) {
 342         filter->refcnt++;
 343         return false;
 344     }
 345     else if (--filter->refcnt > 0) {
 346         return false;
 347     }
 348
 349     state->clear_mods = filter->action.mods.mods.mask;
 350     if (filter->action.mods.flags & ACTION_LOCK_CLEAR)
 351         state->components.locked_mods &= ~filter->action.mods.mods.mask;
 352
 353     filter->func = NULL;
 354     return true;
 355 }
 356
 357 static void
 358 xkb_filter_mod_set_new(struct xkb_state *state, struct xkb_filter *filter)
 359 {
 360     state->set_mods = filter->action.mods.mods.mask;
 361 }
 362
 363 static bool
 364 xkb_filter_mod_lock_func(struct xkb_state *state,
 365                          struct xkb_filter *filter,
 366                          const struct xkb_key *key,
 367                          enum xkb_key_direction direction)
 368 {
 369     if (key != filter->key)
 370         return true;
 371
 372     if (direction == XKB_KEY_DOWN) {
 373         filter->refcnt++;
 374         return false;
 375     }
 376     if (--filter->refcnt > 0)
 377         return false;
 378
 379     state->clear_mods |= filter->action.mods.mods.mask;
 380     if (!(filter->action.mods.flags & ACTION_LOCK_NO_UNLOCK))
 381         state->components.locked_mods &= ~filter->priv;
 382
 383     filter->func = NULL;
 384     return true;
 385 }
 386
 387 static void
 388 xkb_filter_mod_lock_new(struct xkb_state *state, struct xkb_filter *filter)
 389 {
 390     filter->priv = (state->components.locked_mods &
 391                     filter->action.mods.mods.mask);
 392     state->set_mods |= filter->action.mods.mods.mask;
 393     if (!(filter->action.mods.flags & ACTION_LOCK_NO_LOCK))
 394         state->components.locked_mods |= filter->action.mods.mods.mask;
 395 }
 396
 397 enum xkb_key_latch_state {
 398     NO_LATCH,
 399     LATCH_KEY_DOWN,
 400     LATCH_PENDING,
 401 };
 402
 403 static bool
 404 xkb_action_breaks_latch(const union xkb_action *action)
 405 {
 406     switch (action->type) {
 407     case ACTION_TYPE_NONE:
 408     case ACTION_TYPE_PTR_BUTTON:
 409     case ACTION_TYPE_PTR_LOCK:
 410     case ACTION_TYPE_CTRL_SET:
 411     case ACTION_TYPE_CTRL_LOCK:
 412     case ACTION_TYPE_SWITCH_VT:
 413     case ACTION_TYPE_TERMINATE:
 414         return true;
 415     default:
 416         return false;
 417     }
 418 }
 419
 420 static bool
 421 xkb_filter_mod_latch_func(struct xkb_state *state,
 422                           struct xkb_filter *filter,
 423                           const struct xkb_key *key,
 424                           enum xkb_key_direction direction)
 425 {
 426     enum xkb_key_latch_state latch = filter->priv;
 427
 428     if (direction == XKB_KEY_DOWN && latch == LATCH_PENDING) {
 429         /* If this is a new keypress and we're awaiting our single latched
 430          * keypress, then either break the latch if any random key is pressed,
 431          * or promote it to a lock or plain base set if it's the same
 432          * modifier. */
 433         const union xkb_action *action = xkb_key_get_action(state, key);
 434         if (action->type == ACTION_TYPE_MOD_LATCH &&
 435             action->mods.flags == filter->action.mods.flags &&
 436             action->mods.mods.mask == filter->action.mods.mods.mask) {
 437             filter->action = *action;
 438             if (filter->action.mods.flags & ACTION_LATCH_TO_LOCK) {
 439                 filter->action.type = ACTION_TYPE_MOD_LOCK;
 440                 filter->func = xkb_filter_mod_lock_func;
 441                 state->components.locked_mods |= filter->action.mods.mods.mask;
 442             }
 443             else {
 444                 filter->action.type = ACTION_TYPE_MOD_SET;
 445                 filter->func = xkb_filter_mod_set_func;
 446                 state->set_mods = filter->action.mods.mods.mask;
 447             }
 448             filter->key = key;
 449             state->components.latched_mods &= ~filter->action.mods.mods.mask;
 450             /* XXX beep beep! */
 451             return false;
 452         }
 453         else if (xkb_action_breaks_latch(action)) {
 454             /* XXX: This may be totally broken, we might need to break the
 455              *      latch in the next run after this press? */
 456             state->components.latched_mods &= ~filter->action.mods.mods.mask;
 457             filter->func = NULL;
 458             return true;
 459         }
 460     }
 461     else if (direction == XKB_KEY_UP && key == filter->key) {
 462         /* Our key got released.  If we've set it to clear locks, and we
 463          * currently have the same modifiers locked, then release them and
 464          * don't actually latch.  Else we've actually hit the latching
 465          * stage, so set PENDING and move our modifier from base to
 466          * latched. */
 467         if (latch == NO_LATCH ||
 468             ((filter->action.mods.flags & ACTION_LOCK_CLEAR) &&
 469              (state->components.locked_mods & filter->action.mods.mods.mask) ==
 470              filter->action.mods.mods.mask)) {
 471             /* XXX: We might be a bit overenthusiastic about clearing
 472              *      mods other filters have set here? */
 473             if (latch == LATCH_PENDING)
 474                 state->components.latched_mods &=
 475                     ~filter->action.mods.mods.mask;
 476             else
 477                 state->clear_mods = filter->action.mods.mods.mask;
 478             state->components.locked_mods &= ~filter->action.mods.mods.mask;
 479             filter->func = NULL;
 480         }
 481         else {
 482             latch = LATCH_PENDING;
 483             state->clear_mods = filter->action.mods.mods.mask;
 484             state->components.latched_mods |= filter->action.mods.mods.mask;
 485             /* XXX beep beep! */
 486         }
 487     }
 488     else if (direction == XKB_KEY_DOWN && latch == LATCH_KEY_DOWN) {
 489         /* Someone's pressed another key while we've still got the latching
 490          * key held down, so keep the base modifier state active (from
 491          * xkb_filter_mod_latch_new), but don't trip the latch, just clear
 492          * it as soon as the modifier gets released. */
 493         latch = NO_LATCH;
 494     }
 495
 496     filter->priv = latch;
 497
 498     return true;
 499 }
 500
 501 static void
 502 xkb_filter_mod_latch_new(struct xkb_state *state, struct xkb_filter *filter)
 503 {
 504     filter->priv = LATCH_KEY_DOWN;
 505     state->set_mods = filter->action.mods.mods.mask;
 506 }
 507
 508 static const struct {
 509     void (*new)(struct xkb_state *state, struct xkb_filter *filter);
 510     bool (*func)(struct xkb_state *state, struct xkb_filter *filter,
 511                  const struct xkb_key *key, enum xkb_key_direction direction);
 512 } filter_action_funcs[_ACTION_TYPE_NUM_ENTRIES] = {
 513     [ACTION_TYPE_MOD_SET]    = { xkb_filter_mod_set_new,
 514                                  xkb_filter_mod_set_func },
 515     [ACTION_TYPE_MOD_LATCH]  = { xkb_filter_mod_latch_new,
 516                                  xkb_filter_mod_latch_func },
 517     [ACTION_TYPE_MOD_LOCK]   = { xkb_filter_mod_lock_new,
 518                                  xkb_filter_mod_lock_func },
 519     [ACTION_TYPE_GROUP_SET]  = { xkb_filter_group_set_new,
 520                                  xkb_filter_group_set_func },
 521     [ACTION_TYPE_GROUP_LOCK] = { xkb_filter_group_lock_new,
 522                                  xkb_filter_group_lock_func },
 523 };
 524
 525 /**
 526  * Applies any relevant filters to the key, first from the list of filters
 527  * that are currently active, then if no filter has claimed the key, possibly
 528  * apply a new filter from the key action.
 529  */
 530 static void
 531 xkb_filter_apply_all(struct xkb_state *state,
 532                      const struct xkb_key *key,
 533                      enum xkb_key_direction direction)
 534 {
 535     struct xkb_filter *filter;
 536     const union xkb_action *action;
 537     bool send = true;
 538
 539     /* First run through all the currently active filters and see if any of
 540      * them have claimed this event. */
 541     darray_foreach(filter, state->filters) {
 542         if (!filter->func)
 543             continue;
 544         send = filter->func(state, filter, key, direction) && send;
 545     }
 546
 547     if (!send || direction == XKB_KEY_UP)
 548         return;
 549
 550     action = xkb_key_get_action(state, key);
 551
 552     /*
 553      * It's possible for the keymap to set action->type explicitly, like so:
 554      *     interpret XF86_Next_VMode {
 555      *         action = Private(type=0x86, data="+VMode");
 556      *     };
 557      * We don't handle those.
 558      */
 559     if (action->type >= _ACTION_TYPE_NUM_ENTRIES)
 560         return;
 561
 562     if (!filter_action_funcs[action->type].new)
 563         return;
 564
 565     filter = xkb_filter_new(state);
 566     if (!filter)
 567         return; /* WSGO */
 568
 569     filter->key = key;
 570     filter->func = filter_action_funcs[action->type].func;
 571     filter->action = *action;
 572     filter_action_funcs[action->type].new(state, filter);
 573 }
 574
 575 XKB_EXPORT struct xkb_state *
 576 xkb_state_new(struct xkb_keymap *keymap)
 577 {
 578     struct xkb_state *ret;
 579
 580     ret = calloc(sizeof(*ret), 1);
 581     if (!ret)
 582         return NULL;
 583
 584     ret->refcnt = 1;
 585     ret->keymap = xkb_keymap_ref(keymap);
 586
 587     return ret;
 588 }
 589
 590 XKB_EXPORT struct xkb_state *
 591 xkb_state_ref(struct xkb_state *state)
 592 {
 593     state->refcnt++;
 594     return state;
 595 }
 596
 597 XKB_EXPORT void
 598 xkb_state_unref(struct xkb_state *state)
 599 {
 600     if (!state || --state->refcnt > 0)
 601         return;
 602
 603     xkb_keymap_unref(state->keymap);
 604     darray_free(state->filters);
 605     free(state);
 606 }
 607
 608 XKB_EXPORT struct xkb_keymap *
 609 xkb_state_get_keymap(struct xkb_state *state)
 610 {
 611     return state->keymap;
 612 }
 613
 614 /**
 615  * Update the LED state to match the rest of the xkb_state.
 616  */
 617 static void
 618 xkb_state_led_update_all(struct xkb_state *state)
 619 {
 620     xkb_led_index_t idx;
 621     const struct xkb_led *led;
 622
 623     state->components.leds = 0;
 624
 625     xkb_leds_enumerate(idx, led, state->keymap) {
 626         xkb_mod_mask_t mod_mask = 0;
 627         xkb_layout_mask_t group_mask = 0;
 628
 629         if (led->which_mods != 0 && led->mods.mask != 0) {
 630             if (led->which_mods & XKB_STATE_MODS_EFFECTIVE)
 631                 mod_mask |= state->components.mods;
 632             if (led->which_mods & XKB_STATE_MODS_DEPRESSED)
 633                 mod_mask |= state->components.base_mods;
 634             if (led->which_mods & XKB_STATE_MODS_LATCHED)
 635                 mod_mask |= state->components.latched_mods;
 636             if (led->which_mods & XKB_STATE_MODS_LOCKED)
 637                 mod_mask |= state->components.locked_mods;
 638
 639             if (led->mods.mask & mod_mask) {
 640                 state->components.leds |= (1u << idx);
 641                 continue;
 642             }
 643         }
 644
 645         if (led->which_groups != 0 && led->groups != 0) {
 646             if (led->which_groups & XKB_STATE_LAYOUT_EFFECTIVE)
 647                 group_mask |= (1u << state->components.group);
 648             if (led->which_groups & XKB_STATE_LAYOUT_DEPRESSED)
 649                 group_mask |= (1u << state->components.base_group);
 650             if (led->which_groups & XKB_STATE_LAYOUT_LATCHED)
 651                 group_mask |= (1u << state->components.latched_group);
 652             if (led->which_groups & XKB_STATE_LAYOUT_LOCKED)
 653                 group_mask |= (1u << state->components.locked_group);
 654
 655             if (led->groups & group_mask) {
 656                 state->components.leds |= (1u << idx);
 657                 continue;
 658             }
 659         }
 660
 661         if (led->ctrls & state->keymap->enabled_ctrls) {
 662             state->components.leds |= (1u << idx);
 663             continue;
 664         }
 665     }
 666 }
 667
 668 /**
 669  * Calculates the derived state (effective mods/group and LEDs) from an
 670  * up-to-date xkb_state.
 671  */
 672 static void
 673 xkb_state_update_derived(struct xkb_state *state)
 674 {
 675     xkb_layout_index_t wrapped;
 676
 677     state->components.mods = (state->components.base_mods |
 678                               state->components.latched_mods |
 679                               state->components.locked_mods);
 680
 681     /* TODO: Use groups_wrap control instead of always RANGE_WRAP. */
 682
 683     wrapped = XkbWrapGroupIntoRange(state->components.locked_group,
 684                                     state->keymap->num_groups,
 685                                     RANGE_WRAP, 0);
 686     state->components.locked_group =
 687         (wrapped == XKB_LAYOUT_INVALID ? 0 : wrapped);
 688
 689     wrapped = XkbWrapGroupIntoRange(state->components.base_group +
 690                                     state->components.latched_group +
 691                                     state->components.locked_group,
 692                                     state->keymap->num_groups,
 693                                     RANGE_WRAP, 0);
 694     state->components.group =
 695         (wrapped == XKB_LAYOUT_INVALID ? 0 : wrapped);
 696
 697     xkb_state_led_update_all(state);
 698 }
 699
 700 static enum xkb_state_component
 701 get_state_component_changes(const struct state_components *a,
 702                             const struct state_components *b)
 703 {
 704     xkb_mod_mask_t mask = 0;
 705
 706     if (a->group != b->group)
 707         mask |= XKB_STATE_LAYOUT_EFFECTIVE;
 708     if (a->base_group != b->base_group)
 709         mask |= XKB_STATE_LAYOUT_DEPRESSED;
 710     if (a->latched_group != b->latched_group)
 711         mask |= XKB_STATE_LAYOUT_LATCHED;
 712     if (a->locked_group != b->locked_group)
 713         mask |= XKB_STATE_LAYOUT_LOCKED;
 714     if (a->mods != b->mods)
 715         mask |= XKB_STATE_MODS_EFFECTIVE;
 716     if (a->base_mods != b->base_mods)
 717         mask |= XKB_STATE_MODS_DEPRESSED;
 718     if (a->latched_mods != b->latched_mods)
 719         mask |= XKB_STATE_MODS_LATCHED;
 720     if (a->locked_mods != b->locked_mods)
 721         mask |= XKB_STATE_MODS_LOCKED;
 722     if (a->leds != b->leds)
 723         mask |= XKB_STATE_LEDS;
 724
 725     return mask;
 726 }
 727
 728 /**
 729  * Given a particular key event, updates the state structure to reflect the
 730  * new modifiers.
 731  */
 732 XKB_EXPORT enum xkb_state_component
 733 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t kc,
 734                      enum xkb_key_direction direction)
 735 {
 736     xkb_mod_index_t i;
 737     xkb_mod_mask_t bit;
 738     struct state_components prev_components;
 739     const struct xkb_key *key = XkbKey(state->keymap, kc);
 740
 741     if (!key)
 742         return 0;
 743
 744     prev_components = state->components;
 745
 746     state->set_mods = 0;
 747     state->clear_mods = 0;
 748
 749     xkb_filter_apply_all(state, key, direction);
 750
 751     for (i = 0, bit = 1; state->set_mods; i++, bit <<= 1) {
 752         if (state->set_mods & bit) {
 753             state->mod_key_count[i]++;
 754             state->components.base_mods |= bit;
 755             state->set_mods &= ~bit;
 756         }
 757     }
 758
 759     for (i = 0, bit = 1; state->clear_mods; i++, bit <<= 1) {
 760         if (state->clear_mods & bit) {
 761             state->mod_key_count[i]--;
 762             if (state->mod_key_count[i] <= 0) {
 763                 state->components.base_mods &= ~bit;
 764                 state->mod_key_count[i] = 0;
 765             }
 766             state->clear_mods &= ~bit;
 767         }
 768     }
 769
 770     xkb_state_update_derived(state);
 771
 772     return get_state_component_changes(&prev_components, &state->components);
 773 }
 774
 775 /**
 776  * Updates the state from a set of explicit masks as gained from
 777  * xkb_state_serialize_mods and xkb_state_serialize_groups.  As noted in the
 778  * documentation for these functions in xkbcommon.h, this round-trip is
 779  * lossy, and should only be used to update a slave state mirroring the
 780  * master, e.g. in a client/server window system.
 781  */
 782 XKB_EXPORT enum xkb_state_component
 783 xkb_state_update_mask(struct xkb_state *state,
 784                       xkb_mod_mask_t base_mods,
 785                       xkb_mod_mask_t latched_mods,
 786                       xkb_mod_mask_t locked_mods,
 787                       xkb_layout_index_t base_group,
 788                       xkb_layout_index_t latched_group,
 789                       xkb_layout_index_t locked_group)
 790 {
 791     struct state_components prev_components;
 792     xkb_mod_mask_t mask;
 793
 794     prev_components = state->components;
 795
 796     /* Only include modifiers which exist in the keymap. */
 797     mask = (xkb_mod_mask_t) ((1ull << xkb_keymap_num_mods(state->keymap)) - 1u);
 798
 799     state->components.base_mods = base_mods & mask;
 800     state->components.latched_mods = latched_mods & mask;
 801     state->components.locked_mods = locked_mods & mask;
 802
 803     /* Make sure the mods are fully resolved - since we get arbitrary
 804      * input, they might not be.
 805      *
 806      * It might seem more reasonable to do this only for components.mods
 807      * in xkb_state_update_derived(), rather than for each component
 808      * seperately.  That would allow to distinguish between "really"
 809      * depressed mods (would be in MODS_DEPRESSED) and indirectly
 810      * depressed to to a mapping (would only be in MODS_EFFECTIVE).
 811      * However, the traditional behavior of xkb_state_update_key() is that
 812      * if a vmod is depressed, its mappings are depressed with it; so we're
 813      * expected to do the same here.  Also, LEDs (usually) look if a real
 814      * mod is locked, not just effective; otherwise it won't be lit.
 815      *
 816      * We OR here because mod_mask_get_effective() drops vmods. */
 817     state->components.base_mods |=
 818         mod_mask_get_effective(state->keymap, state->components.base_mods);
 819     state->components.latched_mods |=
 820         mod_mask_get_effective(state->keymap, state->components.latched_mods);
 821     state->components.locked_mods |=
 822         mod_mask_get_effective(state->keymap, state->components.locked_mods);
 823
 824     state->components.base_group = base_group;
 825     state->components.latched_group = latched_group;
 826     state->components.locked_group = locked_group;
 827
 828     xkb_state_update_derived(state);
 829
 830     return get_state_component_changes(&prev_components, &state->components);
 831 }
 832
 833 /**
 834  * Provides the symbols to use for the given key and state.  Returns the
 835  * number of symbols pointed to in syms_out.
 836  */
 837 XKB_EXPORT int
 838 xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t kc,
 839                        const xkb_keysym_t **syms_out)
 840 {
 841     xkb_layout_index_t layout;
 842     xkb_level_index_t level;
 843
 844     layout = xkb_state_key_get_layout(state, kc);
 845     if (layout == XKB_LAYOUT_INVALID)
 846         goto err;
 847
 848     level = xkb_state_key_get_level(state, kc, layout);
 849     if (level == XKB_LEVEL_INVALID)
 850         goto err;
 851
 852     return xkb_keymap_key_get_syms_by_level(state->keymap, kc, layout, level,
 853                                             syms_out);
 854
 855 err:
 856     *syms_out = NULL;
 857     return 0;
 858 }
 859
 860 /*
 861  * http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Lock_Modifier
 862  */
 863 static bool
 864 should_do_caps_transformation(struct xkb_state *state, xkb_keycode_t kc)
 865 {
 866     xkb_mod_index_t caps =
 867         xkb_keymap_mod_get_index(state->keymap, XKB_MOD_NAME_CAPS);
 868
 869     return
 870         xkb_state_mod_index_is_active(state, caps, XKB_STATE_MODS_EFFECTIVE) > 0 &&
 871         xkb_state_mod_index_is_consumed(state, kc, caps) == 0;
 872 }
 873
 874 /*
 875  * http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier
 876  */
 877 static bool
 878 should_do_ctrl_transformation(struct xkb_state *state, xkb_keycode_t kc)
 879 {
 880     xkb_mod_index_t ctrl =
 881         xkb_keymap_mod_get_index(state->keymap, XKB_MOD_NAME_CTRL);
 882
 883     return
 884         xkb_state_mod_index_is_active(state, ctrl, XKB_STATE_MODS_EFFECTIVE) > 0 &&
 885         xkb_state_mod_index_is_consumed(state, kc, ctrl) == 0;
 886 }
 887
 888 /* Verbatim from libX11:src/xkb/XKBBind.c */
 889 static char
 890 XkbToControl(char ch)
 891 {
 892     char c = ch;
 893
 894     if ((c >= '@' && c < '\177') || c == ' ')
 895         c &= 0x1F;
 896     else if (c == '2')
 897         c = '\000';
 898     else if (c >= '3' && c <= '7')
 899         c -= ('3' - '\033');
 900     else if (c == '8')
 901         c = '\177';
 902     else if (c == '/')
 903         c = '_' & 0x1F;
 904     return c;
 905 }
 906
 907 /**
 908  * Provides either exactly one symbol, or XKB_KEY_NoSymbol.
 909  */
 910 XKB_EXPORT xkb_keysym_t
 911 xkb_state_key_get_one_sym(struct xkb_state *state, xkb_keycode_t kc)
 912 {
 913     const xkb_keysym_t *syms;
 914     xkb_keysym_t sym;
 915     int num_syms;
 916
 917     num_syms = xkb_state_key_get_syms(state, kc, &syms);
 918     if (num_syms != 1)
 919         return XKB_KEY_NoSymbol;
 920
 921     sym = syms[0];
 922
 923     if (should_do_caps_transformation(state, kc))
 924         sym = xkb_keysym_to_upper(sym);
 925
 926     return sym;
 927 }
 928
 929 /*
 930  * The caps and ctrl transformations require some special handling,
 931  * so we cannot simply use xkb_state_get_one_sym() for them.
 932  * In particular, if Control is set, we must try very hard to find
 933  * some layout in which the keysym is ASCII and thus can be (maybe)
 934  * converted to a control character. libX11 allows to disable this
 935  * behavior with the XkbLC_ControlFallback (see XkbSetXlibControls(3)),
 936  * but it is enabled by default, yippee.
 937  */
 938 static xkb_keysym_t
 939 get_one_sym_for_string(struct xkb_state *state, xkb_keycode_t kc)
 940 {
 941     xkb_level_index_t level;
 942     xkb_layout_index_t layout, num_layouts;
 943     const xkb_keysym_t *syms;
 944     int nsyms;
 945     xkb_keysym_t sym;
 946
 947     layout = xkb_state_key_get_layout(state, kc);
 948     num_layouts = xkb_keymap_num_layouts_for_key(state->keymap, kc);
 949     level = xkb_state_key_get_level(state, kc, layout);
 950     if (layout == XKB_LAYOUT_INVALID || num_layouts == 0 ||
 951         level == XKB_LEVEL_INVALID)
 952         return XKB_KEY_NoSymbol;
 953
 954     nsyms = xkb_keymap_key_get_syms_by_level(state->keymap, kc,
 955                                              layout, level, &syms);
 956     if (nsyms != 1)
 957         return XKB_KEY_NoSymbol;
 958     sym = syms[0];
 959
 960     if (should_do_ctrl_transformation(state, kc) && sym > 127u) {
 961         for (xkb_layout_index_t i = 0; i < num_layouts; i++) {
 962             level = xkb_state_key_get_level(state, kc, i);
 963             if (level == XKB_LEVEL_INVALID)
 964                 continue;
 965
 966             nsyms = xkb_keymap_key_get_syms_by_level(state->keymap, kc,
 967                                                      i, level, &syms);
 968             if (nsyms == 1 && syms[0] <= 127u) {
 969                 sym = syms[0];
 970                 break;
 971             }
 972         }
 973     }
 974
 975     if (should_do_caps_transformation(state, kc)) {
 976         sym = xkb_keysym_to_upper(sym);
 977     }
 978
 979     return sym;
 980 }
 981
 982 XKB_EXPORT int
 983 xkb_state_key_get_utf8(struct xkb_state *state, xkb_keycode_t kc,
 984                        char *buffer, size_t size)
 985 {
 986     xkb_keysym_t sym;
 987     const xkb_keysym_t *syms;
 988     int nsyms;
 989     int offset;
 990     char tmp[7];
 991
 992     sym = get_one_sym_for_string(state, kc);
 993     if (sym != XKB_KEY_NoSymbol) {
 994         nsyms = 1; syms = &sym;
 995     }
 996     else {
 997         nsyms = xkb_state_key_get_syms(state, kc, &syms);
 998     }
 999
1000     /* Make sure not to truncate in the middle of a UTF-8 sequence. */
1001     offset = 0;
1002     for (int i = 0; i < nsyms; i++) {
1003         int ret = xkb_keysym_to_utf8(syms[i], tmp, sizeof(tmp));
1004         if (ret <= 0)
1005             goto err_bad;
1006
1007         ret--;
1008         if ((size_t) (offset + ret) <= size)
1009             memcpy(buffer + offset, tmp, ret);
1010         offset += ret;
1011     }
1012
1013     if ((size_t) offset >= size)
1014         goto err_trunc;
1015     buffer[offset] = '\0';
1016
1017     if (!is_valid_utf8(buffer, offset))
1018         goto err_bad;
1019
1020     if (offset == 1 && (unsigned int) buffer[0] <= 127u &&
1021         should_do_ctrl_transformation(state, kc))
1022         buffer[0] = XkbToControl(buffer[0]);
1023
1024     return offset;
1025
1026 err_trunc:
1027     if (size > 0)
1028         buffer[size - 1] = '\0';
1029     return offset;
1030
1031 err_bad:
1032     if (size > 0)
1033         buffer[0] = '\0';
1034     return 0;
1035 }
1036
1037 XKB_EXPORT uint32_t
1038 xkb_state_key_get_utf32(struct xkb_state *state, xkb_keycode_t kc)
1039 {
1040     xkb_keysym_t sym;
1041     uint32_t cp;
1042
1043     sym = get_one_sym_for_string(state, kc);
1044     cp = xkb_keysym_to_utf32(sym);
1045
1046     if (cp <= 127u && should_do_ctrl_transformation(state, kc))
1047         cp = (uint32_t) XkbToControl((char) cp);
1048
1049     return cp;
1050 }
1051
1052 /**
1053  * Serialises the requested modifier state into an xkb_mod_mask_t, with all
1054  * the same disclaimers as in xkb_state_update_mask.
1055  */
1056 XKB_EXPORT xkb_mod_mask_t
1057 xkb_state_serialize_mods(struct xkb_state *state,
1058                          enum xkb_state_component type)
1059 {
1060     xkb_mod_mask_t ret = 0;
1061
1062     if (type & XKB_STATE_MODS_EFFECTIVE)
1063         return state->components.mods;
1064
1065     if (type & XKB_STATE_MODS_DEPRESSED)
1066         ret |= state->components.base_mods;
1067     if (type & XKB_STATE_MODS_LATCHED)
1068         ret |= state->components.latched_mods;
1069     if (type & XKB_STATE_MODS_LOCKED)
1070         ret |= state->components.locked_mods;
1071
1072     return ret;
1073 }
1074
1075 /**
1076  * Serialises the requested group state, with all the same disclaimers as
1077  * in xkb_state_update_mask.
1078  */
1079 XKB_EXPORT xkb_layout_index_t
1080 xkb_state_serialize_layout(struct xkb_state *state,
1081                            enum xkb_state_component type)
1082 {
1083     xkb_layout_index_t ret = 0;
1084
1085     if (type & XKB_STATE_LAYOUT_EFFECTIVE)
1086         return state->components.group;
1087
1088     if (type & XKB_STATE_LAYOUT_DEPRESSED)
1089         ret += state->components.base_group;
1090     if (type & XKB_STATE_LAYOUT_LATCHED)
1091         ret += state->components.latched_group;
1092     if (type & XKB_STATE_LAYOUT_LOCKED)
1093         ret += state->components.locked_group;
1094
1095     return ret;
1096 }
1097
1098 /**
1099  * Gets a modifier mask and returns the resolved effective mask; this
1100  * is needed because some modifiers can also map to other modifiers, e.g.
1101  * the "NumLock" modifier usually also sets the "Mod2" modifier.
1102  */
1103 xkb_mod_mask_t
1104 mod_mask_get_effective(struct xkb_keymap *keymap, xkb_mod_mask_t mods)
1105 {
1106     const struct xkb_mod *mod;
1107     xkb_mod_index_t i;
1108     xkb_mod_mask_t mask;
1109
1110     /* The effective mask is only real mods for now. */
1111     mask = mods & MOD_REAL_MASK_ALL;
1112
1113     xkb_mods_enumerate(i, mod, &keymap->mods)
1114         if (mods & (1u << i))
1115             mask |= mod->mapping;
1116
1117     return mask;
1118 }
1119
1120 /**
1121  * Returns 1 if the given modifier is active with the specified type(s), 0 if
1122  * not, or -1 if the modifier is invalid.
1123  */
1124 XKB_EXPORT int
1125 xkb_state_mod_index_is_active(struct xkb_state *state,
1126                               xkb_mod_index_t idx,
1127                               enum xkb_state_component type)
1128 {
1129     if (idx >= xkb_keymap_num_mods(state->keymap))
1130         return -1;
1131
1132     return !!(xkb_state_serialize_mods(state, type) & (1u << idx));
1133 }
1134
1135 /**
1136  * Helper function for xkb_state_mod_indices_are_active and
1137  * xkb_state_mod_names_are_active.
1138  */
1139 static int
1140 match_mod_masks(struct xkb_state *state,
1141                 enum xkb_state_component type,
1142                 enum xkb_state_match match,
1143                 xkb_mod_mask_t wanted)
1144 {
1145     xkb_mod_mask_t active = xkb_state_serialize_mods(state, type);
1146
1147     if (!(match & XKB_STATE_MATCH_NON_EXCLUSIVE) && (active & ~wanted))
1148         return 0;
1149
1150     if (match & XKB_STATE_MATCH_ANY)
1151         return !!(active & wanted);
1152     else
1153         return (active & wanted) == wanted;
1154
1155     return 0;
1156 }
1157
1158 /**
1159  * Returns 1 if the modifiers are active with the specified type(s), 0 if
1160  * not, or -1 if any of the modifiers are invalid.
1161  */
1162 XKB_EXPORT int
1163 xkb_state_mod_indices_are_active(struct xkb_state *state,
1164                                  enum xkb_state_component type,
1165                                  enum xkb_state_match match,
1166                                  ...)
1167 {
1168     va_list ap;
1169     xkb_mod_mask_t wanted = 0;
1170     int ret = 0;
1171     xkb_mod_index_t num_mods = xkb_keymap_num_mods(state->keymap);
1172
1173     va_start(ap, match);
1174     while (1) {
1175         xkb_mod_index_t idx = va_arg(ap, xkb_mod_index_t);
1176         if (idx == XKB_MOD_INVALID)
1177             break;
1178         if (idx >= num_mods) {
1179             ret = -1;
1180             break;
1181         }
1182         wanted |= (1u << idx);
1183     }
1184     va_end(ap);
1185
1186     if (ret == -1)
1187         return ret;
1188
1189     return match_mod_masks(state, type, match, wanted);
1190 }
1191
1192 /**
1193  * Returns 1 if the given modifier is active with the specified type(s), 0 if
1194  * not, or -1 if the modifier is invalid.
1195  */
1196 XKB_EXPORT int
1197 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
1198                              enum xkb_state_component type)
1199 {
1200     xkb_mod_index_t idx = xkb_keymap_mod_get_index(state->keymap, name);
1201
1202     if (idx == XKB_MOD_INVALID)
1203         return -1;
1204
1205     return xkb_state_mod_index_is_active(state, idx, type);
1206 }
1207
1208 /**
1209  * Returns 1 if the modifiers are active with the specified type(s), 0 if
1210  * not, or -1 if any of the modifiers are invalid.
1211  */
1212 XKB_EXPORT ATTR_NULL_SENTINEL int
1213 xkb_state_mod_names_are_active(struct xkb_state *state,
1214                                enum xkb_state_component type,
1215                                enum xkb_state_match match,
1216                                ...)
1217 {
1218     va_list ap;
1219     xkb_mod_mask_t wanted = 0;
1220     int ret = 0;
1221
1222     va_start(ap, match);
1223     while (1) {
1224         xkb_mod_index_t idx;
1225         const char *str = va_arg(ap, const char *);
1226         if (str == NULL)
1227             break;
1228         idx = xkb_keymap_mod_get_index(state->keymap, str);
1229         if (idx == XKB_MOD_INVALID) {
1230             ret = -1;
1231             break;
1232         }
1233         wanted |= (1u << idx);
1234     }
1235     va_end(ap);
1236
1237     if (ret == -1)
1238         return ret;
1239
1240     return match_mod_masks(state, type, match, wanted);
1241 }
1242
1243 /**
1244  * Returns 1 if the given group is active with the specified type(s), 0 if
1245  * not, or -1 if the group is invalid.
1246  */
1247 XKB_EXPORT int
1248 xkb_state_layout_index_is_active(struct xkb_state *state,
1249                                 xkb_layout_index_t idx,
1250                                 enum xkb_state_component type)
1251 {
1252     int ret = 0;
1253
1254     if (idx >= state->keymap->num_groups)
1255         return -1;
1256
1257     if (type & XKB_STATE_LAYOUT_EFFECTIVE)
1258         ret |= (state->components.group == idx);
1259     if (type & XKB_STATE_LAYOUT_DEPRESSED)
1260         ret |= (state->components.base_group == (int32_t) idx);
1261     if (type & XKB_STATE_LAYOUT_LATCHED)
1262         ret |= (state->components.latched_group == (int32_t) idx);
1263     if (type & XKB_STATE_LAYOUT_LOCKED)
1264         ret |= (state->components.locked_group == (int32_t) idx);
1265
1266     return ret;
1267 }
1268
1269 /**
1270  * Returns 1 if the given modifier is active with the specified type(s), 0 if
1271  * not, or -1 if the modifier is invalid.
1272  */
1273 XKB_EXPORT int
1274 xkb_state_layout_name_is_active(struct xkb_state *state, const char *name,
1275                                 enum xkb_state_component type)
1276 {
1277     xkb_layout_index_t idx = xkb_keymap_layout_get_index(state->keymap, name);
1278
1279     if (idx == XKB_LAYOUT_INVALID)
1280         return -1;
1281
1282     return xkb_state_layout_index_is_active(state, idx, type);
1283 }
1284
1285 /**
1286  * Returns 1 if the given LED is active, 0 if not, or -1 if the LED is invalid.
1287  */
1288 XKB_EXPORT int
1289 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx)
1290 {
1291     if (idx >= state->keymap->num_leds ||
1292         state->keymap->leds[idx].name == XKB_ATOM_NONE)
1293         return -1;
1294
1295     return !!(state->components.leds & (1u << idx));
1296 }
1297
1298 /**
1299  * Returns 1 if the given LED is active, 0 if not, or -1 if the LED is invalid.
1300  */
1301 XKB_EXPORT int
1302 xkb_state_led_name_is_active(struct xkb_state *state, const char *name)
1303 {
1304     xkb_led_index_t idx = xkb_keymap_led_get_index(state->keymap, name);
1305
1306     if (idx == XKB_LED_INVALID)
1307         return -1;
1308
1309     return xkb_state_led_index_is_active(state, idx);
1310 }
1311
1312 static xkb_mod_mask_t
1313 key_get_consumed(struct xkb_state *state, const struct xkb_key *key)
1314 {
1315     const struct xkb_key_type *type;
1316     const struct xkb_key_type_entry *entry;
1317     xkb_mod_mask_t preserve;
1318     xkb_layout_index_t group;
1319
1320     group = xkb_state_key_get_layout(state, key->keycode);
1321     if (group == XKB_LAYOUT_INVALID)
1322         return 0;
1323
1324     type = key->groups[group].type;
1325
1326     entry = get_entry_for_key_state(state, key, group);
1327     if (entry)
1328         preserve = entry->preserve.mask;
1329     else
1330         preserve = 0;
1331
1332     return type->mods.mask & ~preserve;
1333 }
1334
1335 /**
1336  * Tests to see if a modifier is used up by our translation of a
1337  * keycode to keysyms, taking note of the current modifier state and
1338  * the appropriate key type's preserve information, if any. This allows
1339  * the user to mask out the modifier in later processing of the
1340  * modifiers, e.g. when implementing hot keys or accelerators.
1341  *
1342  * See also, for example:
1343  * - XkbTranslateKeyCode(3), mod_rtrn return value, from libX11.
1344  * - gdk_keymap_translate_keyboard_state, consumed_modifiers return value,
1345  *   from gtk+.
1346  */
1347 XKB_EXPORT int
1348 xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t kc,
1349                                 xkb_mod_index_t idx)
1350 {
1351     const struct xkb_key *key = XkbKey(state->keymap, kc);
1352
1353     if (!key || idx >= xkb_keymap_num_mods(state->keymap))
1354         return -1;
1355
1356     return !!((1u << idx) & key_get_consumed(state, key));
1357 }
1358
1359 /**
1360  * Calculates which modifiers should be consumed during key processing,
1361  * and returns the mask with all these modifiers removed.  e.g. if
1362  * given a state of Alt and Shift active for a two-level alphabetic
1363  * key containing plus and equal on the first and second level
1364  * respectively, will return a mask of only Alt, as Shift has been
1365  * consumed by the type handling.
1366  */
1367 XKB_EXPORT xkb_mod_mask_t
1368 xkb_state_mod_mask_remove_consumed(struct xkb_state *state, xkb_keycode_t kc,
1369                                    xkb_mod_mask_t mask)
1370 {
1371     const struct xkb_key *key = XkbKey(state->keymap, kc);
1372
1373     if (!key)
1374         return 0;
1375
1376     return mask & ~key_get_consumed(state, key);
1377 }
1378
1379 XKB_EXPORT xkb_mod_mask_t
1380 xkb_state_key_get_consumed_mods(struct xkb_state *state, xkb_keycode_t kc)
1381 {
1382     const struct xkb_key *key = XkbKey(state->keymap, kc);
1383
1384     if (!key)
1385         return 0;
1386
1387     return key_get_consumed(state, key);
1388 }