diff options
| author | Ran Benita <ran234@gmail.com> | 2012-11-11 00:22:46 +0200 |
|---|---|---|
| committer | Ran Benita <ran234@gmail.com> | 2012-11-11 00:32:16 +0200 |
| commit | 60bd92021b63ecd3f8396704c841a0bf0fdab72b (patch) | |
| tree | 65163ad722b934323a02a6eac51ebe6b0a37cc9b /xkbcommon | |
| parent | 324d4dbd99f5fb409e8466165481fe2d56c8eb8c (diff) | |
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>
Diffstat (limited to 'xkbcommon')
| -rw-r--r-- | xkbcommon/xkbcommon.h | 18 |
1 files changed, 10 insertions, 8 deletions
diff --git a/xkbcommon/xkbcommon.h b/xkbcommon/xkbcommon.h index 43f9df1..244b35b 100644 --- a/xkbcommon/xkbcommon.h +++ b/xkbcommon/xkbcommon.h @@ -864,6 +864,10 @@ xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key); /** * Get the number of shift levels for a specific key and layout. * + * If @c layout is out of range for this key (that is, larger or equal to + * the value returned by xkb_keymap_num_layouts_for_key()), it is brought + * back into range in a manner consistent with xkb_state_key_get_layout(). + * * @sa xkb_level_index_t * @memberof xkb_keymap */ @@ -881,19 +885,17 @@ xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key, * * @param[in] keymap The keymap. * @param[in] key The keycode of the key. - * @param[in] layout The layout for which to get the keysyms. This must - * be smaller than: - * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode - * Usually it would be: - * @code xkb_state_key_get_layout(state, key) @endcode + * @param[in] layout The layout for which to get the keysyms. * @param[in] level The shift level in the layout for which to get the * keysyms. This must be smaller than: * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode - * usually it would be: - * @code xkb_state_key_get_level(state, key, layout) @endcode - * @param[out] syms_out An immutible array of keysyms corresponding the + * @param[out] syms_out An immutible array of keysyms corresponding to the * key in the given layout and shift level. * + * If @c layout is out of range for this key (that is, larger or equal to + * the value returned by xkb_keymap_num_layouts_for_key()), it is brought + * back into range in a manner consistent with xkb_state_key_get_layout(). + * * @returns The number of keysyms in the syms_out array. If no keysyms * are produced by the key in the given layout and shift level, returns 0 * and sets syms_out to NULL. |