xkbcommon/xkbcommon.h


Log

Author Commit Date CI Message
Ran Benita da83e678 2014-04-11T19:00:36 doc: add @since annotations for API added since 0.3.0 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>
Ran Benita b973d71e 2014-03-21T23:00:17 state: add xkb_state_key_get_{utf8,utf32}() API functions 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>
Ran Benita fdb4de1f 2014-03-04T19:26:56 doc: extend xkb_rule_names default-value description 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>
Ran Benita e086ba94 2014-03-04T18:24:11 doc: remove possibly confusing comment 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>
Ran Benita d7c91a15 2014-02-28T14:50:48 doc: add comments about update_key() and get_syms() order I remember we had a comment about this, but I can't find it. So add it again. Signed-off-by: Ran Benita <ran234@gmail.com>
Jasper St. Pierre 4fb7b06b 2014-02-21T18:09:00 state: Add xkb_state_key_get_consumed_mods 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.
Ran Benita 973b8fd4 2014-02-08T16:40:20 api: deprecate XKB_MAP_COMPILE_PLACEHOLDER, and use KEYMAP instead of MAP 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>
Wander Lairson Costa ac59e735 2013-09-26T09:35:33 Make C++ happy. 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>
Ran Benita dbf07de1 2013-08-29T19:49:40 doc: use 'indices' instead of 'indexes' consistently We use 'indices' in some function names so use that. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita b4cc3394 2013-08-29T19:48:35 doc: try to explain leds and shift levels Remove the @todo's. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 2a2a8d7d 2013-08-13T18:57:43 state: apply capitalization transformation on keysyms 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>
Ran Benita 9c697f80 2013-08-14T11:36:04 doc: tweak the wording on xkb_state/xkb_keymap relationship Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita d83fe702 2013-08-13T15:17:59 doc: un-clarify one subtle point 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>
Ran Benita 3a0adc0f 2013-07-31T10:38:30 doc: try to clarify some subtle points 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>
Matthias Clasen b06de307 2013-05-09T15:31:21 Add keycode min/max and iteration API 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>
David Herrmann 36f55c49 2013-03-11T12:53:39 keymap: add xkb_keymap_new_from_buffer() 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
Daniel Stone 40c46ecd 2013-03-01T23:47:59 Allow NULL rmlvo for xkb_keymap_new_from_names 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>
Daniel Stone fbe5e675 2013-02-28T10:48:40 Add environment overrides for default RMLVO 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>
Ran Benita e33dd591 2013-03-05T11:48:43 doc: some improvements Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 540feef3 2013-03-01T13:51:13 More spelling errors Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita c7aef166 2013-02-19T15:57:14 keysym: print unicode keysyms uppercase and 0-padded Use the same format as XKeysymToString. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 60bd9202 2012-11-11T00:22:46 keymap: wrap the layout parameter if it is out of range for the key 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>
Ran Benita 57761225 2012-11-07T00:41:06 Don't use trailing enum comma in public headers 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 eea0eaeb 2012-11-06T23:00:55 doc: clarify that keysym_to_utf8 returns size including '\0' Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita fb201645 2012-11-04T16:07:30 Add some explanations on consumed modifiers This should hopefully clarify this somewhat subtle point to the uninitiated users. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 7261f404 2012-10-29T01:00:27 state, context: allow passing NULL to *_unref() 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>
Ran Benita b935d361 2012-10-26T16:15:27 doc: fix wrong comment Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 3eac7599 2012-10-22T18:14:39 doc: various fixes Just moving around / fixing syntax / grammar. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 33bba368 2012-10-23T10:25:26 doc: move include_path functions to a separate group 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>
Ran Benita 0c98237f 2012-10-22T21:46:43 Change update_mask arguments to read 'depressed' instead of 'base' Just to be consistent, as we use 'depressed' everywhere else in the API. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 4b81c9f3 2012-10-22T21:00:57 Report which components of the state have changed 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>
Ran Benita 6a94b122 2012-10-22T20:49:44 Split the mods, layout, leds parts of xkb_state_components 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>
Ran Benita 3a5f87b8 2012-10-22T17:53:44 doc: add note about X11 vs. extended keycodes Signed-off-by: Ran Benita <ran234@gmail.com>
David Herrmann 7b3bd11f 2012-10-16T16:05:34 Add xkb_keysym_from_name() flags argument for case-insensitive search 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>
Ran Benita 3477d9e4 2012-10-05T16:23:03 Finish first round of API documentation There are a few @todo's, but nothing serious. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita f43b33c0 2012-10-13T13:13:55 state: make mod_index_is_consumed() return -1 on invalid input Like all the other functions. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 523e46f4 2012-10-12T10:15:43 Change log env vars to XKB_LOG_LEVEL/VERBOSITY A bit more consistent and descriptive. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita bde066b9 2012-10-11T18:13:56 doc: use JAVADOC_AUTOBRIEF Don't have to type @brief all the time. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita bbf388ec 2012-10-11T16:54:17 Make xkb_keymap_num_leds return the index range instead of active count 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>
Daniel Stone 5aaf65b7 2012-09-27T23:27:49 Add xkb_state_key_get_one_sym The trivial wrapper around xkb_state_key_get_syms that every user to date has implemented. Signed-off-by: Daniel Stone <daniel@fooishbar.org>
Ran Benita 9a18b872 2012-09-23T17:52:51 Add format argument to xkb_keymap_get_as_string 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>
Ran Benita 5d31b9e3 2012-09-23T16:57:16 Add return value the xkb_keysym_get_name 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>
Ran Benita 25b83844 2012-09-23T16:56:48 Improve API doxygen documentation 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>
Ran Benita 0dd40125 2012-09-22T10:58:00 API: add _context prefix to log-related functions 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>
Daniel Stone bf194080 2012-09-19T16:19:57 Promote keymap enumeration API to public 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>
Daniel Stone 33a66515 2012-09-12T19:55:06 API change: Rename xkb_map_* and group -> layout 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>
Daniel Stone 80e15681 2012-09-12T19:52:30 Add xkbcommon-compat.h and compat.c So we can start renaming stuff while retaining backwards source and binary compatibility. Signed-off-by: Daniel Stone <daniel@fooishbar.org>
Ran Benita b2110705 2012-09-16T14:45:32 Organize src/ and test/ headers - Add context.h and move context-related functions from xkb-priv.h to it. - Move xkb_context definition back to context.c. - Add keysym.h and move keysym upper/lower/keypad from xkb-priv.h to it. - Rename xkb-priv.h to map.h since it only contains keymap-related definitions and declarations now. - Remove unnecessary includes and some and some other small cleanups. Signed-off-by: Ran Benita <ran234@gmail.com>
Daniel Stone b4b40d73 2012-09-12T16:54:07 Copyright updates With Dan Nicholson's permission (via email), update his copyright and license statements to the standard X.Org boilerplate MIT license, as both myself and Ran have been using. Clean up my copyright declarations (in some cases to correct ownership), and add copyright/license statements from myself and/or Ran where appropriate. Signed-off-by: Daniel Stone <daniel@fooishbar.org>
Pekka Paalanen 517c7ed7 2012-08-20T15:34:07 xkbcommon.h build fix for missing stdarg.h In file included from external/collabora/libxkbcommon/src/xkb-priv.h:87, from external/collabora/libxkbcommon/src/xkbcomp/xkbcomp.h:30, from external/collabora/libxkbcommon/src/xkbcomp/xkbcomp-priv.h:30, from external/collabora/libxkbcommon/src/xkbcomp/action.h:30, from external/collabora/libxkbcommon/src/xkbcomp/action.c:27: external/collabora/libxkbcommon/xkbcommon/xkbcommon.h:279: error: expected declaration specifiers or '...' before 'va_list' Signed-off-by: Pekka Paalanen <ppaalanen@gmail.com>
Daniel Stone e60e9523 2012-09-11T12:35:24 kbproto unentanglement: XkbExplicit*Mask Signed-off-by: Daniel Stone <daniel@fooishbar.org>
Ran Benita 8d7d9792 2012-08-28T00:42:59 log: replace "priority" by "level" everywhere Now that we don't use syslog, "level" does sound more commonplace. We should change it while there is still nobody using it. Also leave some space between the integers of the xkb_log_level enum values, if we ever need to shove more in between. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 06d7803a 2012-08-30T12:13:37 state: fix mod_names_are_active This function was always returning -1. Adding a test, we see that test/state.c treat the is_active functions as returning booleans, which would treat -1 as success, so we test for > 0 instead (most users would probably get this wrong as well...). Also update the documentation for the are_active functions, and add a ATTR_NULL_SENTINEL for gcc __attribute__((sentinel)). Signed-off-by: Ran Benita <ran234@gmail.com>
Daniel Stone 2f1f1bca 2012-08-08T14:26:23 Add xkb_map_mod_mask_remove_consumed A fairly simple helper which, given an xkb_mod_mask_t, removes all modifiers which are consumed during processing of a particular key. Signed-off-by: Daniel Stone <daniel@fooishbar.org>
Daniel Stone 5e276adb 2012-08-08T14:01:46 Add xkb_log_level enum rather than using syslog Instead of relying on people including syslog.h, add our own XKB_LOG_LEVEL_* defines. Signed-off-by: Daniel Stone <daniel@fooishbar.org>
Ran Benita 1a930bf2 2012-08-07T00:20:40 Add API to query whether a modifier is consumed Currently the user has no way of knowing which of the active modifiers have been used in the translation of a keycode to its keysyms. The use case is described in the GTK docs: say there's a menu accelerator activated by "<Alt>+". Some layouts have "+" shifted, and some have it on the first level. So in keymaps where "+" is shifted, the Shift modifier is consumed and must be ignored when the user is testing for "<Alt>+". Otherwise, we may get "<Alt><Shift>+" and the accelerator should not actually fire. For this we also use the preserve[] information in the key types, which can forces us to report modifiers as unconsumed even if they were used in the translation. Until now we didn't do anything with this information. The API tries to match its surronding. It's not very efficient but this can be fixed. Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita f2ecd665 2012-08-06T20:04:22 log: allow to resore default log function Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 70f35cfb 2012-07-20T13:10:13 Add logging API Add new public API to provide the library users with some options to control and customize the logging output from the library. It is based upon the skeleton from the libabc demo libray: https://git.kernel.org/?p=linux/kernel/git/kay/libabc.git which is public domain and works pretty well. This requires passing in the context object in every logging call, and thus the conversion is done file by file. We also remove the global warningLevel variable in favor of a verbosity level in the context, which can be set by the user and is silent by default. One issue is the ACTION calls, which, while nice, do not play very well with line- and priority-based logging, and would require some line continuation handling or keeping state or some other compromise. So instead remove these and just inline them with their respective warning/error. So instead of: ERROR("Memory allocation failed\n") ACTION("Removing all files on hardisk\n") its something like that: log_err("Memory allocation failed; Removing all files on harddisk\n") Signed-off-by: Ran Benita <ran234@gmail.com>
Ran Benita 5e164ff1 2012-07-23T00:41:27 build: drop the include/ directory The include/ dir is somewhat redundant and makes it just a bit harder to handle the -I directives from out side of automake; without it the default $(top_buildir) just works. Here's also some further justifications I found: http://smcv.pseudorandom.co.uk/2008/09/pc-uninstalled/ Signed-off-by: Ran Benita <ran234@gmail.com>