include/xkbcommon/xkbcommon.h

   1 /*
   2 Copyright 1985, 1987, 1990, 1998  The Open Group
   3 Copyright 2008  Dan Nicholson
   4
   5 Permission is hereby granted, free of charge, to any person obtaining a
   6 copy of this software and associated documentation files (the "Software"),
   7 to deal in the Software without restriction, including without limitation
   8 the rights to use, copy, modify, merge, publish, distribute, sublicense,
   9 and/or sell copies of the Software, and to permit persons to whom the
  10 Software is furnished to do so, subject to the following conditions:
  11
  12 The above copyright notice and this permission notice shall be included in
  13 all copies or substantial portions of the Software.
  14
  15 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18 AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  19 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  20 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21
  22 Except as contained in this notice, the names of the authors or their
  23 institutions shall not be used in advertising or otherwise to promote the
  24 sale, use or other dealings in this Software without prior written
  25 authorization from the authors.
  26 */
  27
  28 /************************************************************
  29 Copyright (c) 1993 by Silicon Graphics Computer Systems, Inc.
  30
  31 Permission to use, copy, modify, and distribute this
  32 software and its documentation for any purpose and without
  33 fee is hereby granted, provided that the above copyright
  34 notice appear in all copies and that both that copyright
  35 notice and this permission notice appear in supporting
  36 documentation, and that the name of Silicon Graphics not be
  37 used in advertising or publicity pertaining to distribution
  38 of the software without specific prior written permission.
  39 Silicon Graphics makes no representation about the suitability
  40 of this software for any purpose. It is provided "as is"
  41 without any express or implied warranty.
  42
  43 SILICON GRAPHICS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
  44 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  45 AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SILICON
  46 GRAPHICS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  47 DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  48 DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  49 OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION  WITH
  50 THE USE OR PERFORMANCE OF THIS SOFTWARE.
  51
  52 ********************************************************/
  53
  54
  55 #ifndef _XKBCOMMON_H_
  56 #define _XKBCOMMON_H_
  57
  58 #include <stdint.h>
  59 #include <stdio.h>
  60 #include <X11/Xfuncproto.h>
  61 #include <X11/extensions/XKB.h>
  62
  63 typedef uint32_t xkb_keycode_t;
  64 typedef uint32_t xkb_keysym_t;
  65 typedef uint32_t xkb_mod_index_t;
  66 typedef uint32_t xkb_group_index_t;
  67 typedef uint32_t xkb_led_index_t;
  68
  69 #define XKB_MOD_INVALID                 (0xffffffff)
  70 #define XKB_GROUP_INVALID               (0xffffffff)
  71 #define XKB_KEYCODE_INVALID             (0xffffffff)
  72 #define XKB_LED_INVALID                 (0xffffffff)
  73
  74 #define XKB_KEYCODE_MAX                 (0xffffffff - 1)
  75 #define xkb_keycode_is_legal_ext(kc)    (kc <= XKB_KEYCODE_MAX)
  76 #define xkb_keycode_is_legal_x11(kc)    (kc <= XKB_KEYCODE_MAX)
  77 #define xkb_keymap_keycode_range_is_legal(xkb) \
  78     (xkb->max_key_code > 0 && \
  79      xkb->max_key_code > xkb->min_key_code && \
  80      xkb_keycode_is_legal_ext(xkb->min_key_code) && \
  81      xkb_keycode_is_legal_ext(xkb->max_key_code))
  82
  83 /* Duplicate the modifier mask defines so libxkcommon can be used
  84  * without X.h */
  85 #define XKB_COMMON_SHIFT_MASK           (1 << 0)
  86 #define XKB_COMMON_LOCK_MASK            (1 << 1)
  87 #define XKB_COMMON_CONTROL_MASK         (1 << 2)
  88 #define XKB_COMMON_MOD1_MASK            (1 << 3)
  89 #define XKB_COMMON_MOD2_MASK            (1 << 4)
  90 #define XKB_COMMON_MOD3_MASK            (1 << 5)
  91 #define XKB_COMMON_MOD4_MASK            (1 << 6)
  92 #define XKB_COMMON_MOD5_MASK            (1 << 7)
  93
  94
  95 struct xkb_rule_names {
  96     const char *  rules;
  97     const char *  model;
  98     const char *  layout;
  99     const char *  variant;
 100     const char *  options;
 101 };
 102
 103 struct xkb_any_action {
 104     uint8_t   type;
 105     uint8_t   data[7];
 106 };
 107
 108 struct xkb_mod_action {
 109     uint8_t         type;
 110     uint8_t         flags;
 111     uint8_t         mask;
 112     uint8_t         real_mods;
 113     uint16_t        vmods;
 114 };
 115
 116 struct xkb_group_action {
 117     uint8_t         type;
 118     uint8_t         flags;
 119     int16_t         group;
 120 };
 121
 122 struct xkb_iso_action {
 123     uint8_t         type;
 124     uint8_t         flags;
 125     uint8_t         mask;
 126     uint8_t         real_mods;
 127     uint8_t         group;
 128     uint8_t         affect;
 129     uint16_t        vmods;
 130 };
 131
 132 struct xkb_controls_action {
 133     uint8_t         type;
 134     uint8_t         flags;
 135     uint32_t        ctrls;
 136 };
 137
 138 struct xkb_device_button_action {
 139     uint8_t         type;
 140     uint8_t         flags;
 141     uint8_t         count;
 142     uint8_t         button;
 143     uint8_t         device;
 144 };
 145
 146 struct xkb_device_valuator_action {
 147     uint8_t         type;
 148     uint8_t         device;
 149     uint8_t         v1_what;
 150     uint8_t         v1_index;
 151     uint8_t         v1_value;
 152     uint8_t         v2_what;
 153     uint8_t         v2_index;
 154     uint8_t         v2_value;
 155 };
 156
 157 struct xkb_pointer_default_action {
 158     uint8_t         type;
 159     uint8_t         flags;
 160     uint8_t         affect;
 161     uint8_t         value;
 162 };
 163
 164 struct xkb_switch_screen_action {
 165     uint8_t         type;
 166     uint8_t         flags;
 167     uint8_t         screen;
 168 };
 169
 170 struct xkb_redirect_key_action {
 171     uint8_t             type;
 172     xkb_keycode_t       new_key;
 173     uint8_t             mods_mask;
 174     uint8_t             mods;
 175     uint16_t            vmods_mask;
 176     uint16_t            vmods;
 177 };
 178
 179 struct xkb_pointer_action {
 180     uint8_t     type;
 181     uint8_t     flags;
 182     uint16_t    x;
 183     uint16_t    y;
 184 };
 185
 186 struct xkb_message_action {
 187     uint8_t     type;
 188     uint8_t     flags;
 189     uint8_t     message[6];
 190 };
 191
 192 struct xkb_pointer_button_action {
 193     uint8_t     type;
 194     uint8_t     flags;
 195     uint8_t     count;
 196     uint8_t     button;
 197 };
 198
 199 union xkb_action {
 200     struct xkb_any_action             any;
 201     struct xkb_mod_action             mods;
 202     struct xkb_group_action           group;
 203     struct xkb_iso_action             iso;
 204     struct xkb_controls_action        ctrls;
 205     struct xkb_device_button_action   devbtn;
 206     struct xkb_device_valuator_action devval;
 207     struct xkb_pointer_default_action dflt;
 208     struct xkb_switch_screen_action   screen;
 209     struct xkb_redirect_key_action    redirect; /* XXX wholly unnecessary? */
 210     struct xkb_pointer_action         ptr; /* XXX delete for DeviceValuator */
 211     struct xkb_pointer_button_action  btn; /* XXX delete for DeviceBtn */
 212     struct xkb_message_action         msg; /* XXX just delete */
 213     unsigned char                     type;
 214 };
 215
 216 struct xkb_mods {
 217         uint32_t        mask;   /* effective mods */
 218         uint32_t        vmods;
 219         uint8_t         real_mods;
 220 };
 221
 222 struct xkb_kt_map_entry {
 223         int            active;
 224         uint16_t        level;
 225         struct xkb_mods     mods;
 226 };
 227
 228 struct xkb_key_type {
 229     struct xkb_mods             mods;
 230     uint16_t                num_levels;
 231     unsigned char           map_count;
 232     struct xkb_kt_map_entry *       map;
 233     struct xkb_mods *             preserve;
 234     const char              *name;
 235     const char              **level_names;
 236 };
 237
 238 struct xkb_sym_interpret {
 239     xkb_keysym_t    sym;
 240     unsigned char   flags;
 241     unsigned char   match;
 242     uint8_t         mods;
 243     uint32_t        virtual_mod;
 244     union xkb_action act;
 245 };
 246
 247 struct xkb_compat_map {
 248     struct xkb_sym_interpret *      sym_interpret;
 249     struct xkb_mods              groups[XkbNumKbdGroups];
 250     unsigned short           num_si;
 251     unsigned short           size_si;
 252 };
 253
 254 struct xkb_sym_map {
 255         unsigned char    kt_index[XkbNumKbdGroups];
 256         unsigned char    group_info;
 257         unsigned char    width;
 258         unsigned short   offset;
 259 };
 260
 261 #define XkbNumGroups(g)                 ((g)&0x0f)
 262 #define XkbOutOfRangeGroupInfo(g)       ((g)&0xf0)
 263 #define XkbOutOfRangeGroupAction(g)     ((g)&0xc0)
 264 #define XkbOutOfRangeGroupNumber(g)     (((g)&0x30)>>4)
 265 #define XkbSetGroupInfo(g,w,n)  (((w)&0xc0)|(((n)&3)<<4)|((g)&0x0f))
 266 #define XkbSetNumGroups(g,n)    (((g)&0xf0)|((n)&0x0f))
 267
 268 struct xkb_client_map {
 269     unsigned char            size_types;
 270     unsigned char            num_types;
 271     struct xkb_key_type *           types;
 272
 273     uint32_t                 size_syms;
 274     uint32_t                 num_syms;
 275     xkb_keysym_t             *syms;
 276     struct xkb_sym_map *             key_sym_map;
 277
 278     unsigned char           *modmap;
 279 };
 280
 281 struct xkb_behavior {
 282         unsigned char   type;
 283         unsigned char   data;
 284 };
 285
 286 struct xkb_server_map {
 287     unsigned short      num_acts;
 288     unsigned short      size_acts;
 289
 290 #if defined(__cplusplus) || defined(c_plusplus)
 291     /* explicit is a C++ reserved word */
 292     unsigned char *     c_explicit;
 293 #else
 294     unsigned char *     explicit;
 295 #endif
 296
 297     union xkb_action          *acts;
 298     struct xkb_behavior         *behaviors;
 299     unsigned short      *key_acts;
 300     unsigned char       *explicits;
 301     uint32_t            vmods[XkbNumVirtualMods]; /* vmod -> mod mapping */
 302     uint32_t            *vmodmap; /* key -> vmod mapping */
 303 };
 304
 305
 306 struct xkb_indicator_map {
 307         unsigned char   flags;
 308         unsigned char   which_groups;
 309         unsigned char   groups;
 310         unsigned char   which_mods;
 311         struct xkb_mods mods;
 312         unsigned int    ctrls;
 313 };
 314
 315 struct xkb_indicator {
 316         unsigned long           phys_indicators;
 317         struct xkb_indicator_map        maps[XkbNumIndicators];
 318 };
 319
 320 struct xkb_key_name {
 321         char    name[XkbKeyNameLength];
 322 };
 323
 324 struct xkb_key_alias {
 325         char    real[XkbKeyNameLength];
 326         char    alias[XkbKeyNameLength];
 327 };
 328
 329 struct xkb_names {
 330     const char            *vmods[XkbNumVirtualMods];
 331     const char            *indicators[XkbNumIndicators];
 332     const char            *groups[XkbNumKbdGroups];
 333     struct xkb_key_name *     keys;
 334     struct xkb_key_alias *    key_aliases;
 335
 336     xkb_keycode_t     num_keys;
 337     xkb_keycode_t     num_key_aliases;
 338 };
 339
 340 struct xkb_controls {
 341         unsigned char   num_groups;
 342         unsigned char   groups_wrap;
 343         struct xkb_mods internal;
 344         struct xkb_mods ignore_lock;
 345         unsigned int    enabled_ctrls;
 346         unsigned short  repeat_delay;
 347         unsigned short  repeat_interval;
 348         unsigned short  slow_keys_delay;
 349         unsigned short  debounce_delay;
 350         unsigned short  ax_options;
 351         unsigned short  ax_timeout;
 352         unsigned short  axt_opts_mask;
 353         unsigned short  axt_opts_values;
 354         unsigned int    axt_ctrls_mask;
 355         unsigned int    axt_ctrls_values;
 356         unsigned char   *per_key_repeat;
 357 };
 358
 359 /* Common keyboard description structure */
 360 struct xkb_desc {
 361     unsigned int        refcnt;
 362     unsigned int        defined;
 363     unsigned short      flags;
 364     unsigned short      device_spec;
 365     xkb_keycode_t       min_key_code;
 366     xkb_keycode_t       max_key_code;
 367
 368     struct xkb_controls *      ctrls;
 369     struct xkb_server_map *    server;
 370     struct xkb_client_map *    map;
 371     struct xkb_indicator *     indicators;
 372     struct xkb_names *        names;
 373     struct xkb_compat_map *    compat;
 374 };
 375
 376
 377 #define XkbKeyGroupInfo(d,k)    ((d)->map->key_sym_map[k].group_info)
 378 #define XkbKeyNumGroups(d,k)    (XkbNumGroups((d)->map->key_sym_map[k].group_info))
 379 #define XkbKeyGroupWidth(d,k,g) (XkbKeyType(d,k,g)->num_levels)
 380 #define XkbKeyGroupsWidth(d,k)  ((d)->map->key_sym_map[k].width)
 381 #define XkbKeyTypeIndex(d,k,g)  ((d)->map->key_sym_map[k].kt_index[g&0x3])
 382 #define XkbKeyType(d,k,g)       (&(d)->map->types[XkbKeyTypeIndex(d,k,g)])
 383 #define XkbKeyNumSyms(d,k)      (XkbKeyGroupsWidth(d,k)*XkbKeyNumGroups(d,k))
 384 #define XkbKeySymsOffset(d,k)   ((d)->map->key_sym_map[k].offset)
 385 #define XkbKeySymsPtr(d,k)      (&(d)->map->syms[XkbKeySymsOffset(d,k)])
 386 #define XkbKeySym(d,k,n)        (XkbKeySymsPtr(d,k)[n])
 387 #define XkbKeySymEntry(d,k,sl,g) \
 388         (XkbKeySym(d,k,((XkbKeyGroupsWidth(d,k)*(g))+(sl))))
 389 #define XkbKeyHasActions(d,k)   ((d)->server->key_acts[k]!=0)
 390 #define XkbKeyNumActions(d,k)   (XkbKeyHasActions(d,k)?XkbKeyNumSyms(d,k):1)
 391 #define XkbKeyActionsPtr(d,k)   (&(d)->server->acts[(d)->server->key_acts[k]])
 392 #define XkbKeyAction(d,k,n) \
 393         (XkbKeyHasActions(d,k)?&XkbKeyActionsPtr(d,k)[n]:NULL)
 394 #define XkbKeyActionEntry(d,k,sl,g) \
 395         (XkbKeyHasActions(d,k)?\
 396                 XkbKeyAction(d,k,((XkbKeyGroupsWidth(d,k)*(g))+(sl))):NULL)
 397
 398 #define XkbKeycodeInRange(d,k)  (((k)>=(d)->min_key_code)&&\
 399                                  ((k)<=(d)->max_key_code))
 400 #define XkbNumKeys(d)           ((d)->max_key_code-(d)->min_key_code+1)
 401
 402 struct xkb_map_changes {
 403         unsigned short           changed;
 404         xkb_keycode_t            min_key_code;
 405         xkb_keycode_t            max_key_code;
 406         unsigned char            first_type;
 407         unsigned char            num_types;
 408         xkb_keycode_t            first_key_sym;
 409         xkb_keycode_t            num_key_syms;
 410         xkb_keycode_t            first_key_act;
 411         xkb_keycode_t            num_key_acts;
 412         xkb_keycode_t            first_key_behavior;
 413         xkb_keycode_t            num_key_behaviors;
 414         xkb_keycode_t            first_key_explicit;
 415         xkb_keycode_t            num_key_explicit;
 416         xkb_keycode_t            first_modmap_key;
 417         xkb_keycode_t            num_modmap_keys;
 418         xkb_keycode_t            first_vmodmap_key;
 419         xkb_keycode_t            num_vmodmap_keys;
 420         unsigned short           vmods;
 421 };
 422
 423 struct xkb_controls_changes {
 424         unsigned int             changed_ctrls;
 425         unsigned int             enabled_ctrls_changes;
 426         int                      num_groups_changed;
 427 };
 428
 429 struct xkb_indicator_changes {
 430         unsigned int             state_changes;
 431         unsigned int             map_changes;
 432 };
 433
 434 struct xkb_name_changes {
 435         unsigned int            changed;
 436         unsigned char           first_type;
 437         unsigned char           num_types;
 438         unsigned char           first_lvl;
 439         unsigned char           num_lvls;
 440         xkb_keycode_t           num_aliases;
 441         xkb_keycode_t           first_key;
 442         xkb_keycode_t           num_keys;
 443         unsigned short          changed_vmods;
 444         unsigned long           changed_indicators;
 445         unsigned char           changed_groups;
 446 };
 447
 448 struct xkb_compat_changes {
 449         unsigned char           changed_groups;
 450         unsigned short          first_si;
 451         unsigned short          num_si;
 452 };
 453
 454 struct xkb_changes {
 455         unsigned short           device_spec;
 456         unsigned short           state_changes;
 457         struct xkb_map_changes   map;
 458         struct xkb_controls_changes      ctrls;
 459         struct xkb_indicator_changes     indicators;
 460         struct xkb_name_changes  names;
 461         struct xkb_compat_changes        compat;
 462 };
 463
 464 struct xkb_component_names {
 465         char *                   keymap;
 466         char *                   keycodes;
 467         char *                   types;
 468         char *                   compat;
 469         char *                   symbols;
 470 };
 471
 472 struct xkb_component_name {
 473         unsigned short          flags;
 474         char *                  name;
 475 };
 476
 477 struct xkb_state {
 478         unsigned char   group; /* base + latched + locked */
 479         /* FIXME: Why are base + latched short and not char?? */
 480         unsigned short  base_group; /* physically ... down? */
 481         unsigned short  latched_group;
 482         unsigned char   locked_group;
 483
 484         unsigned char   mods; /* base + latched + locked */
 485         unsigned char   base_mods; /* physically down */
 486         unsigned char   latched_mods;
 487         unsigned char   locked_mods;
 488
 489         unsigned char   compat_state; /* mods + group for core state */
 490
 491         /* grab mods = all depressed and latched mods, _not_ locked mods */
 492         unsigned char   grab_mods; /* grab mods minus internal mods */
 493         unsigned char   compat_grab_mods; /* grab mods + group for core state,
 494                                              but not locked groups if
 495                                              IgnoreGroupLocks set */
 496
 497         /* effective mods = all mods (depressed, latched, locked) */
 498         unsigned char   lookup_mods; /* effective mods minus internal mods */
 499         unsigned char   compat_lookup_mods; /* effective mods + group */
 500
 501         unsigned short  ptr_buttons; /* core pointer buttons */
 502
 503         uint32_t        leds;
 504
 505         int refcnt;
 506         void *filters;
 507         int num_filters;
 508         struct xkb_desc *xkb;
 509 };
 510
 511 #define XkbStateFieldFromRec(s) XkbBuildCoreState((s)->lookup_mods,(s)->group)
 512 #define XkbGrabStateFromRec(s)  XkbBuildCoreState((s)->grab_mods,(s)->group)
 513
 514 #define XkbNumGroups(g)                 ((g)&0x0f)
 515 #define XkbOutOfRangeGroupInfo(g)       ((g)&0xf0)
 516 #define XkbOutOfRangeGroupAction(g)     ((g)&0xc0)
 517 #define XkbOutOfRangeGroupNumber(g)     (((g)&0x30)>>4)
 518 #define XkbSetNumGroups(g,n)    (((g)&0xf0)|((n)&0x0f))
 519
 520 _XFUNCPROTOBEGIN
 521
 522 /*
 523  * Canonicalises component names by prepending the relevant component from
 524  * 'old' to the one in 'names' when the latter has a leading '+' or '|', and
 525  * by replacing a '%' with the relevant component, e.g.:
 526  *
 527  * names        old           output
 528  * ------------------------------------------
 529  * +bar         foo           foo+bar
 530  * |quux        baz           baz|quux
 531  * foo+%|baz    bar           foo+bar|baz
 532  *
 533  * If a component in names needs to be modified, the existing value will be
 534  * free()d, and a new one allocated with malloc().
 535  */
 536 _X_EXPORT extern void
 537 xkb_canonicalise_components(struct xkb_component_names * names,
 538                            const struct xkb_component_names * old);
 539
 540 /*
 541  * Converts a keysym to a string; will return unknown Unicode codepoints
 542  * as "Ua1b2", and other unknown keysyms as "0xabcd1234".
 543  */
 544 _X_EXPORT extern void
 545 xkb_keysym_to_string(xkb_keysym_t ks, char *buffer, size_t size);
 546
 547 /*
 548  * See xkb_keysym_to_string comments: this function will accept any string
 549  * from that function.
 550  */
 551 _X_EXPORT extern xkb_keysym_t
 552 xkb_string_to_keysym(const char *s);
 553
 554 _X_EXPORT unsigned int
 555 xkb_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
 556                  xkb_keysym_t **syms_out);
 557
 558 /**
 559  * @defgroup map Keymap management
 560  * These utility functions allow you to create and deallocate XKB keymaps.
 561  *
 562  * @{
 563  */
 564
 565 /**
 566  * The primary keymap entry point: creates a new XKB keymap from a set of
 567  * RMLVO (Rules + Model + Layout + Variant + Option) names.
 568  *
 569  * You should almost certainly be using this and nothing else to create
 570  * keymaps.
 571  */
 572 _X_EXPORT extern struct xkb_desc *
 573 xkb_map_new_from_names(const struct xkb_rule_names *names);
 574
 575 /**
 576  * Deprecated entrypoint for legacy users who need to be able to compile
 577  * XKB keymaps by KcCGST (Keycodes + Compat + Geometry + Symbols + Types)
 578  * names.
 579  *
 580  * You should not use this unless you are the X server.  This entrypoint
 581  * may well disappear in future releases.  Please, please, don't use it.
 582  *
 583  * Geometry will be ignored since xkbcommon does not support it in any way.
 584  */
 585 _X_EXPORT extern struct xkb_desc *
 586 xkb_map_new_from_kccgst(const struct xkb_component_names *kccgst);
 587
 588 enum xkb_keymap_format {
 589     /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
 590     XKB_KEYMAP_FORMAT_TEXT_V1 = 1,
 591 };
 592
 593 /**
 594  * Creates an XKB keymap from a full text XKB keymap passed into the
 595  * file descriptor.
 596  */
 597 _X_EXPORT extern struct xkb_desc *
 598 xkb_map_new_from_fd(int fd, enum xkb_keymap_format format);
 599
 600 /**
 601  * Creates an XKB keymap from a full text XKB keymap serialised into one
 602  * enormous string.
 603  */
 604 _X_EXPORT extern struct xkb_desc *
 605 xkb_map_new_from_string(const char *string, enum xkb_keymap_format format);
 606
 607 /**
 608  * Takes a new reference on a keymap.
 609  */
 610 _X_EXPORT extern void
 611 xkb_map_ref(struct xkb_desc *xkb);
 612
 613 /**
 614  * Releases a reference on a keymap.
 615  */
 616 _X_EXPORT extern void
 617 xkb_map_unref(struct xkb_desc *xkb);
 618
 619 /** @} */
 620
 621 /**
 622  * @defgroup components XKB state components
 623  * Allows enumeration of state components such as modifiers and groups within
 624  * the current keymap.
 625  *
 626  * @{
 627  */
 628
 629 /**
 630  * Returns the number of modifiers active in the keymap.
 631  */
 632 _X_EXPORT xkb_mod_index_t
 633 xkb_map_num_mods(struct xkb_desc *xkb);
 634
 635 /**
 636  * Returns the name of the modifier specified by 'idx', or NULL if invalid.
 637  */
 638 _X_EXPORT const char *
 639 xkb_map_mod_get_name(struct xkb_desc *xkb, xkb_mod_index_t idx);
 640
 641 /**
 642  * Returns the index of the modifier specified by 'name', or XKB_MOD_INVALID.
 643  */
 644 _X_EXPORT xkb_mod_index_t
 645 xkb_map_mod_get_index(struct xkb_desc *xkb, const char *name);
 646
 647 /**
 648  * Returns the number of groups active in the keymap.
 649  */
 650 _X_EXPORT xkb_group_index_t
 651 xkb_map_num_groups(struct xkb_desc *xkb);
 652
 653 /**
 654  * Returns the name of the group specified by 'idx', or NULL if invalid.
 655  */
 656 _X_EXPORT const char *
 657 xkb_map_group_get_name(struct xkb_desc *xkb, xkb_group_index_t idx);
 658
 659 /**
 660  * Returns the index of the group specified by 'name', or XKB_GROUP_INVALID.
 661  */
 662 _X_EXPORT xkb_group_index_t
 663 xkb_map_group_get_index(struct xkb_desc *xkb, const char *name);
 664
 665 /**
 666  * Returns the number of groups active for the specified key.
 667  */
 668 _X_EXPORT xkb_group_index_t
 669 xkb_key_num_groups(struct xkb_desc *xkb, xkb_keycode_t key);
 670
 671 /**
 672  * Returns the number of LEDs in the given map.
 673  */
 674 _X_EXPORT xkb_led_index_t
 675 xkb_map_num_leds(struct xkb_desc *xkb);
 676
 677 /**
 678  * Returns the name of the LED specified by 'idx', or NULL if invalid.
 679  */
 680 _X_EXPORT const char *
 681 xkb_map_led_get_name(struct xkb_desc *xkb, xkb_led_index_t idx);
 682
 683 /**
 684  * Returns the index of the LED specified by 'name', or XKB_LED_INVALID.
 685  */
 686 _X_EXPORT xkb_led_index_t
 687 xkb_map_led_get_index(struct xkb_desc *xkb, const char *name);
 688
 689 /** @} */
 690
 691 /**
 692  * @defgroup state XKB state objects
 693  * Creation, destruction and manipulation of keyboard state objects,
 694  * representing modifier and group state.
 695  *
 696  * @{
 697  */
 698
 699 /**
 700  * Allocates a new XKB state object for use with the given keymap.
 701  */
 702 _X_EXPORT struct xkb_state *
 703 xkb_state_new(struct xkb_desc *xkb);
 704
 705 /**
 706  * Adds a reference to a state object, so it will not be freed until unref.
 707  */
 708 _X_EXPORT void
 709 xkb_state_ref(struct xkb_state *state);
 710
 711 /**
 712  * Unrefs and potentially deallocates a state object; the caller must not
 713  * use the state object after calling this.
 714  */
 715 _X_EXPORT void
 716 xkb_state_unref(struct xkb_state *state);
 717
 718 /**
 719  * Updates a state object to reflect the given key being pressed or released.
 720  */
 721 _X_EXPORT void
 722 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key, int down);
 723
 724 /**
 725  * Modifier and group types for state objects.  This enum is bitmaskable,
 726  * e.g. (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED) is valid to exclude
 727  * locked modifiers.
 728  */
 729 enum xkb_state_component {
 730     XKB_STATE_DEPRESSED = (1 << 0),
 731         /**< A key holding this modifier or group is currently physically
 732          *   depressed; also known as 'base'. */
 733     XKB_STATE_LATCHED = (1 << 1),
 734         /**< Modifier or group is latched, i.e. will be unset after the next
 735          *   non-modifier key press. */
 736     XKB_STATE_LOCKED = (1 << 2),
 737         /**< Modifier or group is locked, i.e. will be unset after the key
 738          *   provoking the lock has been pressed again. */
 739     XKB_STATE_EFFECTIVE =
 740         (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED | XKB_STATE_LOCKED),
 741         /**< Combinatination of depressed, latched, and locked. */
 742 };
 743
 744 /**
 745  * Returns 1 if the modifier specified by 'name' is active in the manner
 746  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 747  * exist in the current map.
 748  */
 749 _X_EXPORT int
 750 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
 751                              enum xkb_state_component type);
 752
 753 /**
 754  * Returns 1 if the modifier specified by 'idx' is active in the manner
 755  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 756  * exist in the current map.
 757  */
 758 _X_EXPORT int
 759 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
 760                               enum xkb_state_component type);
 761
 762 /**
 763  * Returns 1 if the group specified by 'name' is active in the manner
 764  * specified by 'type', 0 if it is unset, or -1 if the group does not
 765  * exist in the current map.
 766  */
 767 _X_EXPORT int
 768 xkb_state_group_name_is_active(struct xkb_state *state, const char *name,
 769                                enum xkb_state_component type);
 770
 771 /**
 772  * Returns 1 if the group specified by 'idx' is active in the manner
 773  * specified by 'type', 0 if it is unset, or -1 if the group does not
 774  * exist in the current map.
 775  */
 776 _X_EXPORT int
 777 xkb_state_group_index_is_active(struct xkb_state *state, xkb_group_index_t idx,
 778                                 enum xkb_state_component type);
 779
 780 /**
 781  * Returns 1 if the LED specified by 'name' is active, 0 if it is unset, or
 782  * -1 if the LED does not exist in the current map.
 783  */
 784 _X_EXPORT int
 785 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
 786
 787 /**
 788  * Returns 1 if the LED specified by 'idx' is active, 0 if it is unset, or
 789  * -1 if the LED does not exist in the current map.
 790  */
 791 _X_EXPORT int
 792 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
 793
 794 /** @} */
 795
 796 _XFUNCPROTOEND
 797
 798 #endif /* _XKBCOMMON_H_ */