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>
For error handling code, it's nice to be able to pass NULL to these
function without worrying about segfaults ensuing. free() sets the
precedent here.
Also document this fact.
Signed-off-by: Ran Benita <ran234@gmail.com>
These are 'special intrest' function, like the logging functions, so
it's nice to have them in their own logical group.
Signed-off-by: Ran Benita <ran234@gmail.com>
We add a return value to the xkb_state_update_key and
xkb_state_update_mask, which reports to the caller which of the state
components have changed as a result.
This restores the XKB functionality of the XkbStateNotify and
XkbIndicatorsStateNotify events. See:
http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Events
It is quite useful in some situations. For example, it allows an
application to avoid doing some work if nothing of relevance in the
state has changed. Say, a keyboard layout applet. Also useful for
debugging.
The deltas themselves are not provided, because I can't see a use case.
If needed, it should be possible to add some API for that.
In xkbcommon, keymaps are immutable, so all of the other *Notify events
from XKB are irrelevant.
Signed-off-by: Ran Benita <ran234@gmail.com>
Note first:
This commits breaks the ABI somewhat. If an application is run against
this commit without recompiling against the updated header, these break:
- xkb_state_layout_*_is_active always retuns false.
- xkb_state_serialize_mods always returns 0.
So it might break layout switching in some applications. However,
xkbcommon-compat.h provides the necessary fixes, so recompiling should
work (though updating the application is even better).
Split the enum to its individual components, which enables us to refer
to them individually. We will use that later for reporting which
components of the state have changed after update.
Signed-off-by: Ran Benita <ran234@gmail.com>
This adds a flags argument to xkb_keysym_from_name() so we can perform a
case-insensitive search. This should really be supported as many keysyms
have really weird capitalization-rules.
However, as this may produce conflicts, users must be warned to only use
this for fallback paths or error-recovery. This is also the reason why the
internal XKB parsers still use the case-sensitive search.
This also adds some test-cases so the expected results are really
produced. The binary-size does _not_ change with this patch. However,
case-sensitive search may be slightly slower with this patch. But this is
barely measurable.
[ran: use bool instead of int for icase, add a recommendation to the
doc, and test a couple "thorny" cases.]
Signed-off-by: David Herrmann <dh.herrmann@googlemail.com>
Currently xkb_keymap_num_leds() returns a count of valid (settable)
leds. Because the indexes might be non-consecutive, and some leds
might not be settable, it is incorrect to use this function for
iterating over the leds in the keymap. But this is the main use case of
this function, so instead of the current behavior we adapt the function
to the use case by making it return the needed range of iteration.
The caller needs to handle invalid intermittent indexes, though.
Signed-off-by: Ran Benita <ran234@gmail.com>
This function really needs a format argument, for symmetry with the
keymap creation functions. If we add new formats, we will almost
certainly want to add support for serializing it into a string. It would
also allow to convert from one format to another, etc.
The in the common case, the user would just want to use the format she
used to create the keymap; for that we add a special
XKB_KEYMAP_USE_ORIGINAL_FORMAT value, which will do that (it is defined
to -1 outside of the enum because I have a feeling we might want to use
0 for something else). To support this we need to keep the format inside
the keymap. While we're at it we also initialize keymap flags properly.
This changes the API, but the old xkb_map_get_as_string name works as
expected so this is the best time to do this.
Signed-off-by: Ran Benita <ran234@gmail.com>
This is useful to see whether the function was successful and whether
truncation occurred.
It just changes void -> int so shouldn't break API or ABI.
Signed-off-by: Ran Benita <ran234@gmail.com>
To make it look better and a bit more structured and informative.
Not all of the functions are converted to doxygen format, so this is not
finished.
Signed-off-by: Ran Benita <ran234@gmail.com>
This is to follow the general scheme set by all of the other API
functions.
Since no one is using these functions yet, we don't (actually better
not) add the old names to xkbcommon-compat.h.
Signed-off-by: Ran Benita <ran234@gmail.com>
Rename the functions to get keysyms by key/layout/level to fit with the
recent public API renames, and expose them.
Signed-off-by: Daniel Stone <daniel@fooishbar.org>
Move xkb_map_* functions to xkb_keymap_*, xkb_key_* functions under
either xkb_keymap or xkb_state, and rename groups to layout in all
user-visible API.
Backwards-compatible hooks are provided, such that old source will
build, but silently mangled to the new names, and old binaries will
also continue to work.
Signed-off-by: Daniel Stone <daniel@fooishbar.org>
Ran Benita
Jasper St. Pierre
Wander Lairson Costa
Matthias Clasen
David Herrmann
Daniel Stone
David Herrmann