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 ## Relation to X11
  34
  35 Relative to the XKB 1.1 specification implemented in current X servers,
  36 xkbcommon has removed support for some parts of the specification which
  37 introduced unnecessary complications.  Many of these removals were in fact
  38 not implemented, or half-implemented at best, as well as being totally
  39 unused in the standard dataset.
  40
  41 Notable removals:
  42 - geometry support
  43   + there were very few geometry definitions available, and while
  44     xkbcommon was responsible for parsing this insanely complex format,
  45     it never actually did anything with it
  46   + hopefully someone will develop a companion library which supports
  47     keyboard geometries in a more useful format
  48 - KcCGST (keycodes/compat/geometry/symbols/types) API
  49   + use RMLVO instead; KcCGST is now an implementation detail
  50   + including pre-defined keymap files
  51 - XKM support
  52   + may come in an optional X11 support/compatibility library
  53 - around half of the interpret actions
  54   + pointer device, message and redirect actions in particular
  55 - non-virtual modifiers
  56   + core and virtual modifiers have been collapsed into the same
  57     namespace, with a 'significant' flag that largely parallels the
  58     core/virtual split
  59 - radio groups
  60   + completely unused in current keymaps, never fully implemented
  61 - overlays
  62   + almost completely unused in current keymaps
  63 - key behaviors
  64   + used to implement radio groups and overlays, and to deal with things
  65     like keys that physically lock; unused in current keymaps
  66 - indicator behaviours such as LED-controls-key
  67   + the only supported LED behaviour is key-controls-LED; again this
  68     was never really used in current keymaps
  69
  70 Notable additions:
  71 - 32-bit keycodes
  72 - extended number of modifiers
  73 - extended number of groups
  74 - multiple keysyms per level
  75   + this requires incompatible dataset changes, such that X11 would
  76     not be able to parse these
  77
  78 ## Development
  79
  80 An extremely rudimentary homepage can be found at
  81     http://xkbcommon.org
  82
  83 xkbcommon is maintained in git at
  84     https://github.com/xkbcommon/libxkbcommon
  85
  86 Patches are always welcome, and may be sent to either
  87     <xorg-devel@lists.x.org> or <wayland-devel@lists.freedesktop.org>
  88
  89 Bugs are also welcome, and may be reported either at
  90     Bugzilla https://bugs.freedesktop.org/describecomponents.cgi?product=libxkbcommon
  91 or
  92     Github https://github.com/xkbcommon/libxkbcommon/issues
  93
  94 The maintainers are
  95 - Daniel Stone <daniel@fooishbar.org>
  96 - Ran Benita <ran234@gmail.com>
  97
  98 ## Credits
  99
 100 Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
 101 off the ground initially.