diff options
Diffstat (limited to 'libX11/specs/XKB/ch12.xml')
| -rw-r--r-- | libX11/specs/XKB/ch12.xml | 1358 |
1 files changed, 698 insertions, 660 deletions
diff --git a/libX11/specs/XKB/ch12.xml b/libX11/specs/XKB/ch12.xml index 1a062014e..fcfa8f9f2 100644 --- a/libX11/specs/XKB/ch12.xml +++ b/libX11/specs/XKB/ch12.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Interpreting_Key_Events'> <title>Interpreting Key Events</title> @@ -11,12 +14,12 @@ several core X library functions. <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 +When support for Xkb is built into the X library, the +<function>XOpenDisplay</function> +function looks for a compatible version of Xkb on the server. If it finds a +compatible version, it initializes the extension and enables +<firstterm>implicit support</firstterm> +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 @@ -28,10 +31,10 @@ includes ways to control or disable it. <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 +Because +<function>XOpenDisplay</function> +initializes Xkb, some events contain an Xkb description of the keyboard state +instead of that normally used by the core protocol. See <link linkend="Xkb_State_to_Core_Protocol_State_Transformation">section 17.1.1</link> for more information about the differences between Xkb keyboard state and that reported by the core protocol. </para> @@ -41,50 +44,53 @@ by the core protocol. <sect2 id='Effects_of_Xkb_on_MappingNotify_Events'> <title>Effects of Xkb on MappingNotify Events</title> +<indexterm zone="Effects_of_Xkb_on_MappingNotify_Events"> +<primary>events</primary><secondary><symbol>MappingNotify</symbol></secondary></indexterm> + <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. +mapping using +<symbol>MappingNotify</symbol> +events. Whenever the keyboard mapping is changed, the server sends all clients +a +<symbol>MappingNotify</symbol> +event to report the change. When a client receives a +<symbol>MappingNotify</symbol> +event, it is supposed to call +<function>XRefreshKeyboardMapping</function> +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. +The X Keyboard Extension uses +<symbol>XkbMapNotify</symbol> +and +<symbol>XkbNewKeyboardNotify</symbol> +events to track changes to the keyboard mapping. When an Xkb-aware client +receives either event, it should call +<function>XkbRefreshKeyboardMapping</function> +to update the keyboard description used internally by the X library. To avoid +duplicate events, the X server does not send core protocol +<symbol>MappingNotify</symbol> +events to a client that has selected for +<symbol>XkbMapNotify</symbol> +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 +The implicit support for Xkb selects for +<symbol>XkbMapNotify</symbol> +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 +receive +<symbol>MappingNotify</symbol> +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 +converts them to +<symbol>MappingNotify</symbol> +events that report approximately the same information, unless the client has explicitly selected for the Xkb version of the event. </para> @@ -92,21 +98,20 @@ explicitly selected for the Xkb version of the event. <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 +an +<symbol>XkbNewKeyboardNotify</symbol> +event, it reports events from all keys because it assumes that any client that +has received an +<symbol>XkbNewKeyboardNotify</symbol> +event expects key events from the new range of keycodes. The implicit support +for Xkb asks for +<symbol>XkbNewKeyboardNotify</symbol> +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 +<symbol>XkbLC_IgnoreNewKeyboards</symbol> +library control (see <link linkend="IgnoreNewKeyboards">section 11.3.1</link>) to prevent the implicit support from requesting notification of changes to the legal range of keycodes. </para> @@ -117,16 +122,16 @@ requesting notification of changes to the legal range of keycodes. <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> + <simplelist type='vert' columns='1'> + <member><function>XKeycodeToKeysym</function></member> + <member><function>XKeysymToKeycode</function></member> + <member><function>XLookupKeysym</function></member> + <member><function>XLookupString</function></member> + <member><function>XRefreshKeyboardMapping</function></member> + <member><function>XRebindKeysym</function></member> + </simplelist> +</para> <para> The implicit support for Xkb replaces a number of X library functions with @@ -138,23 +143,25 @@ clients. </para> -<para> -The <emphasis> -XKeycodeToKeysym</emphasis> - function reports the keysym associated with a particular index for a single +<para id='XKeycodeToKeysym'> +The +<olink targetdoc='libX11' targetptr='XKeycodeToKeysym'><function>XKeycodeToKeysym</function></olink> +<indexterm significance="preferred" zone="XKeycodeToKeysym"><primary><function>XKeycodeToKeysym</function></primary></indexterm> +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 +is, as reported by the core protocol +<systemitem>GetKeyboardMapping</systemitem> +request). The order of the symbols in the core mapping does not necessarily +correspond to the order of the symbols used by Xkb; <link linkend="Xkb_Keyboard_Mapping_to_Core_Keyboard_Mapping_Transformations">section 17.1.3</link> describes the differences. </para> -<para> -The <emphasis> -XKeysymToKeycode</emphasis> - function reports a keycode to which a particular keysym is bound. When Xkb is +<para id='XKeysymToKeycode'> +The +<olink targetdoc='libX11' targetptr='XKeysymToKeycode'><function>XKeysymToKeycode</function></olink> +<indexterm significance="preferred" zone="XKeysymToKeycode"><primary><function>XKeysymToKeycode</function></primary></indexterm> +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 @@ -162,65 +169,67 @@ symbols instead. </para> -<para> -The <emphasis> -XLookupKeysym</emphasis> - function reports the symbol in a specific column of the key associated with an +<para id='XLookupKeysym'> +The +<olink targetdoc='libX11' targetptr='XLookupKeysym'><function>XLookupKeysym</function></olink> +<indexterm significance="preferred" zone="XLookupKeysym"><primary><function>XLookupKeysym</function></primary></indexterm> +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 +<para id='XLookupString'> +The +<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink> +<indexterm significance="preferred" zone="XLookupString"><primary><function>XLookupString</function></primary></indexterm> +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 +is disabled or missing, +<function>XLookupString</function> +uses the rules specified by the core protocol and reports only ISO Latin-1 +characters. When Xkb is present, +<function>XLookupString</function> +uses the explicit keyboard group, key types, and rules specified by Xkb. When +Xkb is present, +<function>XLookupString</function> +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 +<function>XLookupString</function> +does not use any consumed modifiers (see <link linkend="ConsumeLookupMods">section 11.1.2</link> and <link linkend="Key_Types">section 15.2</link>) 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 +<para id='XRefreshKeyboardMapping'> +The +<olink targetdoc='libX11' targetptr='XRefreshKeyboardMapping'><function>XRefreshKeyboardMapping</function></olink> +<indexterm significance="preferred" zone="XRefreshKeyboardMapping"><primary><function>XRefreshKeyboardMapping</function></primary></indexterm> +function updates the X library’s internal representation of the keyboard to +reflect changes reported via +<symbol>MappingNotify</symbol> +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 +keeps track of the changed components reported by each +<symbol>XkbMapNotify</symbol> +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. +<function>XRefreshKeyboardMapping</function> +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 +<para id='XRebindKeysym'> +The +<olink targetdoc='libX11' targetptr='XRebindKeysym'><function>XRebindKeysym</function></olink> +<indexterm significance="preferred" zone="XRebindKeysym"><primary><function>XRebindKeysym</function></primary></indexterm> +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 +reported in the event is compared to the state specified to +<function>XRebindKeysym</function>. +When Xkb is missing or disabled, +<function>XLookupString</function> +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> @@ -233,616 +242,645 @@ the keysym are consumed and are not used to look up the string. <para> To find the keysym bound to a particular key at a specified group and shift -level, use <emphasis>XkbKeycodeToKeysym</emphasis>. +level, use <function>XkbKeycodeToKeysym</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -KeySym <emphasis> -XkbKeycodeToKeysym</emphasis> -(<emphasis> -dpy, kc, group, level</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * dpy; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode kc; /* key of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int group; /* group of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int level; /* shift level of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbKeycodeToKeysym"><primary><function>XkbKeycodeToKeysym</function></primary></indexterm> +<funcsynopsis id="XkbKeycodeToKeysym"> + <funcprototype> + <funcdef>KeySym <function>XkbKeycodeToKeysym</function></funcdef> +<!-- ( +<parameter>dpy, kc, group, level</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeyCode <parameter>kc</parameter></paramdef> + <paramdef>unsigned int <parameter>group</parameter></paramdef> + <paramdef>unsigned int <parameter>level</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>kc</parameter> + </term> + <listitem> + <para> + key of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>group</parameter> + </term> + <listitem> + <para> + group of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>level</parameter> + </term> + <listitem> + <para> + shift level of interest + </para> + </listitem> + </varlistentry> +</variablelist> <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> -. +<function>XkbKeycodeToKeysym</function> +returns the keysym bound to a particular group and shift level for a +particular key on the core keyboard. If +<parameter>kc</parameter> +is not a legal keycode for the core keyboard, or if +<parameter>group</parameter> +or +<parameter>level</parameter> +are out of range for the specified key, +<function>XkbKeycodeToKeysym</function> +returns +<symbol>NoSymbol</symbol>. </para> <para> To find the set of modifiers bound to a particular keysym on the core keyboard, -use <emphasis> -XkbKeysymToModifiers</emphasis> -. +use +<function>XkbKeysymToModifiers</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned<emphasis> - </emphasis> -int <emphasis> -XkbKeysymToModifiers</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - ks</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym <emphasis> - ks</emphasis> -; /* keysym of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbKeysymToModifiers"><primary><function>XkbKeysymToModifiers</function></primary></indexterm> +<funcsynopsis id="XkbKeysymToModifiers"> + <funcprototype> + <funcdef>unsigned int <function>XkbKeysymToModifiers</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>ks</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeySym <parameter>ks</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ks</parameter> + </term> + <listitem> + <para> + keysym of interest + </para> + </listitem> + </varlistentry> +</variablelist> <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> -. +<function>XkbKeysymToModifiers</function> +finds the set of modifiers currently bound to the keysym +<parameter>ks</parameter> +on the core keyboard. The value returned is the mask of modifiers bound to the +keysym +<parameter>ks</parameter>. +If no modifiers are bound to the keysym, +<function>XkbKeysymToModifiers</function> +returns zero; otherwise, it returns the inclusive OR of zero or more of the +following: +<symbol>ShiftMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>Mod1Mask</symbol>, +<symbol>Mod2Mask</symbol>, +<symbol>Mod3Mask</symbol>, +<symbol>Mod4Mask</symbol>, +and +<symbol>Mod5Mask</symbol>. </para> <para> -Use <emphasis> -XkbLookupKeySym</emphasis> - to find the symbol associated with a key for a particular state. +Use +<function>XkbLookupKeySym</function> +to find the symbol associated with a key for a particular state. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <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> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> - key</emphasis> -; /* key for which symbols are to be found */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - state</emphasis> -; /* state for which symbol should be found */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> - mods_rtrn</emphasis> -; /* backfilled with unconsumed modifiers */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym *<emphasis> - sym_rtrn</emphasis> -; /* backfilled with symbol associated with key + state */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbLookupKeySym"><primary><function>XkbLookupKeySym</function></primary></indexterm> +<funcsynopsis id="XkbLookupKeySym"> + <funcprototype> + <funcdef>Bool <function>XkbLookupKeySym</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>key</parameter>, +<parameter>state</parameter>, +<parameter>mods_rtrn</parameter>, +<parameter>sym_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeyCode <parameter>key</parameter></paramdef> + <paramdef>unsigned int <parameter>state</parameter></paramdef> + <paramdef>unsigned int *<parameter>mods_rtrn</parameter></paramdef> + <paramdef>KeySym *<parameter>sym_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>key</parameter> + </term> + <listitem> + <para> + key for which symbols are to be found + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + state for which symbol should be found + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mods_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with unconsumed modifiers + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sym_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with symbol associated with key + state + </para> + </listitem> + </varlistentry> +</variablelist> <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. +<function>XkbLookupKeySym</function> +is the equivalent of the core +<symbol>XLookupKeySym</symbol> +function. For the core keyboard, given a keycode +<parameter>key</parameter> +and an Xkb state +<parameter>state</parameter>, +<function>XkbLookupKeySym</function> +returns the symbol associated with the key in +<parameter>sym_rtrn</parameter> +and the list of modifiers that should still be applied in +<parameter>mods_rtrn</parameter>. +The +<parameter>state</parameter> +parameter is the state from a +<symbol>KeyPress</symbol> +or +<symbol>KeyRelease</symbol> +event. +<function>XkbLookupKeySym</function> +returns +<symbol>True</symbol> +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. +Use +<function>XkbLookupKeyBinding</function> +to find the string bound to a key by +<function>XRebindKeysym</function>. +<function>XkbLookupKeyBinding</function> +is the equivalent of the core +<function>XLookupString</function> +function. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <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> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym<emphasis> - sym</emphasis> -; /* symbol to be looked up */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -state</emphasis> -; /* state for which string is to be looked up */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - buf</emphasis> -; /* buffer into which returned string is written */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - nbytes</emphasis> -; /* size of buffer in bytes */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> - extra_rtrn</emphasis> -; /* backfilled with number bytes overflow */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbLookupKeyBinding"><primary><function>XkbLookupKeyBinding</function></primary></indexterm> +<funcsynopsis id="XkbLookupKeyBinding"> + <funcprototype> + <funcdef>int <function>XkbLookupKeyBinding</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>sym</parameter>, +<parameter>state</parameter>, +<parameter>buf</parameter>, +<parameter>nbytes</parameter>, +<parameter>extra_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeySym <parameter>sym</parameter></paramdef> + <paramdef>unsigned int <parameter>state</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>nbytes</parameter></paramdef> + <paramdef>int *<parameter>extra_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sym</parameter> + </term> + <listitem> + <para> + symbol to be looked up + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + state for which string is to be looked up + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>buf</parameter> + </term> + <listitem> + <para> + buffer into which returned string is written + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>nbytes</parameter> + </term> + <listitem> + <para> + size of buffer in bytes + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>extra_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with number bytes overflow + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XRebindKeysym</emphasis> - binds an ASCII string to a specified keysym, so that the string and keysym are +<function>XRebindKeysym</function> +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> -. +being held down. +<function>XkbLookupKeyBinding</function> +returns in +<parameter>buf</parameter> +the string associated with the keysym +<parameter>sym</parameter> +and modifier state +<parameter>state</parameter>. +<parameter>buf</parameter> +is +<symbol>NULL</symbol> +terminated unless there’s an overflow. If the string returned is larger than +<parameter>nbytes</parameter>, +a count of bytes that does not fit into the buffer is returned in extra_rtrn. +<function>XkbTranslateKeySym</function> +returns the number of bytes that it placed into +<parameter>buf</parameter>. </para> <para> To find the string and symbol associated with a keysym for a given keyboard -state, use <emphasis> -XkbTranslateKeySym</emphasis> -. +state, use +<function>XkbTranslateKeySym</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <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> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym * <emphasis> - sym_inout</emphasis> -; /* symbol to be translated; result of translation */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - mods</emphasis> -; /* modifiers to apply to <emphasis> -sym_inout</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - buf</emphasis> -; /* buffer into which returned string is written */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - nbytes</emphasis> -; /* size of buffer in bytes */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int *<emphasis> - extra_rtrn</emphasis> -; /* number of bytes overflow*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbTranslateKeySym"><primary><function>XkbTranslateKeySym</function></primary></indexterm> +<funcsynopsis id="XkbTranslateKeySym"> + <funcprototype> + <funcdef>int <function>XkbTranslateKeySym</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>sym_inout</parameter>, +<parameter>mods</parameter>, +<parameter>buf</parameter>, +<parameter>nbytes</parameter>, +<parameter>extra_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeySym *<parameter>sym_inout</parameter></paramdef> + <paramdef>unsigned int <parameter>mods</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>nbytes</parameter></paramdef> + <paramdef>int *<parameter>extra_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sym_inout</parameter> + </term> + <listitem> + <para> + symbol to be translated; result of translation + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mods</parameter> + </term> + <listitem> + <para> + modifiers to apply to <parameter>sym_inout</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>buf</parameter> + </term> + <listitem> + <para> + buffer into which returned string is written + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>nbytes</parameter> + </term> + <listitem> + <para> + size of buffer in bytes + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>extra_rtrn</parameter> + </term> + <listitem> + <para> + number of bytes overflow + </para> + </listitem> + </varlistentry> +</variablelist> <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> -. +<function>XkbTranslateKeySym</function> +applies the transformations specified in +<parameter>mods</parameter> +to the symbol specified by +<parameter>sym_inout</parameter>. +It returns in +<parameter>buf</parameter> +the string, if any, associated with the keysym for the current locale. If the +transformations in +<parameter>mods</parameter> +changes the keysym, +<parameter>sym_inout</parameter> +is updated accordingly. If the string returned is larger than +<parameter>nbytes</parameter>, +a count of bytes that does not fit into the buffer is returned in extra_rtrn. +<function>XkbTranslateKeySym</function> +returns the number of bytes it placed into +<parameter>buf</parameter>. </para> <para> To update the keyboard description that is internal to the X library, use -<emphasis> -XkbRefreshKeyboardMapping</emphasis> -. +<function>XkbRefreshKeyboardMapping</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbRefreshKeyboardMapping</emphasis> -(<emphasis> -event)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbMapNotifyEvent * <emphasis> - event</emphasis> -; /* event initiating remapping */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbRefreshKeyboardMapping"><primary><function>XkbRefreshKeyboardMapping</function></primary></indexterm> +<funcsynopsis id="XkbRefreshKeyboardMapping"> + <funcprototype> + <funcdef>Status <function>XkbRefreshKeyboardMapping</function></funcdef> +<!-- ( +<parameter>event)</parameter> --> + + <paramdef>XkbMapNotifyEvent *<parameter>event</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>event</parameter> + </term> + <listitem> + <para> + event initiating remapping + </para> + </listitem> + </varlistentry> +</variablelist> <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. +<function>XkbRefreshKeyboardMapping</function> +is the Xkb equivalent of the core +<function>XRefreshKeyboardMapping</function> +function. It requests that the X server send the current key mapping +information to this client. A client usually invokes +<function>XkbRefreshKeyboardMapping</function> +after receiving an +<symbol>XkbMapNotify</symbol> +event. +<function>XkbRefreshKeyboardMapping</function> +returns +<symbol>Success</symbol> +if it succeeds and +<errorname>BadMatch</errorname> +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 +The +<symbol>XkbMapNotify</symbol> +event can be generated when some client calls +<function>XkbSetMap</function>, +<function>XkbChangeMap</function>, +<function>XkbGetKeyboardByName</function>, +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> -. +To translate a keycode to a key symbol and modifiers, use +<function>XkbTranslateKeyCode</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Booll <emphasis> -XkbTranslateKeyCode</emphasis> -(<emphasis> -xkb, key, mods, mods_rtrn, keysym_rtrn)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description to use for translation */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -key</emphasis> -; /* keycode to translate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -mods</emphasis> -; /* modifiers to apply when translating <emphasis> -key</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -mods_rtrn</emphasis> -; /* backfilled with unconsumed modifiers */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym * <emphasis> -keysym_rtrn</emphasis> -; /* keysym resulting from translation */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbTranslateKeyCode"><primary><function>XkbTranslateKeyCode</function></primary></indexterm> +<funcsynopsis id="XkbTranslateKeyCode"> + <funcprototype> + <funcdef>Bool <function>XkbTranslateKeyCode</function></funcdef> +<!-- ( +<parameter>xkb, key, mods, mods_rtrn, keysym_rtrn)</parameter> --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>key</parameter></paramdef> + <paramdef>unsigned int <parameter>mods</parameter></paramdef> + <paramdef>unsigned int *<parameter>mods_rtrn</parameter></paramdef> + <paramdef>KeySym *<parameter>keysym_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to use for translation + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>key</parameter> + </term> + <listitem> + <para> + keycode to translate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mods</parameter> + </term> + <listitem> + <para> + modifiers to apply when translating <parameter>key</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mods_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with unconsumed modifiers + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keysym_rtrn</parameter> + </term> + <listitem> + <para> + keysym resulting from translation + </para> + </listitem> + </varlistentry> +</variablelist> <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> -. +<parameter>mods_rtrn</parameter> +is backfilled with the modifiers consumed by the translation process. +<parameter>mods</parameter> +is a bitwise inclusive OR of the legal modifier masks: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol>, +<symbol>Mod2Mask</symbol>, +<symbol>Mod3Mask</symbol>, +<symbol>Mod4Mask</symbol>, +<symbol>Mod5Mask</symbol>. +The +<emphasis>AlwaysConsumeShiftAndLock</emphasis> +library control (see <link linkend="AlwaysConsumeShiftAndLock">section 11.1.3</link>), if enabled, causes +<function>XkbTranslateKeyCode</function> +to consume shift and lock. +<function>XkbTranslateKeyCode</function> +returns +<symbol>True</symbol> +if the translation resulted in a keysym, and +<symbol>False</symbol> +if it resulted in +<symbol>NoSymbol</symbol>. </para> </sect1> </chapter> |