.autom4te.cfg | 3
.gitignore | 1
Makefile.am | 165
NEWS | 129
README | 116
README.md | 109
configure.ac | 117
debian/changelog | 63
debian/control | 50
debian/copyright | 4
debian/libxkbcommon-x11-0.install | 3
debian/libxkbcommon-x11-0.symbols | 6
debian/libxkbcommon-x11-dev.install | 5
debian/libxkbcommon0.symbols | 8
debian/rules | 23
debian/watch | 2
doc/Doxyfile.in | 237
doc/keymap-format-text-v1.txt | 359 +
doc/quick-guide.md | 218
doc/rules-format.txt | 86
m4/ax_gcc_builtin.m4 | 168
makekeys.py | 44
src/atom.c | 137
src/atom.h | 7
src/context-priv.c | 190
src/context.c | 128
src/context.h | 75
src/darray.h | 256
src/keymap-dump.c | 688 --
src/keymap-priv.c | 123
src/keymap.c | 256
src/keymap.h | 80
src/keysym-utf.c | 94
src/keysym.c | 68
src/keysym.h | 6
src/ks_tables.h |11765 +++++++++++++++++++++--------------
src/list.h | 489 -
src/scanner-utils.h | 159
src/state.c | 538 +
src/text.c | 254
src/text.h | 2
src/utf8.c | 142
src/utf8.h | 36
src/utils.c | 107
src/utils.h | 111
src/x11/keymap.c | 1161 +++
src/x11/state.c | 71
src/x11/util.c | 215
src/x11/x11-priv.h | 54
src/xkbcomp/.gitignore | 1
src/xkbcomp/action.c | 544 -
src/xkbcomp/ast-build.c | 517 -
src/xkbcomp/ast-build.h | 72
src/xkbcomp/ast.h | 135
src/xkbcomp/compat.c | 542 -
src/xkbcomp/expr.c | 182
src/xkbcomp/include.c | 84
src/xkbcomp/include.h | 5
src/xkbcomp/keycodes.c | 611 -
src/xkbcomp/keycodes.h | 37
src/xkbcomp/keymap-dump.c | 657 +
src/xkbcomp/keymap.c | 50
src/xkbcomp/keywords.c | 348 +
src/xkbcomp/keywords.gperf | 78
src/xkbcomp/parser-priv.h | 15
src/xkbcomp/parser.y | 289
src/xkbcomp/rules.c | 488 -
src/xkbcomp/scanner.c | 207
src/xkbcomp/scanner.l | 291
src/xkbcomp/symbols.c | 390 -
src/xkbcomp/types.c | 283
src/xkbcomp/vmod.c | 63
src/xkbcomp/vmod.h | 3
src/xkbcomp/xkbcomp-priv.h | 25
src/xkbcomp/xkbcomp.c | 144
test/.gitignore | 8
test/atom.c | 181
test/bench-key-proc.c | 95
test/buffercomp.c | 90
test/common.c | 297
test/context.c | 11
test/data/compat/default | 12
test/data/compat/iso9995 | 4
test/data/keycodes/empty | 4
test/data/keycodes/evdev-xkbcommon | 1
test/data/keymaps/divide-by-zero.xkb | 6
test/data/keymaps/quartz.xkb | 1139 +++
test/data/keymaps/stringcomp.data | 3817 +++++------
test/data/keymaps/unbound-vmod.xkb | 1533 ++++
test/data/rules/base | 88
test/data/rules/evdev | 96
test/data/rules/groups | 5
test/data/symbols/altwin | 21
test/data/symbols/ca | 5
test/data/symbols/ch | 225
test/data/symbols/compose | 35
test/data/symbols/cz | 184
test/data/symbols/de | 114
test/data/symbols/empty | 4
test/data/symbols/il | 80
test/data/symbols/in | 75
test/data/symbols/inet | 4
test/data/symbols/keypad | 11
test/data/symbols/latin | 2
test/data/symbols/level3 | 40
test/data/symbols/level5 | 24
test/data/symbols/pc | 2
test/data/symbols/ru | 34
test/data/symbols/rupeesign | 5
test/data/symbols/us | 224
test/data/sync.sh | 67
test/data/types/level5 | 1
test/data/types/pc | 8
test/filecomp.c | 12
test/interactive-evdev.c | 454 +
test/interactive-x11.c | 387 +
test/interactive.c | 560 -
test/keyseq.c | 249
test/keysym.c | 34
test/log.c | 2
test/print-compiled-keymap.c | 2
test/rmlvo-to-kccgst.c | 17
test/rules-file.c | 2
test/rulescomp.c | 180
test/state.c | 341 -
test/stringcomp.c | 19
test/test.h | 42
test/utf8.c | 157
test/x11.c | 78
xkbcommon-x11-uninstalled.pc.in | 10
xkbcommon-x11.pc.in | 12
xkbcommon/xkbcommon-compat.h | 4
xkbcommon/xkbcommon-keysyms.h | 8
xkbcommon/xkbcommon-names.h | 1
xkbcommon/xkbcommon-x11.h | 174
xkbcommon/xkbcommon.h | 522 +
136 files changed, 24052 insertions(+), 12956 deletions(-)
New commits:
commit cd6f7bdf240dcfef89fd25b14116d4359e748bc9
Author: Timo Aaltonen <tjaal...@ubuntu.com>
Date: Wed Apr 9 13:41:49 2014 +0300
release to trusty
diff --git a/debian/changelog b/debian/changelog
index e2d832c..02713d5 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+libxkbcommon (0.4.1-0ubuntu1) trusty; urgency=medium
+
+ * Sync from debian git. (LP: #1303706)
+
+ -- Timo Aaltonen <tjaal...@ubuntu.com> Mon, 07 Apr 2014 12:49:38 +0300
+
libxkbcommon (0.4.1-1) UNRELEASED; urgency=medium
* New upstream release.
commit 84a8a560cb0255c5266939340824903bb97791e2
Author: Timo Aaltonen <tjaal...@ubuntu.com>
Date: Thu Apr 3 19:15:00 2014 +0300
libxkbcommon0.symbols: Added three new symbols.
diff --git a/debian/changelog b/debian/changelog
index 2ea8c04..e2d832c 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,6 +1,7 @@
libxkbcommon (0.4.1-1) UNRELEASED; urgency=medium
* New upstream release.
+ * libxkbcommon0.symbols: Added three new symbols.
-- Timo Aaltonen <tjaal...@ubuntu.com> Thu, 03 Apr 2014 19:08:26 +0300
diff --git a/debian/libxkbcommon0.symbols b/debian/libxkbcommon0.symbols
index 62a8316..8000529 100644
--- a/debian/libxkbcommon0.symbols
+++ b/debian/libxkbcommon0.symbols
@@ -67,10 +67,13 @@ libxkbcommon.so.0 libxkbcommon0 #MINVER#
xkb_state_get_map@Base 0.2.0
xkb_state_group_index_is_active@Base 0.2.0
xkb_state_group_name_is_active@Base 0.2.0
+ xkb_state_key_get_consumed_mods@Base 0.4.1
xkb_state_key_get_layout@Base 0.2.0
xkb_state_key_get_level@Base 0.2.0
xkb_state_key_get_one_sym@Base 0.2.0
xkb_state_key_get_syms@Base 0.2.0
+ xkb_state_key_get_utf32@Base 0.4.1
+ xkb_state_key_get_utf8@Base 0.4.1
xkb_state_layout_index_is_active@Base 0.2.0
xkb_state_layout_name_is_active@Base 0.2.0
xkb_state_led_index_is_active@Base 0.2.0
commit d44050e90fcf0a319d96cbfbddc839928bb35694
Author: Timo Aaltonen <tjaal...@ubuntu.com>
Date: Thu Apr 3 19:08:52 2014 +0300
update the changelog
diff --git a/debian/changelog b/debian/changelog
index 51527c4..2ea8c04 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+libxkbcommon (0.4.1-1) UNRELEASED; urgency=medium
+
+ * New upstream release.
+
+ -- Timo Aaltonen <tjaal...@ubuntu.com> Thu, 03 Apr 2014 19:08:26 +0300
+
libxkbcommon (0.4.0-1) unstable; urgency=low
* New upstream release. This introduces the new binary packages
commit b5b86b6e7a42c4d4965351f59e629a29b89d9791
Author: Ran Benita <ran...@gmail.com>
Date: Thu Mar 27 20:12:02 2014 +0200
Bump version to 0.4.1
Signed-off-by: Ran Benita <ran...@gmail.com>
diff --git a/configure.ac b/configure.ac
index b08a550..edee68b 100644
--- a/configure.ac
+++ b/configure.ac
@@ -22,7 +22,7 @@ dnl Process this file with autoconf to create configure.
# Initialize Autoconf
AC_PREREQ([2.62])
-AC_INIT([libxkbcommon], [0.4.0],
+AC_INIT([libxkbcommon], [0.4.1],
[https://bugs.freedesktop.org/enter_bug.cgi?product=libxkbcommon],
[libxkbcommon], [http://xkbcommon.org])
AC_CONFIG_SRCDIR([Makefile.am])
commit b636987cf00694abf0beff1ce229c2217f52644c
Author: Ran Benita <ran...@gmail.com>
Date: Thu Mar 27 20:11:13 2014 +0200
Update NEWS
Signed-off-by: Ran Benita <ran...@gmail.com>
diff --git a/NEWS b/NEWS
index 450b753..07ebdd9 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,46 @@
+libxkbcommon 0.4.1
+==================
+
+- Converted README to markdown and added a Quick Guide to the
+ documentation, which breezes through the most common parts of
+ xkbcommon.
+
+- Added two new functions, xkb_state_key_get_utf{8,32}(). They
+ combine the operations of xkb_state_key_get_syms() and
+ xkb_keysym_to_utf{8,32}(), and provide a nicer interface for it
+ (espcially for multiple-keysyms-per-level).
+
+- The xkb_state_key_get_utf{8,32}() functions now apply Control
+ transformation: when the Control modifier is active, the string
+ is converted to an appropriate control character.
+ This matches the behavior of libX11's XLookupString(3), and
+ required by the XKB specification:
+
http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier
+
+ https://bugs.freedesktop.org/show_bug.cgi?id=75892
+
+- The consumed modifiers for a key are now calculated similarly
+ to libX11. The previous behavior caused a bug where Shift would
+ not cancel an active Caps Lock.
+
+- Make xkbcommon-x11 work with the keymap reported by the XQuartz
+ X server.
+
+ https://bugs.freedesktop.org/show_bug.cgi?id=75798
+
+- Reduce memory usage during keymap compilation some more.
+
+- New API:
+ xkb_state_key_get_consumed_mods()
+ xkb_state_key_get_utf8()
+ xkb_state_key_get_utf32()
+
+- Deprecated API:
+ XKB_MAP_COMPILE_PLACEHOLDER, XKB_MAP_NO_FLAGS
+ use XKB_KEYMAP_NO_FLAGS instead.
+
+- Bug fixes.
+
libxkbcommon 0.4.0
==================
commit 240fa418fbf648fce508be3a7440899e338437f8
Author: Ran Benita <ran...@gmail.com>
Date: Thu Mar 27 20:58:16 2014 +0200
build: trim down generated doxygen docs
Remove the huge verbatim copies of the header files.
Signed-off-by: Ran Benita <ran...@gmail.com>
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 0c57100..39a3bbe 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -838,7 +838,7 @@ USE_HTAGS = NO
# will generate a verbatim copy of the header file for each class for
# which an include is specified. Set to NO to disable this.
-VERBATIM_HEADERS = YES
+VERBATIM_HEADERS = NO
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
commit 2a610ff4111c15adb18a8af9a1d66c5e13991bfd
Author: Ran Benita <ran...@gmail.com>
Date: Thu Mar 27 20:37:21 2014 +0200
build: add docs to EXTRA_DIST
Signed-off-by: Ran Benita <ran...@gmail.com>
diff --git a/Makefile.am b/Makefile.am
index ca5c3ff..de13dec 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -6,7 +6,11 @@ pkgconfig_DATA = xkbcommon.pc
EXTRA_DIST = \
makekeys.py \
src/xkbcomp/keywords.gperf \
- test/data
+ test/data \
+ README.md \
+ doc/quick-guide.md \
+ doc/keymap-format-text-v1.txt \
+ doc/rules-format.txt
AM_CPPFLAGS = \
-DDFLT_XKB_CONFIG_ROOT='"$(XKBCONFIGROOT)"' \
commit 5417440970f15673fbc128108245ad0697fcadc0
Author: Ran Benita <ran...@gmail.com>
Date: Thu Mar 27 17:42:20 2014 +0200
state: fix consumed modifier calculation
The current calculation is in short:
entry ? (entry->mask & ~entry->preserve) : 0
This changes it be
type->mask & ~(entry ? entry->preserve : 0)
This is what Xlib does. While less intuitive, it is actually more
correct, if you follow this deduction:
- The key group's type->mask defines which modifiers the key even cares
about. The others are completely irrelevant (and in fact they are
masked out from all sided in the level calculation). Example: NumLock
for an alphabetic key.
- The type->mask, the mods which are not masked out, are *all* relevant
(and in fact in the level calculation they must match *exactly* to the
state). These mods affect which level is chosen for the key, whether
they are active or not.
- Because the type->mask mods are all relevant, they must be considered
as consumed by the calculation *even if they are not active*.
Therefore we use type->mask instead of entry->mask.
The second change is what happens when no entry is found: return 0 or
just take preserve to be 0? Let's consider an example, the basic type
type "ALPHABETIC" {
modifiers = Shift+Lock;
map[Shift] = Level2;
map[Lock] = Level2;
level_name[Level1] = "Base";
level_name[Level2] = "Caps";
};
Suppose Shift+Lock is active - it doesn't match any entry, thus it gets
to level 0. The first interpretation would take them both to be
unconsumed, the second (new one) would take them both to be consumed.
This seems much better: Caps is active, and Shift disables it, they both
do something.
This change also fixes a pretty lousy bug (since 0.3.2), where Shift
appears to apparently *not* disable Caps. What actually happens is that
Caps is not consumed (see above) but active, thus the implicit
capitalization in get_one_sym() kicks in and capitalizes it anyway.
Reported-by: Davinder Pal Singh Bhamra
Signed-off-by: Ran Benita <ran...@gmail.com>
diff --git a/src/state.c b/src/state.c
index d130b8e..0f9ea79 100644
--- a/src/state.c
+++ b/src/state.c
@@ -1276,18 +1276,24 @@ xkb_state_led_name_is_active(struct xkb_state *state,
const char *name)
static xkb_mod_mask_t
key_get_consumed(struct xkb_state *state, const struct xkb_key *key)
{
+ const struct xkb_key_type *type;
const struct xkb_key_type_entry *entry;
+ xkb_mod_mask_t preserve;
xkb_layout_index_t group;
group = xkb_state_key_get_layout(state, key->keycode);
if (group == XKB_LAYOUT_INVALID)
return 0;
+ type = key->groups[group].type;
+
entry = get_entry_for_key_state(state, key, group);
- if (!entry)
- return 0;
+ if (entry)
+ preserve = entry->preserve.mask;
+ else
+ preserve = 0;
- return entry->mods.mask & ~entry->preserve.mask;
+ return type->mods.mask & ~preserve;
}
/**
diff --git a/test/common.c b/test/common.c
index 8b3f954..e6cd1c3 100644
--- a/test/common.c
+++ b/test/common.c
@@ -64,6 +64,7 @@ test_key_seq_va(struct xkb_keymap *keymap, va_list ap)
xkb_keysym_t keysym;
const xkb_keysym_t *syms;
+ xkb_keysym_t sym;
unsigned int nsyms, i;
char ksbuf[64];
@@ -77,6 +78,11 @@ test_key_seq_va(struct xkb_keymap *keymap, va_list ap)
op = va_arg(ap, int);
nsyms = xkb_state_key_get_syms(state, kc, &syms);
+ if (nsyms == 1) {
+ sym = xkb_state_key_get_one_sym(state, kc);
+ syms = &sym;
+ }
+
fprintf(stderr, "got %u syms for key 0x%x: [", nsyms, kc);
if (op == DOWN || op == BOTH)
diff --git a/test/state.c b/test/state.c
index 97c2bb6..2164d6b 100644
--- a/test/state.c
+++ b/test/state.c
@@ -309,17 +309,25 @@ test_repeat(struct xkb_keymap *keymap)
static void
test_consume(struct xkb_keymap *keymap)
{
- struct xkb_state *state = xkb_state_new(keymap);
- xkb_mod_index_t alt, shift;
+ struct xkb_state *state;
+ xkb_mod_index_t alt, shift, caps, ctrl, mod5;
xkb_mod_mask_t mask;
+ state = xkb_state_new(keymap);
assert(state);
alt = xkb_keymap_mod_get_index(keymap, XKB_MOD_NAME_ALT);
assert(alt != XKB_MOD_INVALID);
shift = xkb_keymap_mod_get_index(keymap, XKB_MOD_NAME_SHIFT);
assert(shift != XKB_MOD_INVALID);
+ caps = xkb_keymap_mod_get_index(keymap, XKB_MOD_NAME_CAPS);
+ assert(caps != XKB_MOD_INVALID);
+ ctrl = xkb_keymap_mod_get_index(keymap, XKB_MOD_NAME_CTRL);
+ assert(ctrl != XKB_MOD_INVALID);
+ mod5 = xkb_keymap_mod_get_index(keymap, "Mod5");
+ assert(mod5 != XKB_MOD_INVALID);
+ /* Test remove_consumed() */
xkb_state_update_key(state, KEY_LEFTALT + EVDEV_OFFSET, XKB_KEY_DOWN);
xkb_state_update_key(state, KEY_LEFTSHIFT + EVDEV_OFFSET, XKB_KEY_DOWN);
xkb_state_update_key(state, KEY_EQUAL + EVDEV_OFFSET, XKB_KEY_DOWN);
@@ -333,9 +341,56 @@ test_consume(struct xkb_keymap *keymap)
mask);
assert(mask == (1U << alt));
+ /* Test get_consumed_mods() */
mask = xkb_state_key_get_consumed_mods(state, KEY_EQUAL + EVDEV_OFFSET);
assert(mask == (1U << shift));
+ mask = xkb_state_key_get_consumed_mods(state, KEY_ESC + EVDEV_OFFSET);
+ assert(mask == 0);
+
+ xkb_state_unref(state);
+
+ /* Test is_consumed() - simple ALPHABETIC type. */
+ state = xkb_state_new(keymap);
+ assert(state);
+
+ mask = xkb_state_key_get_consumed_mods(state, KEY_A + EVDEV_OFFSET);
+ assert(mask == ((1U << shift) | (1U << caps)));
+
+ assert(xkb_state_mod_index_is_consumed(state, KEY_A + EVDEV_OFFSET, caps)
> 0);
+ assert(xkb_state_mod_index_is_consumed(state, KEY_A + EVDEV_OFFSET, shift)
> 0);
+ xkb_state_update_key(state, KEY_CAPSLOCK + EVDEV_OFFSET, XKB_KEY_DOWN);
+ xkb_state_update_key(state, KEY_CAPSLOCK + EVDEV_OFFSET, XKB_KEY_UP);
+ assert(xkb_state_mod_index_is_consumed(state, KEY_A + EVDEV_OFFSET, caps)
> 0);
+ assert(xkb_state_mod_index_is_consumed(state, KEY_A + EVDEV_OFFSET, shift)
> 0);
+ xkb_state_update_key(state, KEY_LEFTSHIFT + EVDEV_OFFSET, XKB_KEY_DOWN);
+ assert(xkb_state_mod_index_is_consumed(state, KEY_A + EVDEV_OFFSET, caps)
> 0);
+ assert(xkb_state_mod_index_is_consumed(state, KEY_A + EVDEV_OFFSET, shift)
> 0);
+ xkb_state_update_key(state, KEY_LEFTSHIFT + EVDEV_OFFSET, XKB_KEY_UP);
+ xkb_state_update_key(state, KEY_CAPSLOCK + EVDEV_OFFSET, XKB_KEY_DOWN);
+ xkb_state_update_key(state, KEY_CAPSLOCK + EVDEV_OFFSET, XKB_KEY_UP);
+ assert(xkb_state_mod_index_is_consumed(state, KEY_A + EVDEV_OFFSET, caps)
> 0);
+ assert(xkb_state_mod_index_is_consumed(state, KEY_A + EVDEV_OFFSET, shift)
> 0);
+
+ xkb_state_unref(state);
+
+ /* More complicated - CTRL+ALT */
+ state = xkb_state_new(keymap);
+
+ mask = xkb_state_key_get_consumed_mods(state, KEY_F1 + EVDEV_OFFSET);
+ assert(mask == ((1U << shift) | (1U << alt) | (1U << ctrl) | (1U <<
mod5)));
+
+ /* Shift is preserved. */
+ xkb_state_update_key(state, KEY_LEFTSHIFT + EVDEV_OFFSET, XKB_KEY_DOWN);
+ mask = xkb_state_key_get_consumed_mods(state, KEY_F1 + EVDEV_OFFSET);
+ assert(mask == ((1U << alt) | (1U << ctrl) | (1U << mod5)));
+ xkb_state_update_key(state, KEY_LEFTSHIFT + EVDEV_OFFSET, XKB_KEY_UP);
+
+ mask = xkb_state_key_get_consumed_mods(state, KEY_F1 + EVDEV_OFFSET);
+ assert(mask == ((1U << shift) | (1U << alt) | (1U << ctrl) | (1U <<
mod5)));
+
+ assert(state);
+
xkb_state_unref(state);
}
commit 806dbeac81cfc7447f0bf7b42cdf2f430c630576
Author: Ran Benita <ran...@gmail.com>
Date: Sun Mar 23 15:04:51 2014 +0200
Reformat README markdown
So that github displays it as markdown, and correctly.
Signed-off-by: Ran Benita <ran...@gmail.com>
diff --git a/README b/README
deleted file mode 100644
index 22c6b1e..0000000
--- a/README
+++ /dev/null
@@ -1,118 +0,0 @@
-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
-
-Quick Guide
-===========
-
-See [Quick Guide](doc/quick-guide.md).
-
-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 supported API is available
-in the <xkbcommon/xkbcommon-*.h> files. Additional support is provided for
-X11 (XCB) clients, in the xkbcommon-x11 library, <xkbcommon/xkbcommon-x11.h>.
-
-The xkbcommon API and ABI are stable. 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.5.3, but not necessarily with 1.0.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.
-
-
-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 github.com:
- https://github.com/xkbcommon/libxkbcommon
-
-Patches are always welcome, and may be sent to either xorg-de...@lists.x.org,
-or wayland-de...@lists.freedesktop.org.
-
-Bugs are tracked in Bugzilla at:
- https://bugs.freedesktop.org/describecomponents.cgi?product=libxkbcommon
-Or in github at:
- https://github.com/xkbcommon/libxkbcommon/issues
-
-The maintainers are Daniel Stone and Ran Benita, who can be reached at:
- <dan...@fooishbar.org>
- <ran...@gmail.com>
-
-
-Credits
-=======
-
-Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
-off the ground initially.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2627a32
--- /dev/null
+++ b/README.md
@@ -0,0 +1,109 @@
+# libxkbcommon
+
+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
+
+## Quick Guide
+
+See [Quick Guide](doc/quick-guide.md).
+
+## 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 supported API is available
+in the xkbcommon/xkbcommon-*.h files. Additional support is provided for
+X11 (XCB) clients, in the xkbcommon-x11 library, xkbcommon/xkbcommon-x11.h.
+
+The xkbcommon API and ABI are stable. 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.5.3, but not necessarily with 1.0.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.
+
+## 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
+ https://github.com/xkbcommon/libxkbcommon
+
+Patches are always welcome, and may be sent to either
+ <xorg-de...@lists.x.org> or <wayland-de...@lists.freedesktop.org>
+
+Bugs are also welcome, and may be reported either at
+ Bugzilla
https://bugs.freedesktop.org/describecomponents.cgi?product=libxkbcommon
+or
+ Github https://github.com/xkbcommon/libxkbcommon/issues
+
+The maintainers are
+- Daniel Stone <dan...@fooishbar.org>
+- Ran Benita <ran...@gmail.com>
+
+## Credits
+
+Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
+off the ground initially.
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 57b58ee..0c57100 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -655,7 +655,7 @@ WARN_LOGFILE =
# with spaces.
INPUT = @abs_top_srcdir@/xkbcommon \
- @abs_top_srcdir@/README \
+ @abs_top_srcdir@/README.md \
@abs_top_srcdir@/doc/quick-guide.md
# This tag can be used to specify the character encoding of the source files
@@ -782,7 +782,7 @@ FILTER_SOURCE_PATTERNS =
# (index.html). This can be useful if you have a project on for instance GitHub
# and want reuse the introduction page also for the doxygen output.
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = README.md
#---------------------------------------------------------------------------
# configuration options related to source browsing
commit aa3e82364249e93d05b0c3eed4b050ec5d038478
Author: Ran Benita <ran...@gmail.com>
Date: Sun Mar 23 14:32:12 2014 +0200
doc: add a quick guide to the library
This is a nice intro to the documentation, and also preferably gently
pushes users to the "proper way" of using the library, which can be
confusing.
See also: http://fooishbar.org/tell-me-about/xkbcommon-intro/
Signed-off-by: Ran Benita <ran...@gmail.com>
diff --git a/README b/README
index 6b99c46..22c6b1e 100644
--- a/README
+++ b/README
@@ -19,6 +19,10 @@ current distributions for their X11 XKB data. More
information on
xkeyboard-config is available here:
http://www.freedesktop.org/wiki/Software/XKeyboardConfig
+Quick Guide
+===========
+
+See [Quick Guide](doc/quick-guide.md).
API
===
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index bc4f78e..57b58ee 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -655,7 +655,8 @@ WARN_LOGFILE =
# with spaces.
INPUT = @abs_top_srcdir@/xkbcommon \
- @abs_top_srcdir@/README
+ @abs_top_srcdir@/README \
+ @abs_top_srcdir@/doc/quick-guide.md
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
diff --git a/doc/quick-guide.md b/doc/quick-guide.md
new file mode 100644
index 0000000..6b336a4
--- /dev/null
+++ b/doc/quick-guide.md
@@ -0,0 +1,218 @@
+# Quick Guide
+
+## Intro
+
+This document contains a quick walk-through of the often-used parts of
+the library. We will employ a few use-cases to lead the examples:
+
+1. An evdev client. "evdev" is the Linux kernel's input subsystem; it
+ only reports to the client which keys are pressed and released.
+
+2. An X11 client, using the XCB library to communicate with the X
+ server and the xcb-xkb library for using the XKB protocol.
+
+3. A Wayland client, using the standard protocol.
+
+The snippets are not complete, and some support code is omitted. You
+can find complete and more complex examples in the source directory:
+
+1. test/interactive-evdev.c contains an interactive evdev client.
+
+2. test/interactive-x11.c contains an interactive X11 client.
+
+Also, the library contains many more functions for examining and using
+the library context, the keymap and the keyboard state. See the
+hyper-linked reference documentation or go through the xkbcommon/*.h
+header files for more details.
+
+## Code
+
+Before we can do anything interesting, we need a library context. So
+let's create one:
+
+~~~{.c}
+ #include <xkbcommon/xkbcommon.h>
+
+ struct xkb_context ctx;
+
+ ctx = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
+ if (!ctx) <error>
+~~~
+
+The xkb_context contains the keymap include paths, the log level and
+functions, and other general customizable administrativia.
+
+Next we need to create a keymap, xkb_keymap. There are different ways to
+do this.
+
+If we are an evdev client, we have nothing to go by, so we need to ask
+the user for his/her keymap preferences (for example, an Icelandic
+keyboard with a Dvorak layout). The configuration format is commonly
+called RMLVO (Rules+Model+Layout+Variant+Options), the same format used
+by the X server. With it, we can fill a struct called xkb_rule_names;
+passing NULL chooses the system's default.
+
+~~~{.c}
+ struct xkb_keymap *keymap;
+ struct xkb_rule_names names = <...>;
+
+ keymap = xkb_keymap_new_from_names(ctx, &names,
+ XKB_KEYMAP_COMPILE_NO_FLAGS);
+ if (!keymap) <error>
+~~~
+
+If we are a Wayland client, the compositor gives us a string complete
+with a keymap. In this case, we can create the keymap object like this:
+
+~~~{.c}
+ const char *keymap_string = <...>;
+
+ keymap = xkb_keymap_new_from_string(ctx, keymap_string,
+ XKB_KEYMAP_FORMAT_TEXT_V1,
+ XKB_KEYMAP_COMPILE_NO_FLAGS);
+ if (!keymap) <error>
+~~~
+
+If we are an X11 client, we are better off getting the keymap from the
+X server directly. For this we need to choose the XInput device; here
+we will use the core keyboard device:
+
+~~~{.c}
+ #include <xkbcommon/xkbcommon-x11.h>
+
+ xcb_connection_t *conn = <...>;
+ int32_t device_id;
+
+ device_id = xkb_x11_get_core_keyboard_device_id(conn);
+ if (device_id == -1) <error>
+
+ keymap = xkb_x11_keymap_new_from_device(ctx, conn, device_id,
+ XKB_KEYMAP_COMPILE_NO_FLAGS);
+ if (!keymap) <error>
+~~~
+
+Now that we have the keymap, we are ready to handle the keyboard devices.
+For each device, we create an xkb_state:
+
+~~~{.c}
+ struct xkb_state *state;
+
+ state = xkb_state_new(keymap);
+ if (!state) <error>
+~~~
+
+For X11/XCB clients, this is better:
+
+~~~{.c}
+ state = xkb_x11_state_new_from_device(keymap, conn, device_id);
+ if (!state) <error>
+~~~
+
+When we have an xkb_state for a device, we can start handling key events
+from it. Given a keycode for a key, we can get its keysym:
+
+~~~{.c}
+ <key event structure> event;
+ xkb_keycode_t keycode;
+ xkb_keysym_t keysym;
+
+ keycode = event->keycode;
+ keysym = xkb_state_key_get_one_sym(state, keycode);
+~~~
+
+We can see which keysym we got, and get its name:
+
+~~~{.c}
+ char[64] keysym_name;
+
+ if (keysym == XKB_KEY_Space)
--
To UNSUBSCRIBE, email to debian-x-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
Archive: https://lists.debian.org/e1wxpx4-0001z2...@moszumanska.debian.org
