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 libxkbcommon'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.
  24
  25 See the [API Documentation](http://xkbcommon.org/doc/current/modules.html).
  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 See [Compatibility](doc/compat.md) notes.
  38
  39 ## Development
  40
  41 An extremely rudimentary homepage can be found at
  42     http://xkbcommon.org
  43
  44 xkbcommon is maintained in git at
  45     https://github.com/xkbcommon/libxkbcommon
  46
  47 Patches are always welcome, and may be sent to either
  48     <xorg-devel@lists.x.org> or <wayland-devel@lists.freedesktop.org>
  49
  50 Bugs are also welcome, and may be reported either at
  51     Bugzilla https://bugs.freedesktop.org/describecomponents.cgi?product=libxkbcommon
  52 or
  53     Github https://github.com/xkbcommon/libxkbcommon/issues
  54
  55 The maintainers are
  56 - Daniel Stone <daniel@fooishbar.org>
  57 - Ran Benita <ran234@gmail.com>
  58
  59 ## Credits
  60
  61 Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
  62 off the ground initially.