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 libxkbcommon does not distribute a dataset itself, other than for testing
  16 purposes.  The most common dataset is xkeyboard-config, as used by all
  17 current distributions for their X11 XKB data.  More information on
  18 xkeyboard-config is available here:
  19     http://www.freedesktop.org/wiki/Software/XKeyboardConfig
  20
  21 ## Quick Guide
  22
  23 See [Quick Guide](doc/quick-guide.md).
  24
  25 ## API
  26
  27 While xkbcommon's API is somewhat derived from the classic XKB API as found
  28 in X11/extensions/XKB.h and friends, it has been substantially reworked to
  29 expose fewer internal details to clients.  The supported API is available
  30 in the xkbcommon/xkbcommon-*.h files.  Additional support is provided for
  31 X11 (XCB) clients, in the xkbcommon-x11 library, xkbcommon/xkbcommon-x11.h.
  32
  33 The xkbcommon API and ABI are stable. We will attempt to not break ABI during
  34 a minor release series, so applications written against 0.1.0 should be
  35 completely compatible with 0.5.3, but not necessarily with 1.0.0.  However, new
  36 symbols may be introduced in any release.  Thus, anyone packaging xkbcommon
  37 should make sure any package depending on it depends on a release greater than
  38 or equal to the version it was built against (or earlier, if it doesn't use
  39 any newly-introduced symbols), but less than the next major release.
  40
  41 ## Relation to X11
  42
  43 Relative to the XKB 1.1 specification implemented in current X servers,
  44 xkbcommon has removed support for some parts of the specification which
  45 introduced unnecessary complications.  Many of these removals were in fact
  46 not implemented, or half-implemented at best, as well as being totally
  47 unused in the standard dataset.
  48
  49 Notable removals:
  50 - geometry support
  51   + there were very few geometry definitions available, and while
  52     xkbcommon was responsible for parsing this insanely complex format,
  53     it never actually did anything with it
  54   + hopefully someone will develop a companion library which supports
  55     keyboard geometries in a more useful format
  56 - KcCGST (keycodes/compat/geometry/symbols/types) API
  57   + use RMLVO instead; KcCGST is now an implementation detail
  58   + including pre-defined keymap files
  59 - XKM support
  60   + may come in an optional X11 support/compatibility library
  61 - around half of the interpret actions
  62   + pointer device, message and redirect actions in particular
  63 - non-virtual modifiers
  64   + core and virtual modifiers have been collapsed into the same
  65     namespace, with a 'significant' flag that largely parallels the
  66     core/virtual split
  67 - radio groups
  68   + completely unused in current keymaps, never fully implemented
  69 - overlays
  70   + almost completely unused in current keymaps
  71 - key behaviors
  72   + used to implement radio groups and overlays, and to deal with things
  73     like keys that physically lock; unused in current keymaps
  74 - indicator behaviours such as LED-controls-key
  75   + the only supported LED behaviour is key-controls-LED; again this
  76     was never really used in current keymaps
  77
  78 Notable additions:
  79 - 32-bit keycodes
  80 - extended number of modifiers
  81 - extended number of groups
  82 - multiple keysyms per level
  83   + this requires incompatible dataset changes, such that X11 would
  84     not be able to parse these
  85
  86 ## Development
  87
  88 An extremely rudimentary homepage can be found at
  89     http://xkbcommon.org
  90
  91 xkbcommon is maintained in git at
  92     https://github.com/xkbcommon/libxkbcommon
  93
  94 Patches are always welcome, and may be sent to either
  95     <xorg-devel@lists.x.org> or <wayland-devel@lists.freedesktop.org>
  96
  97 Bugs are also welcome, and may be reported either at
  98     Bugzilla https://bugs.freedesktop.org/describecomponents.cgi?product=libxkbcommon
  99 or
 100     Github https://github.com/xkbcommon/libxkbcommon/issues
 101
 102 The maintainers are
 103 - Daniel Stone <daniel@fooishbar.org>
 104 - Ran Benita <ran234@gmail.com>
 105
 106 ## Credits
 107
 108 Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
 109 off the ground initially.