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