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  * Copyright © 2009 Daniel Stone
  56  *
  57  * Permission is hereby granted, free of charge, to any person obtaining a
  58  * copy of this software and associated documentation files (the "Software"),
  59  * to deal in the Software without restriction, including without limitation
  60  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  61  * and/or sell copies of the Software, and to permit persons to whom the
  62  * Software is furnished to do so, subject to the following conditions:
  63  *
  64  * The above copyright notice and this permission notice (including the next
  65  * paragraph) shall be included in all copies or substantial portions of the
  66  * Software.
  67  *
  68  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  69  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  70  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  71  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  72  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  73  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  74  * DEALINGS IN THE SOFTWARE.
  75  *
  76  * Author: Daniel Stone <daniel@fooishbar.org>
  77  */
  78
  79
  80 #ifndef _XKBCOMMON_H_
  81 #define _XKBCOMMON_H_
  82
  83 #include <stdint.h>
  84 #include <stdio.h>
  85 #include <X11/Xfuncproto.h>
  86 #include <X11/extensions/XKB.h>
  87
  88 typedef uint32_t xkb_keycode_t;
  89 typedef uint32_t xkb_keysym_t;
  90 typedef uint32_t xkb_mod_index_t;
  91 typedef uint32_t xkb_mod_mask_t;
  92 typedef uint32_t xkb_group_index_t;
  93 typedef uint32_t xkb_led_index_t;
  94
  95 #define XKB_MOD_INVALID                 (0xffffffff)
  96 #define XKB_GROUP_INVALID               (0xffffffff)
  97 #define XKB_KEYCODE_INVALID             (0xffffffff)
  98 #define XKB_LED_INVALID                 (0xffffffff)
  99
 100 #define XKB_KEYSYM_NO_SYMBOL            0
 101
 102 #define XKB_KEYCODE_MAX                 (0xffffffff - 1)
 103 #define xkb_keycode_is_legal_ext(kc)    (kc <= XKB_KEYCODE_MAX)
 104 #define xkb_keycode_is_legal_x11(kc)    (kc <= XKB_KEYCODE_MAX)
 105 #define xkb_keymap_keycode_range_is_legal(xkb) \
 106     (xkb->max_key_code > 0 && \
 107      xkb->max_key_code > xkb->min_key_code && \
 108      xkb_keycode_is_legal_ext(xkb->min_key_code) && \
 109      xkb_keycode_is_legal_ext(xkb->max_key_code))
 110
 111
 112 /**
 113  * Names to compile a keymap with, also known as RMLVO.  These names together
 114  * should be the primary identifier for a keymap.
 115  */
 116 struct xkb_rule_names {
 117     char *rules;
 118     char *model;
 119     char *layout;
 120     char *variant;
 121     char *options;
 122 };
 123
 124 /**
 125  * Legacy names for the components of an XKB keymap, also known as KcCGST.
 126  * This is only used in deprecated entrypoints which might be removed or
 127  * shuffled off to a support library.
 128  */
 129 struct xkb_component_names {
 130     char *keymap;
 131     char *keycodes;
 132     char *types;
 133     char *compat;
 134     char *symbols;
 135 };
 136
 137 /**
 138  * Opaque context object; may only be created, accessed, manipulated and
 139  * destroyed through the xkb_context_*() API.
 140  */
 141 struct xkb_context;
 142
 143 /**
 144  * Opaque keymap object; may only be created, accessed, manipulated and
 145  * destroyed through the xkb_state_*() API.
 146  */
 147 struct xkb_keymap;
 148
 149 /**
 150  * Opaque state object; may only be created, accessed, manipulated and
 151  * destroyed through the xkb_state_*() API.
 152  */
 153 struct xkb_state;
 154
 155 _XFUNCPROTOBEGIN
 156
 157 /*
 158  * Canonicalises component names by prepending the relevant component from
 159  * 'old' to the one in 'names' when the latter has a leading '+' or '|', and
 160  * by replacing a '%' with the relevant component, e.g.:
 161  *
 162  * names        old           output
 163  * ------------------------------------------
 164  * +bar         foo           foo+bar
 165  * |quux        baz           baz|quux
 166  * foo+%|baz    bar           foo+bar|baz
 167  *
 168  * If a component in names needs to be modified, the existing value will be
 169  * free()d, and a new one allocated with malloc().
 170  */
 171 _X_EXPORT extern void
 172 xkb_canonicalise_components(struct xkb_component_names *names,
 173                             const struct xkb_component_names *old);
 174
 175 /*
 176  * Converts a keysym to a string; will return unknown Unicode codepoints
 177  * as "Ua1b2", and other unknown keysyms as "0xabcd1234".
 178  */
 179 _X_EXPORT extern void
 180 xkb_keysym_to_string(xkb_keysym_t ks, char *buffer, size_t size);
 181
 182 /*
 183  * See xkb_keysym_to_string comments: this function will accept any string
 184  * from that function.
 185  */
 186 _X_EXPORT extern xkb_keysym_t
 187 xkb_string_to_keysym(const char *s);
 188
 189 /**
 190  * @defgroup ctx XKB contexts
 191  * Every keymap compilation request must have an XKB context associated with
 192  * it.  The context keeps around state such as the include path.
 193  *
 194  * @{
 195  */
 196
 197 /**
 198  * Returns a new XKB context, or NULL on failure.  If successful, the caller
 199  * holds a reference on the context, and must free it when finished with
 200  * xkb_context_unref().
 201  */
 202 _X_EXPORT struct xkb_context *
 203 xkb_context_new(void);
 204
 205 /**
 206  * Appends a new entry to the include path used for keymap compilation.
 207  * Returns 1 on success, or 0 if the include path could not be added or is
 208  * inaccessible.
 209  */
 210 _X_EXPORT int
 211 xkb_context_include_path_append(struct xkb_context *context, const char *path);
 212
 213 /**
 214  * Appends the default include paths to the context's current include path.
 215  * Returns 1 on success, or 0 if the primary include path could not be
 216  * added.
 217  */
 218 _X_EXPORT int
 219 xkb_context_include_path_append_default(struct xkb_context *context);
 220
 221 /**
 222  * Removes all entries from the context's include path, and inserts the
 223  * default paths.  Returns 1 on success, or 0 if the primary include path
 224  * could not be added.
 225  */
 226 _X_EXPORT int
 227 xkb_context_include_path_reset_defaults(struct xkb_context *context);
 228
 229 /**
 230  * Removes all entries from the context's include path.
 231  */
 232 _X_EXPORT void
 233 xkb_context_include_path_clear(struct xkb_context *context);
 234
 235 /**
 236  * Returns the number of include paths currently active in the context.
 237  */
 238 _X_EXPORT unsigned int
 239 xkb_context_num_include_paths(struct xkb_context *context);
 240
 241 /**
 242  * Returns the include path at the specified index within the context.
 243  */
 244 _X_EXPORT const char *
 245 xkb_context_include_path_get(struct xkb_context *context, unsigned int index);
 246
 247 /**
 248  * Takes a new reference on an XKB context.
 249  */
 250 _X_EXPORT struct xkb_context *
 251 xkb_context_ref(struct xkb_context *context);
 252
 253 /**
 254  * Releases a reference on an XKB context, and possibly frees it.
 255  */
 256 _X_EXPORT void
 257 xkb_context_unref(struct xkb_context *context);
 258
 259 /** @} */
 260
 261 /**
 262  * @defgroup map Keymap management
 263  * These utility functions allow you to create and deallocate XKB keymaps.
 264  *
 265  * @{
 266  */
 267
 268 /**
 269  * The primary keymap entry point: creates a new XKB keymap from a set of
 270  * RMLVO (Rules + Model + Layout + Variant + Option) names.
 271  *
 272  * You should almost certainly be using this and nothing else to create
 273  * keymaps.
 274  */
 275 _X_EXPORT extern struct xkb_keymap *
 276 xkb_map_new_from_names(struct xkb_context *context,
 277                        const struct xkb_rule_names *names);
 278
 279 /**
 280  * Deprecated entrypoint for legacy users who need to be able to compile
 281  * XKB keymaps by KcCGST (Keycodes + Compat + Geometry + Symbols + Types)
 282  * names.
 283  *
 284  * You should not use this unless you are the X server.  This entrypoint
 285  * may well disappear in future releases.  Please, please, don't use it.
 286  *
 287  * Geometry will be ignored since xkbcommon does not support it in any way.
 288  */
 289 _X_EXPORT extern struct xkb_keymap *
 290 xkb_map_new_from_kccgst(struct xkb_context *context,
 291                         const struct xkb_component_names *kccgst);
 292
 293 enum xkb_keymap_format {
 294     /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
 295     XKB_KEYMAP_FORMAT_TEXT_V1 = 1,
 296 };
 297
 298 /**
 299  * Creates an XKB keymap from a full text XKB keymap passed into the
 300  * file descriptor.
 301  */
 302 _X_EXPORT extern struct xkb_keymap *
 303 xkb_map_new_from_fd(struct xkb_context *context,
 304                     int fd, enum xkb_keymap_format format);
 305
 306 /**
 307  * Creates an XKB keymap from a full text XKB keymap serialised into one
 308  * enormous string.
 309  */
 310 _X_EXPORT extern struct xkb_keymap *
 311 xkb_map_new_from_string(struct xkb_context *context,
 312                         const char *string,
 313                         enum xkb_keymap_format format);
 314
 315 /**
 316  * Takes a new reference on a keymap.
 317  */
 318 _X_EXPORT extern struct xkb_keymap *
 319 xkb_map_ref(struct xkb_keymap *xkb);
 320
 321 /**
 322  * Releases a reference on a keymap.
 323  */
 324 _X_EXPORT extern void
 325 xkb_map_unref(struct xkb_keymap *xkb);
 326
 327 /** @} */
 328
 329 /**
 330  * @defgroup components XKB state components
 331  * Allows enumeration of state components such as modifiers and groups within
 332  * the current keymap.
 333  *
 334  * @{
 335  */
 336
 337 /**
 338  * Returns the number of modifiers active in the keymap.
 339  */
 340 _X_EXPORT xkb_mod_index_t
 341 xkb_map_num_mods(struct xkb_keymap *xkb);
 342
 343 /**
 344  * Returns the name of the modifier specified by 'idx', or NULL if invalid.
 345  */
 346 _X_EXPORT const char *
 347 xkb_map_mod_get_name(struct xkb_keymap *xkb, xkb_mod_index_t idx);
 348
 349 /**
 350  * Returns the index of the modifier specified by 'name', or XKB_MOD_INVALID.
 351  */
 352 _X_EXPORT xkb_mod_index_t
 353 xkb_map_mod_get_index(struct xkb_keymap *xkb, const char *name);
 354
 355 /**
 356  * Returns the number of groups active in the keymap.
 357  */
 358 _X_EXPORT xkb_group_index_t
 359 xkb_map_num_groups(struct xkb_keymap *xkb);
 360
 361 /**
 362  * Returns the name of the group specified by 'idx', or NULL if invalid.
 363  */
 364 _X_EXPORT const char *
 365 xkb_map_group_get_name(struct xkb_keymap *xkb, xkb_group_index_t idx);
 366
 367 /**
 368  * Returns the index of the group specified by 'name', or XKB_GROUP_INVALID.
 369  */
 370 _X_EXPORT xkb_group_index_t
 371 xkb_map_group_get_index(struct xkb_keymap *xkb, const char *name);
 372
 373 /**
 374  * Returns the number of groups active for the specified key.
 375  */
 376 _X_EXPORT xkb_group_index_t
 377 xkb_key_num_groups(struct xkb_keymap *xkb, xkb_keycode_t key);
 378
 379 /**
 380  * Returns the number of LEDs in the given map.
 381  */
 382 _X_EXPORT xkb_led_index_t
 383 xkb_map_num_leds(struct xkb_keymap *xkb);
 384
 385 /**
 386  * Returns the name of the LED specified by 'idx', or NULL if invalid.
 387  */
 388 _X_EXPORT const char *
 389 xkb_map_led_get_name(struct xkb_keymap *xkb, xkb_led_index_t idx);
 390
 391 /**
 392  * Returns the index of the LED specified by 'name', or XKB_LED_INVALID.
 393  */
 394 _X_EXPORT xkb_led_index_t
 395 xkb_map_led_get_index(struct xkb_keymap *xkb, const char *name);
 396
 397 /** @} */
 398
 399 /**
 400  * @defgroup state XKB state objects
 401  * Creation, destruction and manipulation of keyboard state objects,
 402  * representing modifier and group state.
 403  *
 404  * @{
 405  */
 406
 407 /**
 408  * Returns a new XKB state object for use with the given keymap, or NULL on
 409  * failure.
 410  */
 411 _X_EXPORT struct xkb_state *
 412 xkb_state_new(struct xkb_keymap *xkb);
 413
 414 /**
 415  * Takes a new reference on a state object.
 416  */
 417 _X_EXPORT struct xkb_state *
 418 xkb_state_ref(struct xkb_state *state);
 419
 420 /**
 421  * Unrefs and potentially deallocates a state object; the caller must not
 422  * use the state object after calling this.
 423  */
 424 _X_EXPORT void
 425 xkb_state_unref(struct xkb_state *state);
 426
 427 enum xkb_key_direction {
 428     XKB_KEY_UP,
 429     XKB_KEY_DOWN,
 430 };
 431
 432 /**
 433  * Updates a state object to reflect the given key being pressed or released.
 434  */
 435 _X_EXPORT void
 436 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
 437                      enum xkb_key_direction direction);
 438
 439 /**
 440  * Gives the symbols obtained from pressing a particular key with the given
 441  * state.  *syms_out will be set to point to an array of keysyms, with the
 442  * return value being the number of symbols in *syms_out.  If the return
 443  * value is 0, *syms_out will be set to NULL, as there are no symbols produced
 444  * by this event.
 445  *
 446  * This should be called before xkb_state_update_key.
 447  */
 448 _X_EXPORT unsigned int
 449 xkb_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
 450                  xkb_keysym_t **syms_out);
 451
 452 /**
 453  * Modifier and group types for state objects.  This enum is bitmaskable,
 454  * e.g. (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED) is valid to exclude
 455  * locked modifiers.
 456  */
 457 enum xkb_state_component {
 458     /** A key holding this modifier or group is currently physically
 459      *  depressed; also known as 'base'. */
 460     XKB_STATE_DEPRESSED = (1 << 0),
 461     /** Modifier or group is latched, i.e. will be unset after the next
 462      *  non-modifier key press. */
 463     XKB_STATE_LATCHED = (1 << 1),
 464     /** Modifier or group is locked, i.e. will be unset after the key
 465      *  provoking the lock has been pressed again. */
 466     XKB_STATE_LOCKED = (1 << 2),
 467     /** Combinatination of depressed, latched, and locked. */
 468     XKB_STATE_EFFECTIVE =
 469         (XKB_STATE_DEPRESSED | XKB_STATE_LATCHED | XKB_STATE_LOCKED),
 470 };
 471
 472 /**
 473  * Updates a state object from a set of explicit masks.  This entrypoint is
 474  * really only for window systems and the like, where a master process
 475  * holds an xkb_state, then serialises it over a wire protocol, and clients
 476  * then use the serialisation to feed in to their own xkb_state.
 477  *
 478  * All parameters must always be passed, or the resulting state may be
 479  * incoherent.
 480  *
 481  * The serialisation is lossy and will not survive round trips; it must only
 482  * be used to feed slave state objects, and must not be used to update the
 483  * master state.
 484  *
 485  * Please do not use this unless you fit the description above.
 486  */
 487 _X_EXPORT void
 488 xkb_state_update_mask(struct xkb_state *state,
 489                       xkb_mod_mask_t base_mods,
 490                       xkb_mod_mask_t latched_mods,
 491                       xkb_mod_mask_t locked_mods,
 492                       xkb_group_index_t base_group,
 493                       xkb_group_index_t latched_group,
 494                       xkb_group_index_t locked_group);
 495
 496 /**
 497  * The counterpart to xkb_state_update_mask, to be used on the server side
 498  * of serialisation.  Returns a xkb_mod_mask_t representing the given
 499  * component(s) of the state.
 500  *
 501  * This function should not be used in regular clients; please use the
 502  * xkb_state_mod_*_is_active or xkb_state_foreach_active_mod API instead.
 503  *
 504  * Can return NULL on failure.
 505  */
 506 _X_EXPORT xkb_mod_mask_t
 507 xkb_state_serialise_mods(struct xkb_state *state,
 508                          enum xkb_state_component component);
 509
 510 /**
 511  * The group equivalent of xkb_state_serialise_mods: please see its
 512  * documentation.
 513  */
 514 _X_EXPORT xkb_group_index_t
 515 xkb_state_serialise_group(struct xkb_state *state,
 516                           enum xkb_state_component component);
 517
 518 /**
 519  * Returns 1 if the modifier specified by 'name' is active in the manner
 520  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 521  * exist in the current map.
 522  */
 523 _X_EXPORT int
 524 xkb_state_mod_name_is_active(struct xkb_state *state, const char *name,
 525                              enum xkb_state_component type);
 526
 527 /**
 528  * Returns 1 if the modifier specified by 'idx' is active in the manner
 529  * specified by 'type', 0 if it is unset, or -1 if the modifier does not
 530  * exist in the current map.
 531  */
 532 _X_EXPORT int
 533 xkb_state_mod_index_is_active(struct xkb_state *state, xkb_mod_index_t idx,
 534                               enum xkb_state_component type);
 535
 536 /**
 537  * Returns 1 if the group specified by 'name' is active in the manner
 538  * specified by 'type', 0 if it is unset, or -1 if the group does not
 539  * exist in the current map.
 540  */
 541 _X_EXPORT int
 542 xkb_state_group_name_is_active(struct xkb_state *state, const char *name,
 543                                enum xkb_state_component type);
 544
 545 /**
 546  * Returns 1 if the group specified by 'idx' is active in the manner
 547  * specified by 'type', 0 if it is unset, or -1 if the group does not
 548  * exist in the current map.
 549  */
 550 _X_EXPORT int
 551 xkb_state_group_index_is_active(struct xkb_state *state, xkb_group_index_t idx,
 552                                 enum xkb_state_component type);
 553
 554 /**
 555  * Returns 1 if the LED specified by 'name' is active, 0 if it is unset, or
 556  * -1 if the LED does not exist in the current map.
 557  */
 558 _X_EXPORT int
 559 xkb_state_led_name_is_active(struct xkb_state *state, const char *name);
 560
 561 /**
 562  * Returns 1 if the LED specified by 'idx' is active, 0 if it is unset, or
 563  * -1 if the LED does not exist in the current map.
 564  */
 565 _X_EXPORT int
 566 xkb_state_led_index_is_active(struct xkb_state *state, xkb_led_index_t idx);
 567
 568 /** @} */
 569
 570 _XFUNCPROTOEND
 571
 572 #endif /* _XKBCOMMON_H_ */