aboutsummaryrefslogtreecommitdiff
path: root/libX11/specs/XKB/ch12.xml
diff options
context:
space:
mode:
Diffstat (limited to 'libX11/specs/XKB/ch12.xml')
-rw-r--r--libX11/specs/XKB/ch12.xml841
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>