diff options
Diffstat (limited to 'libX11/specs/XKB/ch12.xml')
| -rw-r--r-- | libX11/specs/XKB/ch12.xml | 841 |
1 files changed, 841 insertions, 0 deletions
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 @@ +<chapter id='interpreting_key_events'> +<title>Interpreting Key Events</title> + +<para> +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. +</para> + +<sect1 id='effects_of_xkb_on_the_core_x_library'> +<title>Effects of Xkb on the Core X Library</title> + +<para> +When support for Xkb is built into the X library, the <emphasis> +XOpenDisplay</emphasis> + function looks for a compatible version of Xkb on the server. If it finds a +compatible version, it initializes the extension and enables <emphasis> +implicit support</emphasis> + 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. +</para> + + +<sect2 id='effects_of_xkb_on_event_state'> +<title>Effects of Xkb on Event State</title> + +<para> +Because <emphasis> +XOpenDisplay</emphasis> + 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. +</para> + + +</sect2> +<sect2 id='effects_of_xkb_on_mappingnotify_events'> +<title>Effects of Xkb on MappingNotify Events</title> + +<para> +When Xkb is missing or disabled, the X library tracks changes to the keyboard +mapping using <emphasis> +MappingNotify</emphasis> + events. Whenever the keyboard mapping is changed, the server sends all clients +a <emphasis> +MappingNotify</emphasis> + event to report the change. When a client receives a <emphasis> +MappingNotify</emphasis> + event, it is supposed to call <emphasis> +XRefreshKeyboardMapping</emphasis> + to update the keyboard description used internally by the X library. +</para> + + +<para> +The X Keyboard Extension uses <emphasis> +XkbMapNotify</emphasis> + and <emphasis> +XkbNewKeyboardNotify</emphasis> + events to track changes to the keyboard mapping. When an Xkb-aware client +receives either event, it should call <emphasis> +XkbRefreshKeyboardMapping</emphasis> + to update the keyboard description used internally by the X library. To avoid +duplicate events, the X server does not send core protocol <emphasis> +MappingNotify</emphasis> + events to a client that has selected for <emphasis> +XkbMapNotify</emphasis> + events. +</para> + + +<para> +The implicit support for Xkb selects for <emphasis> +XkbMapNotify</emphasis> + 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 <emphasis> +MappingNotify</emphasis> + 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 <emphasis> +MappingNotify</emphasis> + events that report approximately the same information, unless the client has +explicitly selected for the Xkb version of the event. +</para> + + +<para> +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 <emphasis> +XkbNewKeyboardNotify</emphasis> + event, it reports events from all keys because it assumes that any client that +has receieved an <emphasis> +XkbNewKeyboardNotify</emphasis> + event expects key events from the new range of keycodes. The implicit support +for Xkb asks for <emphasis> +XkbNewKeyboardNotify</emphasis> + 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 +<emphasis> +XkbLC_IgnoreNewKeyboards</emphasis> + library control (see section 11.3.1) to prevent the implicit support from +requesting notification of changes to the legal range of keycodes. +</para> + + +</sect2> +<sect2 id='x_library_functions_affected_by_xkb'> +<title>X Library Functions Affected by Xkb</title> + +<para> +The following X library functions are modified by Xkb: +</para> + +<para><programlisting> + <emphasis>XKeycodeToKeysym</emphasis> + <emphasis>XKeysymToKeycode</emphasis> + <emphasis>XLookupKeysym</emphasis> + <emphasis>XLookupString</emphasis> + <emphasis>XRefreshKeyboardMapping</emphasis> + <emphasis>XRebindKeysym</emphasis> +</programlisting></para> + +<para> +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. +</para> + + +<para> +The <emphasis> +XKeycodeToKeysym</emphasis> + 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 <emphasis> +GetKeyboardMapping</emphasis> + 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. +</para> + + +<para> +The <emphasis> +XKeysymToKeycode</emphasis> + 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. +</para> + + +<para> +The <emphasis> +XLookupKeysym</emphasis> + 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. +</para> + + +<para> +The <emphasis> +XLookupString</emphasis> + 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, <emphasis> +XLookupString</emphasis> + uses the rules specified by the core protocol and reports only ISO Latin-1 +characters. When Xkb is present, <emphasis> +XLookupString</emphasis> + uses the explicit keyboard group, key types, and rules specified by Xkb. When +Xkb is present, <emphasis> +XLookupString</emphasis> + 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, +<emphasis> +XLookupString</emphasis> + does not use any consumed modifiers (see sections 11.1.2 and 15.2) to +determine matching bindings. +</para> + + +<para> +The <emphasis> +XRefreshKeyboardMapping</emphasis> + function updates the X library’s internal representation of the keyboard to +reflect changes reported via <emphasis> +MappingNotify</emphasis> + 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 <emphasis> +XkbMapNotify</emphasis> + event and updates only those pieces of the keyboard description that have +changed. If the implicit support has not noted any keyboard mapping changes, +<emphasis> +XRefreshKeyboardMapping</emphasis> + updates the entire keyboard description. +</para> + + +<para> +The <emphasis> +XRebindKeysym</emphasis> + 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 <emphasis> +XRebindKeysym</emphasis> +. When Xkb is missing or disabled, <emphasis> +XLookupString</emphasis> + 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. +</para> + + +</sect2> +</sect1> +<sect1 id='xkb_event_and_keymap_functions'> +<title>Xkb Event and Keymap Functions</title> + +<para> +To find the keysym bound to a particular key at a specified group and shift +level, use <emphasis>XkbKeycodeToKeysym</emphasis>. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +KeySym <emphasis> +XkbKeycodeToKeysym</emphasis> +(<emphasis> +dpy, kc, group, level</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * dpy; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +KeyCode kc; /* key of interest */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int group; /* group of interest */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int level; /* shift level of interest */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbKeycodeToKeysym</emphasis> + returns the keysym bound to a particular group and shift level for a +particular key on the core keyboard. If <emphasis> +kc</emphasis> + is not a legal keycode for the core keyboard, or if <emphasis> +group</emphasis> + or <emphasis> +level</emphasis> + are out of range for the specified key, <emphasis> +XkbKeycodeToKeysym</emphasis> + returns <emphasis> +NoSymbol</emphasis> +. +</para> + + +<para> +To find the set of modifiers bound to a particular keysym on the core keyboard, +use <emphasis> +XkbKeysymToModifiers</emphasis> +. +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +unsigned<emphasis> + </emphasis> +int <emphasis> +XkbKeysymToModifiers</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + ks</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display *<emphasis> + dpy</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +KeySym <emphasis> + ks</emphasis> +; /* keysym of interest */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbKeysymToModifiers</emphasis> + finds the set of modifiers currently bound to the keysym <emphasis> +ks</emphasis> + on the core keyboard. The value returned is the mask of modifiers bound to the +keysym <emphasis> +ks</emphasis> +. If no modifiers are bound to the keysym, <emphasis> +XkbKeysymToModifiers</emphasis> + returns zero; otherwise, it returns the inclusive OR of zero or more of the +following: <emphasis> +ShiftMask</emphasis> +, <emphasis> +ControlMask</emphasis> +, <emphasis> +LockMask</emphasis> +, <emphasis> +Mod1Mask</emphasis> +, <emphasis> +Mod2Mask</emphasis> +, <emphasis> +Mod3Mask</emphasis> +, <emphasis> +Mod4Mask,</emphasis> + and <emphasis> +Mod5Mask</emphasis> +. +</para> + + +<para> +Use <emphasis> +XkbLookupKeySym</emphasis> + to find the symbol associated with a key for a particular state. +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool <emphasis> +XkbLookupKeySym</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + key</emphasis> +,<emphasis> + state</emphasis> +,<emphasis> + mods_rtrn</emphasis> +,<emphasis> + sym_rtrn</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> + dpy</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +KeyCode <emphasis> + key</emphasis> +; /* key for which symbols are to be found */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> + state</emphasis> +; /* state for which symbol should be found */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int * <emphasis> + mods_rtrn</emphasis> +; /* backfilled with unconsumed modifiers */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +KeySym *<emphasis> + sym_rtrn</emphasis> +; /* backfilled with symbol associated with key + state */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbLookupKeySym</emphasis> + is the equivalent of the core <emphasis> +XLookupKeySym</emphasis> + function. For the core keyboard, given a keycode <emphasis> +key</emphasis> + and an Xkb state <emphasis> +state</emphasis> +, <emphasis> +XkbLookupKeySym</emphasis> + returns the symbol associated with the key in <emphasis> +sym_rtrn</emphasis> + and the list of modifiers that should still be applied in <emphasis> +mods_rtrn</emphasis> +. The <emphasis> +state</emphasis> + parameter is the state from a <emphasis> +KeyPress</emphasis> + or <emphasis> +KeyRelease</emphasis> + event. <emphasis> +XkbLookupKeySym</emphasis> + returns <emphasis> +True</emphasis> + if it succeeds. +</para> + + +<para> +Use <emphasis> +XkbLookupKeyBinding</emphasis> + to find the string bound to a key by <emphasis> +XRebindKeySym</emphasis> +. <emphasis> +XkbLookupKeyBinding</emphasis> + is the equivalent of the core <emphasis> +XLookupString</emphasis> + function. +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +int <emphasis> +XkbLookupKeyBinding</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + sym</emphasis> +,<emphasis> + state</emphasis> +,<emphasis> + buf</emphasis> +,<emphasis> + nbytes</emphasis> +,<emphasis> + extra_rtrn</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> + dpy</emphasis> +; /* connection to server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +KeySym<emphasis> + sym</emphasis> +; /* symbol to be looked up */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +state</emphasis> +; /* state for which string is to be looked up */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +char * <emphasis> + buf</emphasis> +; /* buffer into which returned string is written */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int <emphasis> + nbytes</emphasis> +; /* size of buffer in bytes */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> + extra_rtrn</emphasis> +; /* backfilled with number bytes overflow */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XRebindKeysym</emphasis> + 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. <emphasis> +XkbLookupKeyBinding</emphasis> + returns in <emphasis> +buf</emphasis> + the string associated with the keysym <emphasis> +sym</emphasis> + and modifier state <emphasis> +state</emphasis> +. <emphasis> +buf</emphasis> + is <emphasis> +NULL</emphasis> + terminated unless there’s an overflow. If the string returned is larger than +<emphasis> +nbytes</emphasis> +, a count of bytes that does not fit into the buffer is returned in extra_rtrn. +<emphasis> +XkbTranslateKeySym</emphasis> + returns the number of bytes that it placed into <emphasis> +buf</emphasis> +. +</para> + + +<para> +To find the string and symbol associated with a keysym for a given keyboard +state, use <emphasis> +XkbTranslateKeySym</emphasis> +. +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +int <emphasis> +XkbTranslateKeySym</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + sym_inout</emphasis> +,<emphasis> + mods</emphasis> +,<emphasis> + buf</emphasis> +,<emphasis> + nbytes</emphasis> +, <emphasis> +extra_rtrn</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> + dpy</emphasis> +; /* connection to X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +KeySym * <emphasis> + sym_inout</emphasis> +; /* symbol to be translated; result of translation */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> + mods</emphasis> +; /* modifiers to apply to <emphasis> +sym_inout</emphasis> + */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +char * <emphasis> + buf</emphasis> +; /* buffer into which returned string is written */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int <emphasis> + nbytes</emphasis> +; /* size of buffer in bytes */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int *<emphasis> + extra_rtrn</emphasis> +; /* number of bytes overflow*/ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbTranslateKeySym</emphasis> + applies the transformations specified in <emphasis> +mods</emphasis> + to the symbol specified by <emphasis> +sym_inout</emphasis> +. It returns in <emphasis> +buf</emphasis> + the string, if any, associated with the keysym for the current locale. If the +transformations in <emphasis> +mods</emphasis> + changes the keysym, <emphasis> +sym_inout</emphasis> + is updated accordingly. If the string returned is larger than <emphasis> +nbytes</emphasis> +, a count of bytes that does not fit into the buffer is returned in extra_rtrn. +<emphasis> +XkbTranslateKeySym</emphasis> + returns the number of bytes it placed into <emphasis> +buf</emphasis> +. +</para> + + +<para> +To update the keyboard description that is internal to the X library, use +<emphasis> +XkbRefreshKeyboardMapping</emphasis> +. +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Status <emphasis> +XkbRefreshKeyboardMapping</emphasis> +(<emphasis> +event)</emphasis> + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbMapNotifyEvent * <emphasis> + event</emphasis> +; /* event initiating remapping */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbRefreshKeyboardMapping</emphasis> + is the Xkb equivalent of the core <emphasis> +XRefreshKeyboardMapping</emphasis> + function. It requests that the X server send the current key mapping +information to this client. A client usually invokes <emphasis> +XkbRefreshKeyboardMapping</emphasis> + after receiving an <emphasis> +XkbMapNotify</emphasis> + event. <emphasis> +XkbRefreshKeyboardMapping</emphasis> + returns <emphasis> +Success</emphasis> + if it succeeds and <emphasis> +BadMatch</emphasis> + if the event is not an Xkb event. +</para> + + +<para> +The <emphasis> +XkbMapNotify</emphasis> + event can be generated when some client calls <emphasis> +XkbSetMap</emphasis> +, <emphasis> +XkbChangeMap</emphasis> +, <emphasis> +XkbGetKeyboardByName</emphasis> +, or any of the standard X library functions that change the keyboard mapping +or modifier mapping. +</para> + + +<para> +To translate a keycode to a key symbol and modifiers, use <emphasis> +XkbTranslateKeyCode</emphasis> +. +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Booll <emphasis> +XkbTranslateKeyCode</emphasis> +(<emphasis> +xkb, key, mods, mods_rtrn, keysym_rtrn)</emphasis> + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> +xkb</emphasis> +; /* keyboard description to use for translation */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +KeyCode <emphasis> +key</emphasis> +; /* keycode to translate */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +mods</emphasis> +; /* modifiers to apply when translating <emphasis> +key</emphasis> + */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int * <emphasis> +mods_rtrn</emphasis> +; /* backfilled with unconsumed modifiers */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +KeySym * <emphasis> +keysym_rtrn</emphasis> +; /* keysym resulting from translation */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +mods_rtrn</emphasis> + is backfilled with the modifiers consumed by the translation process. +<emphasis> +mods</emphasis> + is a bitwise inclusive OR of the legal modifier masks: <emphasis> +ShiftMask</emphasis> +, <emphasis> +LockMask</emphasis> +, <emphasis> +ControlMask</emphasis> +, <emphasis> +Mod1Mask</emphasis> +, <emphasis> +Mod2Mask</emphasis> +, <emphasis> +Mod3Mask</emphasis> +, <emphasis> +Mod4Mask</emphasis> +, <emphasis> +Mod5Mask</emphasis> +.The <emphasis> +AlwaysConsumeShiftAndLock</emphasis> + library control (see section 11.1.3), if enabled, causes <emphasis> +XkbTranslateKeyCode</emphasis> + to consume shift and lock.<emphasis> + XkbTranslateKeyCode</emphasis> + returns <emphasis> +True</emphasis> + if the translation resulted in a keysym, and <emphasis> +False</emphasis> + if it resulted in <emphasis> +NoSymbol</emphasis> +. +</para> +</sect1> +</chapter> |