The new API is useful to implement features like auto-type and
desktop automation. Since the inputs for these features is usually
specified in terms of the symbols that need to be typed, the
implementation needs to be able to invert the keycode->keysym
transformation and produce a sequence of keycodes that can be used
to type the requested character(s).
In order to support features like auto-type and UI automation, the
relevant tools need to be able to invert the keycode->keysym->text
transformation. In order to facilitate that, a new API was added.
It allows querying the keysyms that correspond to particular Unicode
codepoints. For all practical purposes, it can be thought of as an
inverse of xkb_keysym_to_utf32().
These can be useful in some odd cases.
There is already an implementation (+ tests) for internal use, so all
that's needed is to export them.
If xkbcommon were to provide a way to convert a Unicode codepoint to a
keysym, this could have been implemented externally as follows:
uint32_t codepoint = xkb_keysym_to_utf32(keysym);
uint32_t upper_codepoint = my_unicode_library_to_upper(codepoint);
xkb_keysym_t upper_keysym = theoretical_xkb_keysym_from_utf32(upper_codepoint);
However keysym -> codepoint is not injective so such a function is not
possible strictly speaking.
Signed-off-by: Ran Benita <ran234@gmail.com>
The current functions dealing with consumed modifiers use the
traditional XKB definition of consumed modifiers (see description in the
added documentation). However, for several users of the library (e.g.
GTK) this definition is unsuitable or too eager. This is exacerbated by
some less-than-ideal xkeyboard-config type definitions (CTRL+ALT seems
to cause most grief...).
So, because we
- want to enable alternative interpretations, but
- don't want to expose too much internal details, and
- want to keep things simple for all library users,
we add a high-level "mode" parameter which selects the desired
interpretation. New ones can be added as long as they make some sense.
All of the old consumed-modifiers functions keep using the traditional
("XKB") mode. I mark xkb_state_mod_mask_remove_consumed() and as
deprecated without adding a *2 variant because I don't it is very useful
(or used) in practice.
Alternative modes are added in subsequent commits (this commit only adds
a mode for the existing behavior).
https://github.com/xkbcommon/libxkbcommon/issues/17
Signed-off-by: Ran Benita <ran234@gmail.com>
xkb_keymap_key_by_name() allows finding a keycode from a given keyname and
is useful for generating keyboard events to use in regression tests
during CI
xkb_keymap_key_get_name() is the inverse of xkb_keymap_key_by_name()
Signed-off-by: Mike Blumenkrantz <zmike@osg.samsung.com>
[ran: some stylistic tweaks + another test case]
Signed-off-by: Ran Benita <ran234@gmail.com>
The @level argument is restricted by xkb_keymap_num_levels_for_key(). Fix
the description to no longer mention xkb_keymap_num_layouts_for_key().
Signed-off-by: David Herrmann <dh.herrmann@gmail.com>
The documentation should be clear about what is happening, even if it's
rather unlikely anyone will really dig into the details.
Signed-off-by: Ran Benita <ran234@gmail.com>
And also add release dates to the NEWS.
We're adding API freely, so this can make life easier for anyone who
wants to stay compatible with an older version.
Signed-off-by: Ran Benita <ran234@gmail.com>
These functions generally have the same effect as
xkb_state_key_get_syms() + xkb_keysym_to_utf{8,32}().
So why add them?
- They provide a slightly nicer interface, especially if the string is
the only interest.
- It makes the handling of multiple-keysyms-to-utf8 transparent. For the
designated use-case of multiple-keysyms (unicode combining
characters), this is a must. We also validate the UTF-8, which the
user might not otherwise do.
- We will need to apply some transformation on the resulting string
which depend on the xkb_state. This is not possible with the
xkb_keysym_* functions.
With these functions, the existing xkb_keysym_to_utf{8,32}() are not
expected to be used by a typical user; they are "raw" functions.
Signed-off-by: Ran Benita <ran234@gmail.com>
Especially a mention of the XKB_DEFAULT_* envvars was missing.
Reported-by: Paeglis Gatis <Gatis.Paeglis@digia.com> (thanks!)
Signed-off-by: Ran Benita <ran234@gmail.com>
There are valid reasons to use the other keymap-creation functions, if
one needs them. On the other hand, if one is supposed to use RMLVO, it
is more or less the only choice, so the comment is not needed in this
case as well.
Signed-off-by: Ran Benita <ran234@gmail.com>
This retrieves the mask of consumed modifiers for a given key and state,
which is helpful for toolkits without having them to do it one modifier
at a time, or pass in 0xFFFFFFFF to xkb_state_remove_consumed_mods to
"reverse-engineer" the consumed mods.
The PLACEHOLDER was not meant to be used, but c++ doesn't like passing 0
to enums, so it was used. For this reason we add all the NO_FLAGS items,
so the PLACEHOLDER shouldn't be used anymore.
Second, XKB_MAP is the prefix we used ages ago, KEYMAP is the expected
prefix here. So deprecate that as well.
The old names may still be used through the xkbcommon-compat.h header,
which is included by default (no need to include directly).
Signed-off-by: Ran Benita <ran234@gmail.com>
For most functions taking an enum flags parameter, we use 0 value to
indicate that no flags should be applied.
C++ has a stronger type system than C and will not implicitly convert
int's to enum's. Thus, we create valid 0 enum values for enum types
where it makes sense.
Signed-off-by: Wander Lairson Costa <wander.lairson@gmail.com>
Signed-off-by: Ran Benita <ran234@gmail.com>
The xkbproto spec says:
http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Lock_Modifier
If the Lock modifier is not consumed by the symbol lookup process,
routines that determine the symbol and string that correspond to
an event should capitalize the result.
This was not an issue until now, because most xkeyboard-config keymaps
do not utilize this "feature", and specify the keysyms for the Lock
modifier explicitly instead. However, some keymaps do depend on it, e.g.
ch(fr) for eacute and others.
The spec goes on to describe two options for doing this transformation:
locale-sensitive and locale-insensitive. We opt for the latter; it is
less desirable but we don't want *that* headache.
Also, only xkb_state_key_get_one_sym() is changed;
xkb_state_key_get_syms() is left as-is, and always reports the
untransformed keysyms. This is for the following reasons:
- The API doesn't allow it, since we return a const pointer directly to
the keymap keysyms table and we can't transform that.
- The transformation doesn't make sense for multiple-keysyms.
- It can be useful for an application to get the "raw" keysyms if it
wants to (e.g. maybe it wants to do the transformation itself).
Finally, note that xkb_state_mod_index_is_consumed() does *not*
report Lock as consumed even if it was used in the transformation. This
is what Xlib does.
This definitely doesn't fall under the "hard to misuse" API rule but
it's the best we can do.
https://bugs.freedesktop.org/show_bug.cgi?id=67167
Reported-By: Gatis Paeglis <gatis.paeglis@digia.com>
Signed-off-by: Ran Benita <ran234@gmail.com>
Including the X server is a bit of a borderline case; we should mostly
encourage people to use update_mask() only when xkbcommon itself
serializes the state on the other side. But it's not entirely wrong
either.. So rephrase a bit.
Signed-off-by: Ran Benita <ran234@gmail.com>
Which to choose: xkb_state_update_key() / xkb_state_update_mask(). If you
use update_mask(), you don't (and shouldn't) use update_key().
If you use update_key(), be careful not to have unmatched UP/DOWN
calls; this can bring about stuck modifiers etc.
Probably want to use XKB_STATE_{MODS,LAYOUT}_EFFECTIVE. The others are
only useful in very special cases.
Signed-off-by: Ran Benita <ran234@gmail.com>
Add three new pieces of API:
- xkb_keymap_min_keycode does what it says on the tin
- xkb_keymap_max_keycode likewise
- xkb_keymap_key_for_each calls the provided function once for every
valid key in the keymap
Signed-off-by: Daniel Stone <daniel@fooishbar.org>
The current API doesn't allow the caller to create keymaps from mmap()'ed
files. The problem is, xkb_keymap_new_from_string() requires a terminating
0 byte. However, there is no way to guarantee that when using mmap() so a
user currently has to copy the whole file just to get the terminating zero
byte (assuming they cannot use xkb_keymap_new_from_file()).
This adds a new entry xkb_keymap_new_from_buffer() which takes a memory
location and the buffer size in bytes.
Internally, we depend on yy_scan_{string,byte}() helpers. According to
flex documentation these already copy the input string because they are
wrappers around yy_scan_buffer().
yy_scan_buffer() on the other hand has some insane requirements. The
buffer must be writeable and the last two bytes must be ASCII-NUL. But the
buffer may contain other 0 bytes just fine.
Because we don't want these constraints in our public API,
xkb_keymap_new_from_buffer() needs to create a copy of the input memory.
But it then calls yy_scan_buffer() directly. Hence, we have the same
number of buffer-copies as with *_from_string() but without the
terminating 0 requirement.
The explicit yy_scan_buffer() call is preferred over yy_scan_byte() so the
buffer-copy operation is not hidden somewhere in flex.
Maybe some day we no longer depend on flex and can have a zero-copy API. A
user could mmap() a file and it would get parsed right from this buffer.
But until then, we shouldn't expose this limitation in the API but instead
provide an API that some day can work with zero-copy.
Signed-off-by: David Herrmann <dh.herrmann@gmail.com>
[ran: rebased on top of my branch]
Conflicts:
Makefile.am
src/xkbcomp/xkbcomp.c
Previously we allowed you to pass a names struct with five NULL members,
but not just pass NULL for the struct itself. This was pretty dumb. :(
Signed-off-by: Daniel Stone <daniel@fooishbar.org>
You can now set default values in the environment, as well as a context
option to ignore the environment, e.g. for tests.
Signed-off-by: Daniel Stone <daniel@fooishbar.org>
The functions num_levels_for_key() and get_syms_by_level() have a
'layout' parameter. Currently it is expected that this value is always
legal for the key, as determined by num_layouts_for_key(). However,
there are legitimate use cases for passing an out-of-range layout there,
most probably passing the effective layout, and expecting to get the
keysyms/levels for just this layout. So we wrap it just as we do in the
xkb_state_* functions.
This is also useful for stuff like this:
http://developer.gnome.org/gdk/stable/gdk-Keyboard-Handling.html#gdk-keymap-lookup-key
If this behavior is not desired, the user has the option to check
against num_layouts_for_key herself.
https://bugs.freedesktop.org/show_bug.cgi?id=56866
Reported-by: Gatis Paeglis <gatis.paeglis@digia.com>
Signed-off-by: Ran Benita <ran234@gmail.com>
Pretty annoying, but C89 doesn't support that (officially), and it might
cause warning with -pedantic, etc. (though you need -Wsystem-headers to
see them usually). Removing them is not a big deal.
Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita
Jaroslaw Kubik
Peter Hutterer
Jesse
Ran Benita
Mike Blumenkrantz
David Herrmann
Jasper St. Pierre
Wander Lairson Costa
Matthias Clasen
Daniel Stone