From 16b53769eba7d5d8249a217aa29287d72b7713c2 Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 14 Sep 2011 14:23:18 +0200 Subject: libX11 git update 14 sep 2011 --- libX11/specs/XKB/ch12.xml | 841 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 841 insertions(+) create mode 100644 libX11/specs/XKB/ch12.xml (limited to 'libX11/specs/XKB/ch12.xml') diff --git a/libX11/specs/XKB/ch12.xml b/libX11/specs/XKB/ch12.xml new file mode 100644 index 000000000..1f10261c7 --- /dev/null +++ b/libX11/specs/XKB/ch12.xml @@ -0,0 +1,841 @@ + +Interpreting Key Events + + +Xkb provides functions to help developers interpret key events without having +to directly interpret Xkb data structures. Xkb also modifies the behavior of +several core X library functions. + + + +Effects of Xkb on the Core X Library + + +When support for Xkb is built into the X library, the +XOpenDisplay + function looks for a compatible version of Xkb on the server. If it finds a +compatible version, it initializes the extension and enables +implicit support + for Xkb in a number of X library functions. This makes it possible for clients +to take advantage of nearly all Xkb features without having to be rewritten or +even recompiled, if they are built with shared libraries. This implicit support +is invisible to most clients, but it can have side effects, so the extension +includes ways to control or disable it. + + + + +Effects of Xkb on Event State + + +Because +XOpenDisplay + initializes Xkb, some events contain an Xkb description of the keyboard state +instead of that normally used by the core protocol. See section 17.1.1 for more +information about the differences between Xkb keyboard state and that reported +by the core protocol. + + + + + +Effects of Xkb on MappingNotify Events + + +When Xkb is missing or disabled, the X library tracks changes to the keyboard +mapping using +MappingNotify + events. Whenever the keyboard mapping is changed, the server sends all clients +a +MappingNotify + event to report the change. When a client receives a +MappingNotify + event, it is supposed to call +XRefreshKeyboardMapping + to update the keyboard description used internally by the X library. + + + + +The X Keyboard Extension uses +XkbMapNotify + and +XkbNewKeyboardNotify + events to track changes to the keyboard mapping. When an Xkb-aware client +receives either event, it should call +XkbRefreshKeyboardMapping + to update the keyboard description used internally by the X library. To avoid +duplicate events, the X server does not send core protocol +MappingNotify + events to a client that has selected for +XkbMapNotify + events. + + + + +The implicit support for Xkb selects for +XkbMapNotify + events. This means that clients that do not explicitly use Xkb but that are +using a version of the X library that has implicit support for Xkb do not +receive +MappingNotify + events over the wire. Clients that were not written with Xkb in mind do not +recognize or properly handle the new Xkb events, so the implicit support +converts them to +MappingNotify + events that report approximately the same information, unless the client has +explicitly selected for the Xkb version of the event. + + + + +An Xkb-capable X server does not send events from keys that fall outside the +legal range of keycodes expected by that client. Once the server sends a client +an +XkbNewKeyboardNotify + event, it reports events from all keys because it assumes that any client that +has receieved an +XkbNewKeyboardNotify + event expects key events from the new range of keycodes. The implicit support +for Xkb asks for +XkbNewKeyboardNotify + events, so the range of keycodes reported to the client might vary without the +client’s knowledge. Most clients don’t really care about the range of legal +keycodes, but some clients maintain information about each key and might have +problems with events that come from unexpected keys. Such clients can set the + +XkbLC_IgnoreNewKeyboards + library control (see section 11.3.1) to prevent the implicit support from +requesting notification of changes to the legal range of keycodes. + + + + + +X Library Functions Affected by Xkb + + +The following X library functions are modified by Xkb: + + + + XKeycodeToKeysym + XKeysymToKeycode + XLookupKeysym + XLookupString + XRefreshKeyboardMapping + XRebindKeysym + + + +The implicit support for Xkb replaces a number of X library functions with +versions that understand and use the X Keyboard Extension. In most cases, the +semantics of the new versions are identical to those of the old, but there are +occasional visible differences. This section lists all of the functions that +are affected and the differences in behavior, if any, that are visible to +clients. + + + + +The +XKeycodeToKeysym + function reports the keysym associated with a particular index for a single +key. The index specifies a column of symbols in the core keyboard mapping (that +is, as reported by the core protocol +GetKeyboardMapping + request). The order of the symbols in the core mapping does not necessarily +correspond to the order of the symbols used by Xkb; section 17.1.3 describes +the differences. + + + + +The +XKeysymToKeycode + function reports a keycode to which a particular keysym is bound. When Xkb is +missing or disabled, this function looks in each column of the core keyboard +mapping in turn and returns the lowest numbered key that matches in the lowest +numbered group. When Xkb is present, this function uses the Xkb ordering for +symbols instead. + + + + +The +XLookupKeysym + function reports the symbol in a specific column of the key associated with an +event. Whether or not Xkb is present, the column specifies an index into the +core symbol mapping. + + + + +The +XLookupString + function reports the symbol and string associated with a key event, taking +into account the keycode and keyboard state as reported in the event. When Xkb +is disabled or missing, +XLookupString + uses the rules specified by the core protocol and reports only ISO Latin-1 +characters. When Xkb is present, +XLookupString + uses the explicit keyboard group, key types, and rules specified by Xkb. When +Xkb is present, +XLookupString + is allowed, but not required, to return strings in character sets other than +ISO Latin-1, depending on the current locale. If any key bindings are defined, + +XLookupString + does not use any consumed modifiers (see sections 11.1.2 and 15.2) to +determine matching bindings. + + + + +The +XRefreshKeyboardMapping + function updates the X library’s internal representation of the keyboard to +reflect changes reported via +MappingNotify + events. When Xkb is missing or disabled, this function reloads the entire +modifier map or keyboard mapping. When Xkb is present, the implicit Xkb support +keeps track of the changed components reported by each +XkbMapNotify + event and updates only those pieces of the keyboard description that have +changed. If the implicit support has not noted any keyboard mapping changes, + +XRefreshKeyboardMapping + updates the entire keyboard description. + + + + +The +XRebindKeysym + function associates a string with a keysym and a set of modifiers. Xkb does +not directly change this function, but it does affect the way that the state +reported in the event is compared to the state specified to +XRebindKeysym +. When Xkb is missing or disabled, +XLookupString + returns the specified string if the modifiers in the event exactly match the +modifiers from this call. When Xkb is present, any modifiers used to determine +the keysym are consumed and are not used to look up the string. + + + + + + +Xkb Event and Keymap Functions + + +To find the keysym bound to a particular key at a specified group and shift +level, use XkbKeycodeToKeysym. + + + + + + + + +KeySym +XkbKeycodeToKeysym +( +dpy, kc, group, level +) + + + + +Display * dpy; /* connection to X server */ + + + + +KeyCode kc; /* key of interest */ + + + + +unsigned int group; /* group of interest */ + + + + +unsigned int level; /* shift level of interest */ + + + + + + + + +XkbKeycodeToKeysym + returns the keysym bound to a particular group and shift level for a +particular key on the core keyboard. If +kc + is not a legal keycode for the core keyboard, or if +group + or +level + are out of range for the specified key, +XkbKeycodeToKeysym + returns +NoSymbol +. + + + + +To find the set of modifiers bound to a particular keysym on the core keyboard, +use +XkbKeysymToModifiers +. + + + + + + + + + +unsigned + +int +XkbKeysymToModifiers +( +dpy +, + ks +) + + + + +Display * + dpy +; /* connection to X server */ + + + + +KeySym + ks +; /* keysym of interest */ + + + + + + + + +XkbKeysymToModifiers + finds the set of modifiers currently bound to the keysym +ks + on the core keyboard. The value returned is the mask of modifiers bound to the +keysym +ks +. If no modifiers are bound to the keysym, +XkbKeysymToModifiers + returns zero; otherwise, it returns the inclusive OR of zero or more of the +following: +ShiftMask +, +ControlMask +, +LockMask +, +Mod1Mask +, +Mod2Mask +, +Mod3Mask +, +Mod4Mask, + and +Mod5Mask +. + + + + +Use +XkbLookupKeySym + to find the symbol associated with a key for a particular state. + + + + + + + + + +Bool +XkbLookupKeySym +( +dpy +, + key +, + state +, + mods_rtrn +, + sym_rtrn +) + + + + +Display * + dpy +; /* connection to X server */ + + + + +KeyCode + key +; /* key for which symbols are to be found */ + + + + +unsigned int + state +; /* state for which symbol should be found */ + + + + +unsigned int * + mods_rtrn +; /* backfilled with unconsumed modifiers */ + + + + +KeySym * + sym_rtrn +; /* backfilled with symbol associated with key + state */ + + + + + + + + +XkbLookupKeySym + is the equivalent of the core +XLookupKeySym + function. For the core keyboard, given a keycode +key + and an Xkb state +state +, +XkbLookupKeySym + returns the symbol associated with the key in +sym_rtrn + and the list of modifiers that should still be applied in +mods_rtrn +. The +state + parameter is the state from a +KeyPress + or +KeyRelease + event. +XkbLookupKeySym + returns +True + if it succeeds. + + + + +Use +XkbLookupKeyBinding + to find the string bound to a key by +XRebindKeySym +. +XkbLookupKeyBinding + is the equivalent of the core +XLookupString + function. + + + + + + + + + +int +XkbLookupKeyBinding +( +dpy +, + sym +, + state +, + buf +, + nbytes +, + extra_rtrn +) + + + + +Display * + dpy +; /* connection to server */ + + + + +KeySym + sym +; /* symbol to be looked up */ + + + + +unsigned int +state +; /* state for which string is to be looked up */ + + + + +char * + buf +; /* buffer into which returned string is written */ + + + + +int + nbytes +; /* size of buffer in bytes */ + + + + +int * + extra_rtrn +; /* backfilled with number bytes overflow */ + + + + + + + + +XRebindKeysym + binds an ASCII string to a specified keysym, so that the string and keysym are +returned when the key is pressed and a specified list of modifiers are also +being held down. +XkbLookupKeyBinding + returns in +buf + the string associated with the keysym +sym + and modifier state +state +. +buf + is +NULL + terminated unless there’s an overflow. If the string returned is larger than + +nbytes +, a count of bytes that does not fit into the buffer is returned in extra_rtrn. + +XkbTranslateKeySym + returns the number of bytes that it placed into +buf +. + + + + +To find the string and symbol associated with a keysym for a given keyboard +state, use +XkbTranslateKeySym +. + + + + + + + + + +int +XkbTranslateKeySym +( +dpy +, + sym_inout +, + mods +, + buf +, + nbytes +, +extra_rtrn +) + + + + +Display * + dpy +; /* connection to X server */ + + + + +KeySym * + sym_inout +; /* symbol to be translated; result of translation */ + + + + +unsigned int + mods +; /* modifiers to apply to +sym_inout + */ + + + + +char * + buf +; /* buffer into which returned string is written */ + + + + +int + nbytes +; /* size of buffer in bytes */ + + + + +int * + extra_rtrn +; /* number of bytes overflow*/ + + + + + + + + +XkbTranslateKeySym + applies the transformations specified in +mods + to the symbol specified by +sym_inout +. It returns in +buf + the string, if any, associated with the keysym for the current locale. If the +transformations in +mods + changes the keysym, +sym_inout + is updated accordingly. If the string returned is larger than +nbytes +, a count of bytes that does not fit into the buffer is returned in extra_rtrn. + +XkbTranslateKeySym + returns the number of bytes it placed into +buf +. + + + + +To update the keyboard description that is internal to the X library, use + +XkbRefreshKeyboardMapping +. + + + + + + + + + +Status +XkbRefreshKeyboardMapping +( +event) + + + + +XkbMapNotifyEvent * + event +; /* event initiating remapping */ + + + + + + + + +XkbRefreshKeyboardMapping + is the Xkb equivalent of the core +XRefreshKeyboardMapping + function. It requests that the X server send the current key mapping +information to this client. A client usually invokes +XkbRefreshKeyboardMapping + after receiving an +XkbMapNotify + event. +XkbRefreshKeyboardMapping + returns +Success + if it succeeds and +BadMatch + if the event is not an Xkb event. + + + + +The +XkbMapNotify + event can be generated when some client calls +XkbSetMap +, +XkbChangeMap +, +XkbGetKeyboardByName +, or any of the standard X library functions that change the keyboard mapping +or modifier mapping. + + + + +To translate a keycode to a key symbol and modifiers, use +XkbTranslateKeyCode +. + + + + + + + + + +Booll +XkbTranslateKeyCode +( +xkb, key, mods, mods_rtrn, keysym_rtrn) + + + + +XkbDescPtr +xkb +; /* keyboard description to use for translation */ + + + + +KeyCode +key +; /* keycode to translate */ + + + + +unsigned int +mods +; /* modifiers to apply when translating +key + */ + + + + +unsigned int * +mods_rtrn +; /* backfilled with unconsumed modifiers */ + + + + +KeySym * +keysym_rtrn +; /* keysym resulting from translation */ + + + + + + + + +mods_rtrn + is backfilled with the modifiers consumed by the translation process. + +mods + is a bitwise inclusive OR of the legal modifier masks: +ShiftMask +, +LockMask +, +ControlMask +, +Mod1Mask +, +Mod2Mask +, +Mod3Mask +, +Mod4Mask +, +Mod5Mask +.The +AlwaysConsumeShiftAndLock + library control (see section 11.1.3), if enabled, causes +XkbTranslateKeyCode + to consume shift and lock. + XkbTranslateKeyCode + returns +True + if the translation resulted in a keysym, and +False + if it resulted in +NoSymbol +. + + + -- cgit v1.2.3