120 lines
5.0 KiB
Plaintext
120 lines
5.0 KiB
Plaintext
Overview {#mainpage}
|
|
========
|
|
|
|
xkbcommon is a keymap compiler and support library which processes a
|
|
reduced subset of keymaps as defined by the XKB specification. Primarily,
|
|
a keymap is created from a set of Rules/Model/Layout/Variant/Options names,
|
|
processed through an XKB ruleset, and compiled into a struct xkb_keymap,
|
|
which is the base type for all xkbcommon operations.
|
|
|
|
From an xkb_keymap, an xkb_state object is created which holds the current
|
|
state of all modifiers, groups, LEDs, etc, relating to that keymap. All
|
|
key events must be fed into the xkb_state object using xkb_state_update_key().
|
|
Once this is done, the xkb_state object will be properly updated, and the
|
|
keysyms to use can be obtained with xkb_state_key_get_syms().
|
|
|
|
libxkbcommon does not distribute a dataset itself, other than for testing
|
|
purposes. The most common dataset is xkeyboard-config, as used by all
|
|
current distributions for their X11 XKB data. More information on
|
|
xkeyboard-config is available here:
|
|
http://www.freedesktop.org/wiki/Software/XKeyboardConfig
|
|
|
|
|
|
API
|
|
===
|
|
|
|
While xkbcommon's API is somewhat derived from the classic XKB API as found
|
|
in <X11/extensions/XKB.h> and friends, it has been substantially reworked to
|
|
expose fewer internal details to clients. The only supported API is available
|
|
in <xkbcommon/xkbcommon.h>. Any definition not in this header (including
|
|
accessing internal structures through the old macros previously available)
|
|
should be regarded as an implementation detail and is liable to change at any
|
|
time.
|
|
|
|
During its early development, xkbcommon does not promise API or ABI stability.
|
|
Regardless, we will attempt to not break ABI during a minor release series,
|
|
so applications written against 0.1.0 should be completely compatible with
|
|
0.1.3, but not necessarily with 0.2.0. However, new symbols may be introduced
|
|
in any release. Thus, anyone packaging xkbcommon should make sure any package
|
|
depending on it depends on a release greater than or equal to the version it
|
|
was built against (or earlier, if it doesn't use any newly-introduced
|
|
symbols), but less than the next major release.
|
|
|
|
xkbcommon 1.x will offer full API and ABI stability for its lifetime, with a
|
|
soname of libxkbcommon.so.1. Any ABI breaks will wait until xkbcommon 2.0,
|
|
which will be libxkbcommon.so.2.
|
|
|
|
The xkbcomp command-line tool has also been removed, although this will
|
|
likely reappear in a later release.
|
|
|
|
|
|
Relation to X11
|
|
===============
|
|
|
|
Relative to the XKB 1.1 specification implemented in current X servers,
|
|
xkbcommon has removed support for some parts of the specification which
|
|
introduced unnecessary complications. Many of these removals were in fact
|
|
not implemented, or half-implemented at best, as well as being totally
|
|
unused in the standard dataset.
|
|
|
|
Notable removals:
|
|
- geometry support
|
|
+ there were very few geometry definitions available, and while
|
|
xkbcommon was responsible for parsing this insanely complex format,
|
|
it never actually did anything with it
|
|
+ hopefully someone will develop a companion library which supports
|
|
keyboard geometries in a more useful format
|
|
- KcCGST (keycodes/compat/geometry/symbols/types) API
|
|
+ use RMLVO instead; KcCGST is now an implementation detail
|
|
+ including pre-defined keymap files
|
|
- XKM support
|
|
+ may come in an optional X11 support/compatibility library
|
|
- around half of the interpret actions
|
|
+ pointer device, message and redirect actions in particular
|
|
- non-virtual modifiers
|
|
+ core and virtual modifiers have been collapsed into the same
|
|
namespace, with a 'significant' flag that largely parallels the
|
|
core/virtual split
|
|
- radio groups
|
|
+ completely unused in current keymaps, never fully implemented
|
|
- overlays
|
|
+ almost completely unused in current keymaps
|
|
- key behaviors
|
|
+ used to implement radio groups and overlays, and to deal with things
|
|
like keys that physically lock; unused in current keymaps
|
|
- indicator behaviours such as LED-controls-key
|
|
+ the only supported LED behaviour is key-controls-LED; again this
|
|
was never really used in current keymaps
|
|
|
|
Notable additions:
|
|
- 32-bit keycodes
|
|
- extended number of modifiers
|
|
- extended number of groups
|
|
- multiple keysyms per level
|
|
+ this requires incompatible dataset changes, such that X11 would
|
|
not be able to parse these
|
|
|
|
|
|
Development
|
|
===========
|
|
|
|
An extremely rudimentary homepage can be found at:
|
|
http://xkbcommon.org
|
|
|
|
xkbcommon is maintained in git at freedesktop.org:
|
|
git://anongit.freedesktop.org/git/libxkbcommon
|
|
|
|
Patches are always welcome, and may be sent to either xorg-devel@lists.x.org,
|
|
or wayland-devel@lists.freedesktop.org. Bugs are tracked in Bugzilla at:
|
|
http://bugs.freedesktop.org
|
|
|
|
The maintainer is Daniel Stone, who can be reached at:
|
|
<daniel@fooishbar.org>
|
|
|
|
|
|
Credits
|
|
=======
|
|
|
|
Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
|
|
off the ground initially, as well as to Ran Benita for subsequent development.
|