README.md

   1 # libxkbcommon
   2
   3 xkbcommon is a keymap compiler and support library which processes a
   4 reduced subset of keymaps as defined by the XKB specification.  Primarily,
   5 a keymap is created from a set of Rules/Model/Layout/Variant/Options names,
   6 processed through an XKB ruleset, and compiled into a struct xkb_keymap,
   7 which is the base type for all xkbcommon operations.
   8
   9 From an xkb_keymap, an xkb_state object is created which holds the current
  10 state of all modifiers, groups, LEDs, etc, relating to that keymap.  All
  11 key events must be fed into the xkb_state object using xkb_state_update_key().
  12 Once this is done, the xkb_state object will be properly updated, and the
  13 keysyms to use can be obtained with xkb_state_key_get_syms().
  14
  15 ## Quick Guide
  16
  17 See [Quick Guide](doc/quick-guide.md).
  18
  19 ## API
  20
  21 While xkbcommon's API is somewhat derived from the classic XKB API as found
  22 in X11/extensions/XKB.h and friends, it has been substantially reworked to
  23 expose fewer internal details to clients.  The supported API is available
  24 in the xkbcommon/xkbcommon-*.h files.  Additional support is provided for
  25 X11 (XCB) clients, in the xkbcommon-x11 library, xkbcommon/xkbcommon-x11.h.
  26
  27 ## Dataset
  28
  29 libxkbcommon does not distribute a keymap dataset itself, other than for
  30 testing purposes.  The most common dataset is xkeyboard-config, which is used
  31 by all current distributions for their X11 XKB data.  More information on
  32 xkeyboard-config is available here:
  33     http://www.freedesktop.org/wiki/Software/XKeyboardConfig
  34
  35 ## Relation to X11
  36
  37 Relative to the XKB 1.1 specification implemented in current X servers,
  38 xkbcommon has removed support for some parts of the specification which
  39 introduced unnecessary complications.  Many of these removals were in fact
  40 not implemented, or half-implemented at best, as well as being totally
  41 unused in the standard dataset.
  42
  43 Notable removals:
  44 - geometry support
  45   + there were very few geometry definitions available, and while
  46     xkbcommon was responsible for parsing this insanely complex format,
  47     it never actually did anything with it
  48   + hopefully someone will develop a companion library which supports
  49     keyboard geometries in a more useful format
  50 - KcCGST (keycodes/compat/geometry/symbols/types) API
  51   + use RMLVO instead; KcCGST is now an implementation detail
  52   + including pre-defined keymap files
  53 - XKM support
  54   + may come in an optional X11 support/compatibility library
  55 - around half of the interpret actions
  56   + pointer device, message and redirect actions in particular
  57 - non-virtual modifiers
  58   + core and virtual modifiers have been collapsed into the same
  59     namespace, with a 'significant' flag that largely parallels the
  60     core/virtual split
  61 - radio groups
  62   + completely unused in current keymaps, never fully implemented
  63 - overlays
  64   + almost completely unused in current keymaps
  65 - key behaviors
  66   + used to implement radio groups and overlays, and to deal with things
  67     like keys that physically lock; unused in current keymaps
  68 - indicator behaviours such as LED-controls-key
  69   + the only supported LED behaviour is key-controls-LED; again this
  70     was never really used in current keymaps
  71
  72 Notable additions:
  73 - 32-bit keycodes
  74 - extended number of modifiers
  75 - extended number of groups
  76 - multiple keysyms per level
  77   + this requires incompatible dataset changes, such that X11 would
  78     not be able to parse these
  79
  80 ## Development
  81
  82 An extremely rudimentary homepage can be found at
  83     http://xkbcommon.org
  84
  85 xkbcommon is maintained in git at
  86     https://github.com/xkbcommon/libxkbcommon
  87
  88 Patches are always welcome, and may be sent to either
  89     <xorg-devel@lists.x.org> or <wayland-devel@lists.freedesktop.org>
  90
  91 Bugs are also welcome, and may be reported either at
  92     Bugzilla https://bugs.freedesktop.org/describecomponents.cgi?product=libxkbcommon
  93 or
  94     Github https://github.com/xkbcommon/libxkbcommon/issues
  95
  96 The maintainers are
  97 - Daniel Stone <daniel@fooishbar.org>
  98 - Ran Benita <ran234@gmail.com>
  99
 100 ## Credits
 101
 102 Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
 103 off the ground initially.