From 89fbf979f13f9254e55f69dbe1229c7d8b8e4b4c Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sat, 12 Apr 2014 00:22:47 +0300 Subject: [PATCH] doc: explain keysym/string transformation 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 --- xkbcommon/xkbcommon.h | 52 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 45 insertions(+), 7 deletions(-) diff --git a/xkbcommon/xkbcommon.h b/xkbcommon/xkbcommon.h index 2cc4e60..b5fbf3a 100644 --- a/xkbcommon/xkbcommon.h +++ b/xkbcommon/xkbcommon.h @@ -363,6 +363,34 @@ struct xkb_rule_names { }; /** + * @page keysym-transformations Keysym Transformations + * + * Keysym translation is subject to several "keysym transformations", + * as described in the XKB specification. These are: + * + * - Capitalization transformation. If the Caps Lock modifier is + * active and was not consumed by the translation process, a single + * keysym is transformed to its upper-case form (if applicable). + * Similarly, the UTF-8/UTF-32 string produced is capitalized. + * + * This is described in: + * http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Lock_Modifier + * + * - Control transformation. If the Control modifier is active and + * was not consumed by the translation process, the string produced + * is transformed to its matching ASCII control character (if + * applicable). Keysyms are not affected. + * + * This is described in: + * http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier + * + * Each relevant function discusses which transformations it performs. + * + * These transformations are not applicable when a key produces multiple + * keysyms. + */ + +/** * @defgroup keysyms Keysyms * Utility functions related to keysyms. * @@ -434,8 +462,8 @@ xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags); * terminating byte). If the keysym does not have a Unicode * representation, returns 0. If the buffer is too small, returns -1. * - * Prefer not to use this function on keysyms obtained from an - * xkb_state. In this case, use xkb_state_key_get_utf8() instead. + * This function does not perform any @ref keysym-transformations. + * Therefore, prefer to use xkb_state_key_get_utf8() if possible. * * @sa xkb_state_key_get_utf8() */ @@ -449,8 +477,8 @@ xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size); * compatible with UCS-4. If the keysym does not have a Unicode * representation, returns 0. * - * Prefer not to use this function on keysyms obtained from an - * xkb_state. In this case, use xkb_state_key_get_utf32() instead. + * This function does not perform any @ref keysym-transformations. + * Therefore, prefer to use xkb_state_key_get_utf32() if possible. * * @sa xkb_state_key_get_utf32() */ @@ -1272,9 +1300,11 @@ xkb_state_update_mask(struct xkb_state *state, * key in the given keyboard state. * * As an extension to XKB, this function can return more than one keysym. - * If you do not want to handle this case, you should use - * xkb_state_key_get_one_sym(), which additionally performs transformations - * which are specific to the one-keysym case. + * If you do not want to handle this case, you can use + * xkb_state_key_get_one_sym() for a simpler interface. + * + * This function does not perform any @ref keysym-transformations. + * (This might change). * * @returns The number of keysyms in the syms_out array. If no keysyms * are produced by the key in the given keyboard state, returns 0 and sets @@ -1306,6 +1336,9 @@ xkb_state_key_get_syms(struct xkb_state *state, xkb_keycode_t key, * You may safely pass NULL and 0 to @p buffer and @p size to find the * required size (without the NUL-byte). * + * This function performs Capitalization and Control @ref + * keysym-transformations. + * * @memberof xkb_state * @since 0.4.1 */ @@ -1320,6 +1353,9 @@ xkb_state_key_get_utf8(struct xkb_state *state, xkb_keycode_t key, * @returns The UTF-32 representation for the key, if it consists of only * a single codepoint. Otherwise, returns 0. * + * This function performs Capitalization and Control @ref + * keysym-transformations. + * * @memberof xkb_state * @since 0.4.1 */ @@ -1338,6 +1374,8 @@ xkb_state_key_get_utf32(struct xkb_state *state, xkb_keycode_t key); * @returns The keysym. If the key does not have exactly one keysym, * returns XKB_KEY_NoSymbol * + * This function performs Capitalization @ref keysym-transformations. + * * @sa xkb_state_key_get_syms() * @memberof xkb_state */ -- 2.7.4