diff options
Diffstat (limited to 'libX11/specs/XKB/ch16.xml')
| -rw-r--r-- | libX11/specs/XKB/ch16.xml | 6393 |
1 files changed, 3210 insertions, 3183 deletions
diff --git a/libX11/specs/XKB/ch16.xml b/libX11/specs/XKB/ch16.xml index 2640ea2dd..3f5e42f04 100644 --- a/libX11/specs/XKB/ch16.xml +++ b/libX11/specs/XKB/ch16.xml @@ -1,23 +1,33 @@ +<?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='Xkb_Server_Keyboard_Mapping'> <title>Xkb Server Keyboard Mapping</title> +<indexterm zone="Xkb_Server_Keyboard_Mapping"> +<primary>server map</primary></indexterm> +<indexterm zone="Xkb_Server_Keyboard_Mapping"> +<primary>map</primary><secondary>server</secondary></indexterm> + <para> -The <emphasis> -server</emphasis> - field of the complete Xkb keyboard description (see section 6.1) is a pointer +The +<structfield>server</structfield> +field of the complete Xkb keyboard description (see <link linkend="The_XkbDescRec_Structure">section 6.1</link>) is a pointer to the Xkb server map. </para> <para> -Figure 16.1 shows the relationships between elements in the server map: +<link linkend="figure16.1">Figure 16.1</link> shows the relationships between elements in the server map: </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-16.svg"/> - </imageobject> -<caption>Server Map Relationships</caption> - </mediaobject> +<figure id='figure16.1'> + <title>Server Map Relationships</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-16.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- @@ -25,51 +35,50 @@ Figure 16.1 shows the relationships between elements in the server map: Server Map Relationships</H5> --> -<para> +<para id='XkbServerMapRec'> +<indexterm significance="preferred" zone="XkbServerMapRec"> +<primary><structname>XkbServerMapRec</structname></primary></indexterm> The Xkb server map contains the information the server needs to interpret key -events and is of type <emphasis> -XkbServerMapRec</emphasis> -: -</para> +events and is of type +<structname>XkbServerMapRec</structname>: -<para><programlisting> +<programlisting> #define XkbNumVirtualMods 16 -</programlisting></para> -<para><programlisting> -typedef struct { /* Server Map */ - unsigned short num_acts; /* # of occupied entries in <emphasis> acts</emphasis> */ - unsigned short size_acts; /* # of entries in <emphasis> acts</emphasis> */ - XkbAction * acts; /* linear 2d tables of key actions, 1 per keycode */ - XkbBehavior * behaviors; /* key behaviors,1 per keycode */ - unsigned short * key_acts; /* index into <emphasis> acts</emphasis> , 1 per keycode */ - unsigned char * explicit; /* explicit overrides of core remapping, 1 per key */ - unsigned char vmods[XkbNumVirtualMods]; /* real mods bound to virtual mods */ - unsigned short * vmodmap; /* virtual mods bound to key, 1 per keycode*/ -} <emphasis>XkbServerMapRec</emphasis>, *XkbServerMapPtr; +typedef struct { /* Server Map */ + unsigned short num_acts; /* # of occupied entries in <structfield>acts</structfield> */ + unsigned short size_acts; /* # of entries in <structfield>acts</structfield> */ + XkbAction * acts; /* linear 2d tables of key actions, + 1 per keycode */ + XkbBehavior * behaviors; /* key behaviors, 1 per keycode */ + unsigned short * key_acts; /* index into <structfield>acts</structfield>, 1 per keycode */ + unsigned char * explicit; /* explicit overrides of core + remapping, 1 per key */ + unsigned char vmods[XkbNumVirtualMods]; /* real mods bound + to virtual mods */ + unsigned short * vmodmap; /* virtual mods bound to key, + 1 per keycode */ +} <structname>XkbServerMapRec</structname>, *XkbServerMapPtr; </programlisting></para> <para> -The <emphasis> -num_acts</emphasis> -, <emphasis> -size_acts</emphasis> -, <emphasis> -acts</emphasis> -, and <emphasis> -key_acts</emphasis> - fields specify the key actions, defined in section 16.1. The <emphasis> -behaviors</emphasis> - field describes the behavior for each key and is defined in section 16.2. The -<emphasis> -explicit</emphasis> - field describes the explicit components for a key and is defined in section -16.3. The <emphasis> -vmods</emphasis> - and the <emphasis> -vmodmap</emphasis> - fields describe the virtual modifiers and the per-key virtual modifier mapping -and are defined in section 16.4. +The +<structfield>num_acts</structfield>, +<structfield>size_acts</structfield>, +<structfield>acts</structfield>, +and +<structfield>key_acts</structfield> +fields specify the key actions, defined in <link linkend="Key_Actions">section 16.1</link>. The +<structfield>behaviors</structfield> +field describes the behavior for each key and is defined in <link linkend="Key_Behavior">section 16.2</link>. The +<structfield>explicit</structfield> +field describes the explicit components for a key and is defined in +<link linkend="Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">section 16.3</link>. The +<structfield>vmods</structfield> +and the +<structfield>vmodmap</structfield> +fields describe the virtual modifiers and the per-key virtual modifier mapping +and are defined in <link linkend="Virtual_Modifier_Mapping">section 16.4</link>. </para> <sect1 id='Key_Actions'> @@ -78,74 +87,71 @@ and are defined in section 16.4. <para> A key action defines the effect key presses and releases have on the internal state of the server. For example, the expected key action associated with -pressing the <emphasis> -Shift</emphasis> - key is to set the <emphasis> -Shift</emphasis> - modifier. There is zero or one key action associated with each keysym bound to +pressing the +<symbol>Shift</symbol> +key is to set the +<symbol>Shift</symbol> +modifier. There is zero or one key action associated with each keysym bound to each key. </para> <para> Just as the entire list of key symbols for the keyboard mapping is held in the -<emphasis> -syms</emphasis> - field of the client map, the entire list of key actions for the keyboard -mapping is held in the <emphasis> -acts</emphasis> - array of the server map. The total size of <emphasis> -acts</emphasis> - is specified by <emphasis> -size_acts</emphasis> -, and the number of entries is specified by <emphasis> -num_acts</emphasis>. -</para> - - -<para> -The <emphasis> -key_acts</emphasis> - array, indexed by keycode, describes the actions associated with a key. The -<emphasis> -key_acts</emphasis> - array has <emphasis> -min_key_code</emphasis> - unused entries at the start to allow direct indexing using a keycode. If a -<emphasis> -key_acts</emphasis> - entry is <emphasis> -zero</emphasis> -, it means the key does not have any actions associated with it. If an entry is -not <emphasis> -zero</emphasis> -, the entry represents an index into the <emphasis> -acts</emphasis> - field of the server map, much as the <emphasis> -offset</emphasis> - field of a <emphasis> -KeySymMapRec</emphasis> - structure is an index into the <emphasis> -syms</emphasis> - field of the client map. -</para> - -<para> -The reason the <emphasis> -acts</emphasis> - field is a linear list of <emphasis> -XkbAction</emphasis> -s is to reduce the memory consumption associated with a keymap. Because Xkb +<structfield>syms</structfield> +field of the client map, the entire list of key actions for the keyboard +mapping is held in the +<structfield>acts</structfield> +array of the server map. The total size of +<structfield>acts</structfield> +is specified by +<structfield>size_acts</structfield>, +and the number of entries is specified by +<structfield>num_acts</structfield>. +</para> + + +<para> +The +<structfield>key_acts</structfield> +array, indexed by keycode, describes the actions associated with a key. The +<structfield>key_acts</structfield> +array has +<structfield>min_key_code</structfield> +unused entries at the start to allow direct indexing using a keycode. If a +<structfield>key_acts</structfield> +entry is +<emphasis>zero</emphasis>, +it means the key does not have any actions associated with it. If an entry is +not +<emphasis>zero</emphasis>, +the entry represents an index into the +<structfield>acts</structfield> +field of the server map, much as the +<structfield>offset</structfield> +field of a +<structname>KeySymMapRec</structname> +structure is an index into the +<structfield>syms</structfield> +field of the client map. +</para> + +<para> +The reason the +<structfield>acts</structfield> +field is a linear list of +<structname>XkbAction</structname>s +is to reduce the memory consumption associated with a keymap. Because Xkb allows individual keys to have multiple shift levels and a different number of -groups per key, a single two-dimensional array of <emphasis> -KeySyms</emphasis> - would potentially be very large and sparse. Instead, Xkb provides a small -two-dimensional array of <emphasis> -XkbAction</emphasis> -s for each key. To store all of these individual arrays, Xkb concatenates each -array together in the <emphasis> -acts</emphasis> - field of the server map. +groups per key, a single two-dimensional array of +<type>KeySym</type>s +would potentially be very large and sparse. Instead, Xkb provides a small +two-dimensional array of +<structname>XkbAction</structname>s +for each key. To store all of these individual arrays, Xkb concatenates each +array together in the +<structfield>acts</structfield> +field of the server map. </para> @@ -163,290 +169,308 @@ Xkb provides the following macros, to simplify accessing information pertaining to key actions: </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> -XkbKeyHasActions</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyHasActions</emphasis> - returns <emphasis> -True</emphasis> - if the key corresponding to <emphasis> -keycode</emphasis> - has any actions associated with it; otherwise, it returns <emphasis> -False</emphasis> -. -</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> -XkbKeyNumActions</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyNumActions</emphasis> - computes the number of actions associated with the key corresponding to -<emphasis> -keycode</emphasis> -. This should be the same value as the result of <emphasis> -XkbKeyNumSyms</emphasis> - (see section 15.3.3). -</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'> -XkbKeyActionPtr <emphasis> -XkbKeyActionsPtr</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyActionsPtr</emphasis> - returns a pointer to the two-dimensional array of key actions associated with -the key corresponding to <emphasis> -keycode</emphasis> -. Use<emphasis> - XkbKeyActionsPtr</emphasis> - only if the key actually has some actions associated with it, that is, -<emphasis> -XkbKeyNumActions</emphasis> +<indexterm significance="preferred" zone="XkbKeyHasActions"><primary><function>XkbKeyHasActions</function></primary></indexterm> +<funcsynopsis id="XkbKeyHasActions"> + <funcprototype> + <funcdef>Bool <function>XkbKeyHasActions</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyHasActions</function> +returns +<symbol>True</symbol> +if the key corresponding to +<parameter>keycode</parameter> +has any actions associated with it; otherwise, it returns +<symbol>False</symbol>. +</para> + + +<indexterm significance="preferred" zone="XkbKeyNumActions"><primary><function>XkbKeyNumActions</function></primary></indexterm> +<funcsynopsis id="XkbKeyNumActions"> + <funcprototype> + <funcdef>int <function>XkbKeyNumActions</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyNumActions</function> +computes the number of actions associated with the key corresponding to +<parameter>keycode</parameter>. +This should be the same value as the result of +<function>XkbKeyNumSyms</function> +(see <link linkend="Key_Width">section 15.3.3</link>). +</para> + + +<indexterm significance="preferred" zone="XkbKeyActionsPtr"><primary><function>XkbKeyActionsPtr</function></primary></indexterm> +<funcsynopsis id="XkbKeyActionsPtr"> + <funcprototype> + <funcdef>XkbKeyActionPtr <function>XkbKeyActionsPtr</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyActionsPtr</function> +returns a pointer to the two-dimensional array of key actions associated with +the key corresponding to +<parameter>keycode</parameter>. +Use +<function>XkbKeyActionsPtr</function> +only if the key actually has some actions associated with it, that is, +<function>XkbKeyNumActions</function> (xkb, keycode) returns something greater than zero. </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'> -XkbAction <emphasis> -XkbKeyAction</emphasis> -(<emphasis> -xkb, keycode, idx</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -idx</emphasis> -; /* index for group and shift level */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbKeyAction"><primary><function>XkbKeyAction</function></primary></indexterm> +<funcsynopsis id="XkbKeyAction"> + <funcprototype> + <funcdef>XkbAction <function>XkbKeyAction</function></funcdef> +<!-- ( +<parameter>xkb, keycode, idx</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>int <parameter>idx</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>idx</parameter> + </term> + <listitem> + <para> + index for group and shift level + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbKeyAction</emphasis> - returns the key action indexed by <emphasis> -idx</emphasis> - in the two-dimensional array of key actions associated with the key -corresponding to <emphasis> -keycode</emphasis> -. <emphasis> -idx</emphasis> - may be computed from the group and shift level of interest as follows: +<function>XkbKeyAction</function> +returns the key action indexed by +<parameter>idx</parameter> +in the two-dimensional array of key actions associated with the key +corresponding to +<parameter>keycode</parameter>. +<parameter>idx</parameter> +may be computed from the group and shift level of interest as follows: </para> <literallayout> idx = group_index * key_width + shift_level </literallayout> -<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'> -XkbAction <emphasis> -XkbKeyActionEntry</emphasis> -(<emphasis> -xkb, keycode, shift, grp</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -shift</emphasis> -; /* shift level within group */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -grp</emphasis> -; /* group index for group of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbKeyActionEntry"><primary><function>XkbKeyActionEntry</function></primary></indexterm> +<funcsynopsis id="XkbKeyActionEntry"> + <funcprototype> + <funcdef>XkbAction <function>XkbKeyActionEntry</function></funcdef> +<!-- ( +<parameter>xkb, keycode, shift, grp</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>int <parameter>shift</parameter></paramdef> + <paramdef>int <parameter>grp</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>shift</parameter> + </term> + <listitem> + <para> + shift level within group + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>grp</parameter> + </term> + <listitem> + <para> + group index for group of interest + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbKeyActionEntry</emphasis> - returns the key action corresponding to group <emphasis> -grp</emphasis> - and shift level <emphasis> -lvl</emphasis> - from the two-dimensional table of key actions associated with the key -corresponding to <emphasis> -keycode</emphasis> -. +<function>XkbKeyActionEntry</function> +returns the key action corresponding to group +<parameter>grp</parameter> +and shift level +<parameter>shift</parameter> +from the two-dimensional table of key actions associated with the key +corresponding to +<parameter>keycode</parameter>. </para> <sect2 id='The_XkbAction_Structure'> <title>The XkbAction Structure</title> +<indexterm significance="preferred" zone="The_XkbAction_Structure"> +<primary><structname>XkbAction</structname></primary></indexterm> <para> -The description for an action is held in an <emphasis> -XkbAction</emphasis> - structure, which is a union of all possible Xkb action types: -</para> +The description for an action is held in an +<structname>XkbAction</structname> +structure, which is a union of all possible Xkb action types: -<para><programlisting> +<programlisting> typedef union _XkbAction { - XkbAnyAction any; - XkbModAction mods; - XkbGroupAction group; - XkbISOAction iso; - XkbPtrAction ptr; - XkbPtrBtnAction btn; - XkbPtrDfltAction dflt; - XkbSwitchScreenAction screen; - XkbCtrlsAction ctrls; - XkbMessageAction msg; - XkbRedirectKeyAction redirect; - XkbDeviceBtnAction devbtn; - XkbDeviceValuatorAction devval; - unsigned char type; -} <emphasis>XkbAction</emphasis>; + XkbAnyAction any; + XkbModAction mods; + XkbGroupAction group; + XkbISOAction iso; + XkbPtrAction ptr; + XkbPtrBtnAction btn; + XkbPtrDfltAction dflt; + XkbSwitchScreenAction screen; + XkbCtrlsAction ctrls; + XkbMessageAction msg; + XkbRedirectKeyAction redirect; + XkbDeviceBtnAction devbtn; + XkbDeviceValuatorAction devval; + unsigned char type; +} <structname>XkbAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field is provided for convenience and is the same as the type field in the +The +<structfield>type</structfield> +field is provided for convenience and is the same as the type field in the individual structures. The following sections describe the individual structures for each action in detail. </para> @@ -455,36 +479,36 @@ structures for each action in detail. </sect2> <sect2 id='The_XkbAnyAction_Structure'> <title>The XkbAnyAction Structure</title> +<indexterm significance="preferred" zone="The_XkbAnyAction_Structure"> +<primary><structname>XkbAnyAction</structname></primary></indexterm> <para> -The <emphasis> -XkbAnyAction</emphasis> - structure is a convenience structure that refers to any of the actions: -</para> +The +<structname>XkbAnyAction</structname> +structure is a convenience structure that refers to any of the actions: -<para><programlisting> +<programlisting> #define XkbAnyActionDataSize 7 -</programlisting></para> -<para><programlisting> typedef struct _XkbAnyAction { - unsigned char type; /* type of action; determines interpretation for data */ - unsigned char data[XkbAnyActionDataSize]; -} <emphasis>XkbAnyAction</emphasis>; + unsigned char type; /* type of action; determines interpretation for data */ + unsigned char data[XkbAnyActionDataSize]; +} <structname>XkbAnyAction</structname>; </programlisting></para> <para> -The <emphasis> -data</emphasis> - field represents a structure for an action, and its interpretation depends on -the <emphasis> -type</emphasis> - field. The valid values for the <emphasis> -type</emphasis> - field, and the data structures associated with them are shown in Table 16.1: +The +<structfield>data</structfield> +field represents a structure for an action, and its interpretation depends on +the +<structfield>type</structfield> +field. The valid values for the +<structfield>type</structfield> +field, and the data structures associated with them are shown in +<link linkend="table16.1">Table 16.1</link>: </para> -<table frame='topbot'> +<table id='table16.1' frame='topbot'> <title>Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -502,10 +526,10 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_NoAction</emphasis></entry> + <entry><symbol>XkbSA_NoAction</symbol></entry> <entry> -<emphasis>XkbSA_NoAction</emphasis> - means the server does not perform an action for the key; this action does not +<symbol>XkbSA_NoAction</symbol> +means the server does not perform an action for the key; this action does not have an associated data structure. </entry> <entry>any</entry> @@ -513,91 +537,91 @@ have an associated data structure. </row> <row> <entry> -<para><emphasis>XkbSA_SetMods</emphasis></para> -<para><emphasis>XkbSA_LatchMods</emphasis></para> -<para><emphasis>XkbSA_LockMods</emphasis></para> +<para><symbol>XkbSA_SetMods</symbol></para> +<para><symbol>XkbSA_LatchMods</symbol></para> +<para><symbol>XkbSA_LockMods</symbol></para> </entry> - <entry><para><emphasis>XkbModAction</emphasis></para></entry> + <entry><para><structname>XkbModAction</structname></para></entry> <entry>mods</entry> - <entry>16.1.3</entry> + <entry><link linkend="Actions_for_Changing_Modifiers_State">16.1.3</link></entry> </row> <row> <entry> -<para><emphasis>XkbSA_SetGroup</emphasis></para> -<para><emphasis>XkbSA_LatchGroup</emphasis></para> -<para><emphasis>XkbSA_LockGroup</emphasis></para> +<para><symbol>XkbSA_SetGroup</symbol></para> +<para><symbol>XkbSA_LatchGroup</symbol></para> +<para><symbol>XkbSA_LockGroup</symbol></para> </entry> - <entry><emphasis>XkbGroupAction</emphasis></entry> + <entry><structname>XkbGroupAction</structname></entry> <entry>group</entry> - <entry>16.1.4</entry> + <entry><link linkend="Actions_for_Changing_Group_State">16.1.4</link></entry> </row> <row> - <entry><emphasis>XkbSA_MovePtr</emphasis></entry> - <entry><emphasis>XkbPtrAction</emphasis></entry> + <entry><symbol>XkbSA_MovePtr</symbol></entry> + <entry><structname>XkbPtrAction</structname></entry> <entry>ptr</entry> - <entry>16.1.5</entry> + <entry><link linkend="Actions_for_Moving_the_Pointer">16.1.5</link></entry> </row> <row> <entry> -<para><emphasis>XKbSA_PtrBtn</emphasis></para> -<para><emphasis>XkbSA_LockPtrBtn</emphasis></para> +<para><symbol>XkbSA_PtrBtn</symbol></para> +<para><symbol>XkbSA_LockPtrBtn</symbol></para> </entry> - <entry><emphasis>XkbPtrBtnAction</emphasis></entry><entry>btn</entry> - <entry>16.1.6</entry> + <entry><structname>XkbPtrBtnAction</structname></entry><entry>btn</entry> + <entry><link linkend="Actions_for_Simulating_Pointer_Button_Press_and_Release">16.1.6</link></entry> </row> <row> - <entry><emphasis>XkbSA_SetPtrDflt</emphasis></entry> - <entry><emphasis>XkbPtrDfltAction</emphasis></entry> + <entry><symbol>XkbSA_SetPtrDflt</symbol></entry> + <entry><structname>XkbPtrDfltAction</structname></entry> <entry>dflt</entry> - <entry>16.1.7</entry> + <entry><link linkend="Actions_for_Changing_the_Pointer_Button_Simulated">16.1.7</link></entry> </row> <row> - <entry><emphasis>XkbSA_ISOLock</emphasis></entry> - <entry><emphasis>XkbISOAction</emphasis></entry> + <entry><symbol>XkbSA_ISOLock</symbol></entry> + <entry><structname>XkbISOAction</structname></entry> <entry>iso</entry> - <entry>16.1.8</entry> + <entry><link linkend="Actions_for_Locking_Modifiers_and_Group">16.1.8</link></entry> </row> <row> - <entry><emphasis>XkbSA_SwitchScreen</emphasis></entry> - <entry><emphasis>XkbSwitchScreenAction</emphasis></entry> + <entry><symbol>XkbSA_SwitchScreen</symbol></entry> + <entry><structname>XkbSwitchScreenAction</structname></entry> <entry>screen</entry> - <entry>16.1.9</entry> + <entry><link linkend="Actions_for_Changing_the_Active_Screen">16.1.9</link></entry> </row> <row> <entry> -<para><emphasis>XkbSA_SetControls</emphasis></para> -<para><emphasis>XkbSA_LockControls</emphasis></para> +<para><symbol>XkbSA_SetControls</symbol></para> +<para><symbol>XkbSA_LockControls</symbol></para> </entry> - <entry><emphasis>XkbCtrlsAction</emphasis></entry> + <entry><structname>XkbCtrlsAction</structname></entry> <entry>ctrls</entry> - <entry>16.1.10</entry> + <entry><link linkend="Actions_for_Changing_Boolean_Controls_State">16.1.10</link></entry> </row> <row> - <entry><emphasis>XkbSA_ActionMessage</emphasis></entry> - <entry><emphasis>XkbMessgeAction</emphasis></entry> + <entry><symbol>XkbSA_ActionMessage</symbol></entry> + <entry><structname>XkbMessageAction</structname></entry> <entry>msg</entry> - <entry>16.1.11</entry> + <entry><link linkend="Actions_for_Generating_Messages">16.1.11</link></entry> </row> <row> - <entry><emphasis>XkbSA_RedirectKey</emphasis></entry> - <entry><emphasis>XkbRedirectKeyAction</emphasis></entry> + <entry><symbol>XkbSA_RedirectKey</symbol></entry> + <entry><structname>XkbRedirectKeyAction</structname></entry> <entry>redirect</entry> - <entry>16.1.12</entry> + <entry><link linkend="Actions_for_Generating_a_Different_Keycode">16.1.12</link></entry> </row> <row> <entry> -<para><emphasis>XkbSA_DeviceBtn</emphasis></para> -<para><emphasis>XKbSA_LockDeviceBtn</emphasis></para> +<para><symbol>XkbSA_DeviceBtn</symbol></para> +<para><symbol>XkbSA_LockDeviceBtn</symbol></para> </entry> - <entry><emphasis>XkbDeviceBtnAction</emphasis></entry> + <entry><structname>XkbDeviceBtnAction</structname></entry> <entry>devbtn</entry> - <entry>16.1.13</entry> + <entry><link linkend="Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease">16.1.13</link></entry> </row> <row> - <entry><emphasis>XkbSA_DeviceValuator</emphasis></entry> - <entry><emphasis>XkbDeviceValuatorAction</emphasis></entry> + <entry><symbol>XkbSA_DeviceValuator</symbol></entry> + <entry><structname>XkbDeviceValuatorAction</structname></entry> <entry>devval</entry> - <entry>16.1.14</entry> + <entry><link linkend="Actions_for_Simulating_Events_from_Device_Valuators">16.1.14</link></entry> </row> </tbody> </tgroup> @@ -606,53 +630,63 @@ have an associated data structure. </sect2> <sect2 id='Actions_for_Changing_Modifiers_State'> <title>Actions for Changing Modifiers’ State</title> +<indexterm significance="preferred" zone="Actions_for_Changing_Modifiers_State"> +<primary><structname>XkbModAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbModAction</emphasis> - structure change the state of the modifiers when keys are pressed and released -(see Chapter 7 for a discussion of modifiers): -</para> +Actions associated with the +<structname>XkbModAction</structname> +structure change the state of the modifiers when keys are pressed and released +(see <xref linkend="Virtual_Modifiers" /> for a discussion of modifiers): -<para><programlisting> +<programlisting> typedef struct _XkbModAction { - unsigned char type; /* <emphasis> XkbSA_{Set|Latch|Lock}Mods</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis> , controls the effect on modifiers */ - unsigned char mask; /* same as <emphasis> mask</emphasis> field of a modifier description */ - unsigned char real_mods; /* same as <emphasis> real_mods</emphasis> field of a modifier description */ - unsigned char vmods1; /* derived from <emphasis> vmods</emphasis> field of a modifier description */ - unsigned char vmods2; /* derived from <emphasis> vmods</emphasis> field of a modifier description */ -} <emphasis>XkbModAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_{Set|Latch|Lock}Mods</symbol> */ + unsigned char flags; /* with <structfield>type</structfield>, controls the effect + on modifiers */ + unsigned char mask; /* same as <structfield>mask</structfield> field of + a modifier description */ + unsigned char real_mods; /* same as <structfield>real_mods</structfield> field of + a modifier description */ + unsigned char vmods1; /* derived from <structfield>vmods</structfield> field of + a modifier description */ + unsigned char vmods2; /* derived from <structfield>vmods</structfield> field of + a modifier description */ +} <structname>XkbModAction</structname>; </programlisting></para> <para> -In the following description, the term <emphasis> -action modifiers</emphasis> - means the real modifier bits associated with this action. Depending on the -value of <emphasis> -flags</emphasis> - (see Table 16.3), these are designated either in the <emphasis> -mask</emphasis> - field of the <emphasis> -XkbModAction</emphasis> - structure itself or the real modifiers bound to the key for which the action -is being used. In the latter case, this is the client <emphasis> -map</emphasis> --><emphasis> -modmap</emphasis> -[<emphasis> -keycode</emphasis> +In the following description, the term +<firstterm>action modifiers</firstterm> +<indexterm significance="preferred" zone="Actions_for_Changing_Modifiers_State"> +<primary>action modifiers</primary></indexterm> +<indexterm significance="preferred" zone="Actions_for_Changing_Modifiers_State"> +<primary>modifiers</primary><secondary>action</secondary></indexterm> +means the real modifier bits associated with this action. Depending on the +value of +<structfield>flags</structfield> +(see <link linkend="table16.3">Table 16.3</link>), +these are designated either in the +<structfield>mask</structfield> +field of the +<structname>XkbModAction</structname> +structure itself or the real modifiers bound to the key for which the action +is being used. In the latter case, this is the client +<structfield>map</structfield>-><structfield>modmap</structfield> +[ +<parameter>keycode</parameter> ] field. </para> <para> -The <emphasis> -type</emphasis> - field can have any of the values shown in Table 16.2. +The +<structfield>type</structfield> +field can have any of the values shown in +<link linkend="table16.2">Table 16.2</link>. </para> -<table frame='topbot'> +<table id='table16.2' frame='topbot'> <title>Modifier Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -666,7 +700,7 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_SetMods</emphasis></entry> + <entry><symbol>XkbSA_SetMods</symbol></entry> <entry> <itemizedlist> <listitem> @@ -683,78 +717,77 @@ provided no other key affecting the same modifiers is logically down. <listitem> <para> If no other keys are physically depressed when this key is released, and -<emphasis> -XkbSA_ClearLocks</emphasis> - is set in the <emphasis> -flags</emphasis> - field, the key release unlocks any action modifiers. +<symbol>XkbSA_ClearLocks</symbol> +is set in the +<structfield>flags</structfield> +field, the key release unlocks any action modifiers. </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LatchMods</emphasis></entry> + <entry><symbol>XkbSA_LatchMods</symbol></entry> <entry> <itemizedlist> <listitem> <para> -Key press and key release events have the same effect as for <emphasis> -XkbSA_SetMods</emphasis> -; if no keys are physically depressed when this key is released, key release +Key press and key release events have the same effect as for +<symbol>XkbSA_SetMods</symbol>; +if no keys are physically depressed when this key is released, key release events have the following additional effects: </para> </listitem> <listitem> <para> -Modifiers unlocked due to <emphasis> -XkbSA_ClearLocks</emphasis> - have no further effect. +Modifiers unlocked due to +<symbol>XkbSA_ClearLocks</symbol> +have no further effect. </para> </listitem> <listitem> <para> -If <emphasis> -XkbSA_LatchToLock</emphasis> - is set in the <emphasis> -flags</emphasis> - field, a key release locks and then unlatches any remaining action modifiers +If +<symbol>XkbSA_LatchToLock</symbol> +is set in the +<structfield>flags</structfield> +field, a key release locks and then unlatches any remaining action modifiers that are already latched. </para> </listitem> <listitem> <para> -A key release latches any action modifiers not used by the <emphasis> -XkbSA_ClearLocks</emphasis> - and <emphasis> -XkbSA_LatchToLock</emphasis> - flags. +A key release latches any action modifiers not used by the +<symbol>XkbSA_ClearLocks</symbol> +and +<symbol>XkbSA_LatchToLock</symbol> +flags. </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LockMods</emphasis></entry> + <entry><symbol>XkbSA_LockMods</symbol></entry> <entry> <itemizedlist> <listitem> <para> -A key press sets the base state of any action modifiers. If <emphasis> -XkbSA_LockNoLock</emphasis> - is set in the <emphasis> -flags</emphasis> - field, a key press also sets the locked state of any action modifiers. +A key press sets the base state of any action modifiers. If +<symbol>XkbSA_LockNoLock</symbol> +is set in the +<structfield>flags</structfield> +field, a key press also sets the locked state of any action modifiers. </para> </listitem> <listitem> <para> A key release clears any action modifiers in the keyboard’s base modifiers, -provided no other key that affects the same modifiers is down. If <emphasis> -XkbSA_LockNoUnlock</emphasis> - is not set in the <emphasis> -flags</emphasis> - field, and any of the action modifiers were locked before the corresponding +provided no other key that affects the same modifiers is down. If +<symbol>XkbSA_LockNoUnlock</symbol> +is not set in the +<structfield>flags</structfield> +field, and any of the action modifiers were locked before the corresponding key press occurred, a key release unlocks them. </para> </listitem> @@ -766,14 +799,15 @@ key press occurred, a key release unlocks them. </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.3. A general meaning is given in the table, but the exact meaning depends on -the action <emphasis>type</emphasis>. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.3">Table 16.3</link>. +A general meaning is given in the table, but the exact meaning depends on +the action <structfield>type</structfield>. </para> -<table frame='topbot'> +<table id='table16.3' frame='topbot'> <title>Modifier Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -787,50 +821,48 @@ the action <emphasis>type</emphasis>. </thead> <tbody> <row> - <entry><emphasis>XkbSA_UseModMapMods</emphasis></entry> + <entry><symbol>XkbSA_UseModMapMods</symbol></entry> <entry> If set, the action modifiers are determined by the modifiers bound by the modifier mapping of the key. Otherwise, the action modifiers are set to the -modifiers specified by the <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmod1</emphasis> -, and <emphasis> -vmod2</emphasis> - fields. +modifiers specified by the +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields. </entry> </row> <row> - <entry><emphasis>XkbSA_ClearLocks</emphasis></entry> + <entry><symbol>XkbSA_ClearLocks</symbol></entry> <entry> If set and no keys are physically depressed when this key transition occurs, the server unlocks any action modifiers. </entry> </row> <row> - <entry><emphasis>XkbSA_LatchToLock</emphasis></entry> + <entry><symbol>XkbSA_LatchToLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LatchMods</emphasis> -, the server locks the action modifiers if they are already latched. +If set, and the action type is +<symbol>XkbSA_LatchMods</symbol>, +the server locks the action modifiers if they are already latched. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockMods</emphasis> -, the server only unlocks the action modifiers. +If set, and the action type is +<symbol>XkbSA_LockMods</symbol>, +the server only unlocks the action modifiers. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry> -If set, and the action is <emphasis> -XkbSA_LockMods</emphasis> -, the server only locks the action modifiers. +If set, and the action is +<symbol>XkbSA_LockMods</symbol>, +the server only locks the action modifiers. </entry> </row> </tbody> @@ -838,177 +870,172 @@ XkbSA_LockMods</emphasis> </table> <para> -If <emphasis> -XkbSA_UseModMapMods</emphasis> - is not set in the <emphasis> -flags</emphasis> - field, the <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmods1</emphasis> -, and <emphasis> -vmods2 </emphasis> +If +<symbol>XkbSA_UseModMapMods</symbol> +is not set in the +<structfield>flags</structfield> +field, the +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> fields are used to determine the action modifiers. Otherwise they are ignored -and the modifiers bound to the key (client <emphasis> -map</emphasis> --><emphasis> -modmap</emphasis> -[<emphasis> -keycode</emphasis> +and the modifiers bound to the key (client +<structfield>map</structfield>-><structfield>modmap</structfield> +[ +<parameter>keycode</parameter> ]) are used instead. </para> <para> -The <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmods1</emphasis> -, and <emphasis> -vmods2</emphasis> - fields represent the components of an Xkb modifier description (see section -7.2). While the <emphasis> -mask</emphasis> - and <emphasis> -real_mods</emphasis> - fields correspond directly to the <emphasis> -mask</emphasis> - and <emphasis> -real_mods</emphasis> - fields of an Xkb modifier description, the <emphasis> -vmods1</emphasis> - and <emphasis> -vmods2</emphasis> - fields are combined to correspond to the <emphasis> -vmods</emphasis> - field of an Xkb modifier description. Xkb provides the following macros, to +The +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields represent the components of an Xkb modifier description +(see <link linkend="Modifier_Definitions">section 7.2</link>). While the +<structfield>mask</structfield> +and +<structfield>real_mods</structfield> +fields correspond directly to the +<structfield>mask</structfield> +and +<structfield>real_mods</structfield> +fields of an Xkb modifier description, the +<structfield>vmods1</structfield> +and +<structfield>vmods2</structfield> +fields are combined to correspond to the +<structfield>vmods</structfield> +field of an Xkb modifier description. Xkb provides the following macros, to convert between the two formats: </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 short <emphasis> -XkbModActionVMods</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action from which to extract virtual mods */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbModActionVMods</emphasis> - returns the <emphasis> -vmods1</emphasis> - and <emphasis> -vmods2</emphasis> - fields of <emphasis> -act</emphasis> - converted to the <emphasis> -vmods</emphasis> - format of an Xkb modifier description. -</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'> -void <emphasis> -XkbSetModActionVMods</emphasis> -(<emphasis> -act, vmods</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action in which to set vmods */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short <emphasis> -vmods</emphasis> -; /* virtual mods to set */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbModActionVMods"><primary><function>XkbModActionVMods</function></primary></indexterm> +<funcsynopsis id="XkbModActionVMods"> + <funcprototype> + <funcdef>unsigned short <function>XkbModActionVMods</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract virtual mods + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbModActionVMods</function> +returns the +<structfield>vmods1</structfield> +and +<structfield>vmods2</structfield> +fields of +<parameter>act</parameter> +converted to the +<structfield>vmods</structfield> +format of an Xkb modifier description. +</para> + + +<indexterm significance="preferred" zone="XkbSetModActionVMods"><primary><function>XkbSetModActionVMods</function></primary></indexterm> +<funcsynopsis id="XkbSetModActionVMods"> + <funcprototype> + <funcdef>void <function>XkbSetModActionVMods</function></funcdef> +<!-- ( +<parameter>act, vmods</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + <paramdef>unsigned short <parameter>vmods</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set vmods + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>vmods</parameter> + </term> + <listitem> + <para> + virtual mods to set + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSetModActionVMods</emphasis> - sets the <emphasis> -vmods1</emphasis> - and <emphasis> -vmods2</emphasis> - fields of <emphasis> -act</emphasis> - using the <emphasis> -vmods</emphasis> - format of an Xkb modifier description. +<function>XkbSetModActionVMods</function> +sets the +<structfield>vmods1</structfield> +and +<structfield>vmods2</structfield> +fields of +<parameter>act</parameter> +using the +<parameter>vmods</parameter> +format of an Xkb modifier description. </para> <note><para>Despite the fact that the first parameter of these two macros is of -type XkbAction, these macros may be used only with Actions of type <emphasis> -XkbModAction</emphasis> - and <emphasis> -XkbISOAction</emphasis> -.</para></note> +type XkbAction, these macros may be used only with Actions of type +<structname>XkbModAction</structname> +and +<structname>XkbISOAction</structname>. +</para></note> </sect2> <sect2 id='Actions_for_Changing_Group_State'> <title>Actions for Changing Group State</title> +<indexterm significance="preferred" zone="Actions_for_Changing_Group_State"> +<primary><structname>XkbGroupAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbGroupAction</emphasis> - structure change the current group state when keys are pressed and released -(see Chapter 5 for a description of groups and keyboard state): -</para> +Actions associated with the +<structname>XkbGroupAction</structname> +structure change the current group state when keys are pressed and released +(see <xref linkend="Keyboard_State" /> for a description of groups and keyboard state): -<para><programlisting> +<programlisting> typedef struct _XkbGroupAction { - unsigned char type; /* <emphasis> XkbSA_{Set|Latch|Lock}Group</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis> , controls the effect on groups */ - char group_XXX; /* represents a group index or delta */ -} <emphasis>XkbGroupAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_{Set|Latch|Lock}Group</symbol> */ + unsigned char flags; /* with <structfield>type</structfield> , controls the effect on groups */ + char group_XXX; /* represents a group index or delta */ +} <structname>XkbGroupAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field can have any of the following values: +The +<structfield>type</structfield> +field can have any of the following values: </para> -<table frame='topbot'> +<table id='table16.4' frame='topbot'> <title>Group Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1022,76 +1049,72 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_SetGroup</emphasis></entry> + <entry><symbol>XkbSA_SetGroup</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If the <emphasis> -XkbSA_GroupAbsolute</emphasis> - bit is set in the <emphasis> -flags</emphasis> - field, key press events change the base keyboard group to the group specified -by the <emphasis> -group_XXX</emphasis> - field. Otherwise, key press events change the base keyboard group by adding -the <emphasis> -group_XXX</emphasis> - field to the base keyboard group. In either case, the resulting effective +If the +<symbol>XkbSA_GroupAbsolute</symbol> +bit is set in the +<structfield>flags</structfield> +field, key press events change the base keyboard group to the group specified +by the +<structfield>group_XXX</structfield> +field. Otherwise, key press events change the base keyboard group by adding +the +<structfield>group_XXX</structfield> +field to the base keyboard group. In either case, the resulting effective keyboard group is brought back into range depending on the value of the -<emphasis> -groups_wrap</emphasis> - field of the controls structure (see section 10.7.1). +<structfield>groups_wrap</structfield> +field of the controls structure (see <link linkend="The_GroupsWrap_Control">section 10.7.1</link>). </para> </listitem> <listitem> <para> -If a key with an <emphasis> -XkbSA_ISOLock</emphasis> - action (see section 16.1.8) is pressed while this key is down, the key release +If a key with an +<symbol>XkbSA_ISOLock</symbol> +action (see <link linkend="Actions_for_Locking_Modifiers_and_Group">section 16.1.8</link>) is pressed while this key is down, the key release of this key has no effect. Otherwise, the key release cancels the effects of the key press. </para> </listitem> <listitem> <para> -If the <emphasis> -XkbSA_ClearLocks</emphasis> - bit is set in the flags field, and no keys are physically depressed when this +If the +<symbol>XkbSA_ClearLocks</symbol> +bit is set in the flags field, and no keys are physically depressed when this key is released, the key release also sets the locked keyboard group to -<emphasis> -Group1</emphasis> -. - </para> +<emphasis>Group1</emphasis>. +</para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LatchGroup</emphasis></entry> + <entry><symbol>XkbSA_LatchGroup</symbol></entry> <entry> <itemizedlist> <listitem> <para> -Key press and key release events have the same effect as for <emphasis> -XkbSA_SetGroup</emphasis> -; if no keys are physically depressed when this key is released, key release +Key press and key release events have the same effect as for +<symbol>XkbSA_SetGroup</symbol>; +if no keys are physically depressed when this key is released, key release events have the following additional effects. </para> </listitem> <listitem> <para> -If the <emphasis> -XkbSA_LatchToLock</emphasis> - bit is set in the <emphasis> -flags</emphasis> - field and the latched keyboard group index is nonzero, the key release adds +If the +<symbol>XkbSA_LatchToLock</symbol> +bit is set in the +<structfield>flags</structfield> +field and the latched keyboard group index is nonzero, the key release adds the delta applied by the corresponding key press to the locked keyboard group and subtracts it from the latched keyboard group. The locked and effective keyboard group are brought back into range according to the value of the -<emphasis> -groups_wrap</emphasis> - field of the controls structure. +<structfield>groups_wrap</structfield> +field of the controls structure. </para> </listitem> <listitem> @@ -1103,25 +1126,25 @@ Otherwise, the key press adds the key press delta to the latched keyboard group. </entry> </row> <row> - <entry><emphasis>XkbSA_LockGroup</emphasis></entry> + <entry><symbol>XkbSA_LockGroup</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If the <emphasis> -XkbSA_GroupAbsolute</emphasis> - is set in the <emphasis> -flags</emphasis> - field, key press events set the locked keyboard group to the group specified -by the <emphasis> -group_XXX</emphasis> - field. Otherwise, key press events add the group specified by the <emphasis> -group_XXX</emphasis> - field to the locked keyboard group. In either case, the resulting locked and +If the +<symbol>XkbSA_GroupAbsolute</symbol> +is set in the +<structfield>flags</structfield> +field, key press events set the locked keyboard group to the group specified +by the +<structfield>group_XXX</structfield> +field. Otherwise, key press events add the group specified by the +<structfield>group_XXX</structfield> +field to the locked keyboard group. In either case, the resulting locked and effective keyboard groups are brought back into range depending on the value of -the <emphasis> -groups_wrap</emphasis> - field of the controls structure. +the +<structfield>groups_wrap</structfield> +field of the controls structure. </para> </listitem> <listitem> @@ -1137,16 +1160,16 @@ A key release has no effect. </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.5. A general meaning is given in the table, but the exact meaning depends on -the action <emphasis> -type</emphasis> -. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.5">Table 16.5</link>. +A general meaning is given in the table, but the exact meaning depends on +the action +<structfield>type</structfield>. </para> -<table frame='topbot'> +<table id='table16.5' frame='topbot'> <title>Group Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1160,28 +1183,28 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_ClearLocks</emphasis></entry> + <entry><symbol>XkbSA_ClearLocks</symbol></entry> <entry> If set and no keys are physically depressed when this key transition occurs, -the server sets the locked keyboard group to <emphasis> -Group1</emphasis> - on a key release. +the server sets the locked keyboard group to +<emphasis>Group1</emphasis> +on a key release. </entry> </row> <row> - <entry><emphasis>XkbSA_LatchToLock</emphasis></entry> + <entry><symbol>XkbSA_LatchToLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -SA_LatchGroup</emphasis> -, the server locks the action group if it is already latched. +If set, and the action type is +<symbol>XkbSA_LatchGroup</symbol>, +the server locks the action group if it is already latched. </entry> </row> <row> - <entry><emphasis>XkbSA_GroupAbsolute</emphasis></entry> + <entry><symbol>XkbSA_GroupAbsolute</symbol></entry> <entry> -If set, the <emphasis> -group_XXX</emphasis> - field represents an absolute group number. Otherwise, it represents a group +If set, the +<structfield>group_XXX</structfield> +field represents an absolute group number. Otherwise, it represents a group delta to be added to the current group to determine the new group number. </entry> </row> @@ -1190,170 +1213,168 @@ delta to be added to the current group to determine the new group number. </table> <para> -The <emphasis> -group_XXX</emphasis> - field represents a signed character. Xkb provides the following macros to +The +<structfield>group_XXX</structfield> +field represents a signed character. Xkb provides the following macros to convert between a signed integer value and a signed character: </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> -XkbSAGroup</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action from which to extract group */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSAGroup</emphasis> - returns the <emphasis> -group_XXX</emphasis> - field of <emphasis> -act</emphasis> - converted to a signed int. -</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'> -void <emphasis> -XkbSASetGroup</emphasis> -(<emphasis> -act, grp</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action from which to set group */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -grp</emphasis> -; /* group index to set in <emphasis> -group_XXX</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSAGroup"><primary><function>XkbSAGroup</function></primary></indexterm> +<funcsynopsis id="XkbSAGroup"> + <funcprototype> + <funcdef>int <function>XkbSAGroup</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract group + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSAGroup</function> +returns the +<structfield>group_XXX</structfield> +field of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbSASetGroup"><primary><function>XkbSASetGroup</function></primary></indexterm> +<funcsynopsis id="XkbSASetGroup"> + <funcprototype> + <funcdef>void <function>XkbSASetGroup</function></funcdef> +<!-- ( +<parameter>act, grp</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>grp</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to set group + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>grp</parameter> + </term> + <listitem> + <para> + group index to set in <structfield>group_XXX</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSASetGroup</emphasis> - sets the <emphasis> -group_XXX</emphasis> - field of <emphasis> -act</emphasis> - from the group index <emphasis> -grp</emphasis> -. +<function>XkbSASetGroup</function> +sets the +<structfield>group_XXX</structfield> +field of +<parameter>act</parameter> +from the group index +<parameter>grp</parameter>. </para> <note><para>Despite the fact that the first parameter of these two macros is of -type XkbAction, these macros may only be used with Actions of type <emphasis> -XkbGroupAction</emphasis> - and <emphasis> -XkbISOAction</emphasis> -.</para></note> +type XkbAction, these macros may only be used with Actions of type +<structname>XkbGroupAction</structname> +and +<structname>XkbISOAction</structname>. +</para></note> </sect2> <sect2 id='Actions_for_Moving_the_Pointer'> <title>Actions for Moving the Pointer</title> +<indexterm significance="preferred" zone="Actions_for_Moving_the_Pointer"> +<primary><structname>XkbPtrAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbPtrAction</emphasis> - structure move the pointer when keys are pressed and released: -</para> +Actions associated with the +<structname>XkbPtrAction</structname> +structure move the pointer when keys are pressed and released: -<para><programlisting> +<programlisting> typedef struct _XkbPtrAction { - unsigned char type; /* <emphasis> XkbSA_MovePtr</emphasis> */ - unsigned char flags; /* determines type of pointer motion */ - unsigned char high_XXX; /* x coordinate, high bits*/ - unsigned char low_XXX; /* y coordinate, low bits */ - unsigned char high_YYY; /* x coordinate, high bits */ - unsigned char low_YYY; /* y coordinate, low bits */ -} <emphasis>XkbPtrAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_MovePtr</symbol> */ + unsigned char flags; /* determines type of pointer motion */ + unsigned char high_XXX; /* x coordinate, high bits */ + unsigned char low_XXX; /* y coordinate, low bits */ + unsigned char high_YYY; /* x coordinate, high bits */ + unsigned char low_YYY; /* y coordinate, low bits */ +} <structname>XkbPtrAction</structname>; </programlisting></para> <para> -If the <emphasis> -MouseKeys</emphasis> - control is not enabled (see section 10.5.1), <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events are treated as though the action is <emphasis> -XkbSA_NoAction</emphasis>. +If the +<emphasis>MouseKeys</emphasis> +control is not enabled (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>), +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events are treated as though the action is +<symbol>XkbSA_NoAction</symbol>. </para> <para> -If the <emphasis> -MouseKeys</emphasis> - control is enabled, a server action of type <emphasis> -XkbSA_MovePtr</emphasis> - instructs the server to generate core pointer <emphasis> -MotionNotify</emphasis> - events rather than the usual <emphasis> -KeyPress</emphasis> - event, and the corresponding <emphasis> -KeyRelease</emphasis> - event disables any mouse keys timers that were created as a result of handling -the <emphasis> -XkbSA_MovePtr</emphasis> - action. +If the +<emphasis>MouseKeys</emphasis> +control is enabled, a server action of type +<symbol>XkbSA_MovePtr</symbol> +instructs the server to generate core pointer +<symbol>MotionNotify</symbol> +events rather than the usual +<symbol>KeyPress</symbol> +event, and the corresponding +<symbol>KeyRelease</symbol> +event disables any mouse keys timers that were created as a result of handling +the +<symbol>XkbSA_MovePtr</symbol> +action. </para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbPtrAction</emphasis> - structure is always <emphasis> -XkbSA_MovePtr</emphasis> -. +The +<structfield>type</structfield> +field of the +<structname>XkbPtrAction</structname> +structure is always +<symbol>XkbSA_MovePtr</symbol>. </para> <para> -The <emphasis> -flags</emphasis> - field is a bitwise inclusive OR of the masks shown in Table 16.6. +The +<structfield>flags</structfield> +field is a bitwise inclusive OR of the masks shown in +<link linkend="table16.6">Table 16.6</link>. </para> -<table frame='topbot'> +<table id='table16.6' frame='topbot'> <title>Pointer Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1367,25 +1388,25 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_NoAcceleration</emphasis></entry> + <entry><symbol>XkbSA_NoAcceleration</symbol></entry> <entry> -If not set, and the <emphasis> -MouseKeysAccel</emphasis> - control is enabled (see section 10.5.2), the <emphasis> -KeyPress</emphasis> - initiates a mouse keys timer for this key; every time the timer expires, the +If not set, and the +<emphasis>MouseKeysAccel</emphasis> +control is enabled (see <link linkend="The_MouseKeysAccel_Control">section 10.5.2</link>), the +<symbol>KeyPress</symbol> +initiates a mouse keys timer for this key; every time the timer expires, the cursor moves. </entry> </row> <row> - <entry><emphasis>XkbSA_MoveAbsoluteX</emphasis></entry> + <entry><symbol>XkbSA_MoveAbsoluteX</symbol></entry> <entry>If set, the X portion of the structure specifies the new pointer X coordinate. Otherwise, the X portion is added to the current pointer X coordinate to determine the new pointer X coordinate. </entry> </row> <row> - <entry><emphasis>XkbSA_MoveAbsoluteY</emphasis></entry> + <entry><symbol>XkbSA_MoveAbsoluteY</symbol></entry> <entry> If set, the Y portion of the structure specifies the new pointer Y coordinate. Otherwise, the Y portion is added @@ -1397,231 +1418,231 @@ to the current pointer Y coordinate to determine the new pointer Y coordinate. </table> <para> -Each of the X and Y coordinantes of the <emphasis> -XkbPtrAction</emphasis> - structure is composed of two signed 16-bit values, that is, the X coordinate -is composed of <emphasis> -high_XXX</emphasis> - and <emphasis> -low_XXX</emphasis> -, and similarly for the Y coordinate. Xkb provides the following macros, to -convert between a signed integer and two signed 16-bit values in <emphasis> -XkbPtrAction</emphasis> - structures: -</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> -XkbPtrActionX</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrAction <emphasis> -act</emphasis> -; /* action from which to extract X */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbPtrActionX</emphasis> - returns the <emphasis> -high_XXX</emphasis> - and <emphasis> -low_XXX</emphasis> - fields of <emphasis> -act</emphasis> - converted to a signed int. -</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> -XkbPtrActionY</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrAction <emphasis> -act</emphasis> -; /* action from which to extract Y */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbPtrActionY</emphasis> - returns the <emphasis> -high_YYY</emphasis> - and <emphasis> -low_YYY</emphasis> - fields of <emphasis> -act</emphasis> - converted to a signed int. -</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'> -void <emphasis> -XkbSetPtrActionX</emphasis> -(<emphasis> -act</emphasis> -, <emphasis> -x</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrAction <emphasis> -act</emphasis> -; /* action in which to set X */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -x; </emphasis> - /* new value to set */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetPtrActionX</emphasis> - sets the <emphasis> -high_XXX</emphasis> - and <emphasis> -low_XXX</emphasis> - fields of <emphasis> -act</emphasis> - from the signed integer value <emphasis> -x</emphasis> -. -</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'> -void <emphasis> -XkbSetPtrActionY</emphasis> -(<emphasis> -act, y</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrAction <emphasis> -act</emphasis> -; /* action in which to set Y */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -y</emphasis> -; /* new value to set */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +Each of the X and Y coordinates of the +<structname>XkbPtrAction</structname> +structure is composed of two signed 16-bit values, that is, the X coordinate +is composed of +<structfield>high_XXX</structfield> +and +<structfield>low_XXX</structfield>, +and similarly for the Y coordinate. Xkb provides the following macros, to +convert between a signed integer and two signed 16-bit values in +<structname>XkbPtrAction</structname> +structures: +</para> + +<indexterm significance="preferred" zone="XkbPtrActionX"><primary><function>XkbPtrActionX</function></primary></indexterm> +<funcsynopsis id="XkbPtrActionX"> + <funcprototype> + <funcdef>int <function>XkbPtrActionX</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbPtrAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract X + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbPtrActionX</function> +returns the +<structfield>high_XXX</structfield> +and +<structfield>low_XXX</structfield> +fields of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbPtrActionY"><primary><function>XkbPtrActionY</function></primary></indexterm> +<funcsynopsis id="XkbPtrActionY"> + <funcprototype> + <funcdef>int <function>XkbPtrActionY</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbPtrAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract Y + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbPtrActionY</function> +returns the +<structfield>high_YYY</structfield> +and +<structfield>low_YYY</structfield> +fields of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbSetPtrActionX"><primary><function>XkbSetPtrActionX</function></primary></indexterm> +<funcsynopsis id="XkbSetPtrActionX"> + <funcprototype> + <funcdef>void <function>XkbSetPtrActionX</function></funcdef> +<!-- ( +<parameter>act</parameter>, +<parameter>x</parameter> +) /* macro */ --> + + <paramdef>XkbPtrAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>x</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set X + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>x</parameter> + </term> + <listitem> + <para> + new value to set + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetPtrActionX</function> +sets the +<structfield>high_XXX</structfield> +and +<structfield>low_XXX</structfield> +fields of +<parameter>act</parameter> +from the signed integer value +<parameter>x</parameter>. +</para> + + +<indexterm significance="preferred" zone="XkbSetPtrActionY"><primary><function>XkbSetPtrActionY</function></primary></indexterm> +<funcsynopsis id="XkbSetPtrActionY"> + <funcprototype> + <funcdef>void <function>XkbSetPtrActionY</function></funcdef> +<!-- ( +<parameter>act, y</parameter> +) /* macro */ --> + + <paramdef>XkbPtrAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>y</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set Y + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>y</parameter> + </term> + <listitem> + <para> + new value to set + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSetPtrActionX</emphasis> - sets the <emphasis> -high_YYY</emphasis> - and <emphasis> -low_YYY</emphasis> - fields of <emphasis> -act</emphasis> - from the signed integer value <emphasis> -y</emphasis> -. +<function>XkbSetPtrActionX</function> +sets the +<structfield>high_YYY</structfield> +and +<structfield>low_YYY</structfield> +fields of +<parameter>act</parameter> +from the signed integer value +<parameter>y</parameter>. </para> </sect2> <sect2 id='Actions_for_Simulating_Pointer_Button_Press_and_Release'> <title>Actions for Simulating Pointer Button Press and Release</title> +<indexterm significance="preferred" zone="Actions_for_Simulating_Pointer_Button_Press_and_Release"> +<primary><structname>XkbPtrBtnAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbPtrBtnAction</emphasis> - structure simulate the press and release of pointer buttons when keys are +Actions associated with the +<structname>XkbPtrBtnAction</structname> +structure simulate the press and release of pointer buttons when keys are pressed and released: -</para> -<para><programlisting> +<programlisting> typedef struct _XkbPtrBtnAction { - unsigned char type; /*<emphasis> XkbSA_PtrBtn, XkbSA_LockPtrBtn</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis> , controls the effect on pointer buttons*/ - unsigned char count; /* controls number of ButtonPress and ButtonRelease events */ - unsigned char button; /* pointer button to simulate */ -} <emphasis>XkbPtrBtnAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_PtrBtn</symbol>, <symbol>XkbSA_LockPtrBtn</symbol> */ + unsigned char flags; /* with <structfield>type</structfield>, controls the effect + on pointer buttons */ + unsigned char count; /* controls number of ButtonPress and + ButtonRelease events */ + unsigned char button; /* pointer button to simulate */ +} <structname>XkbPtrBtnAction</structname>; </programlisting></para> <para> -If the <emphasis> -MouseKeys</emphasis> - (see section 10.5.1) control is not enabled, <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events are treated as though the action is <emphasis> -XkbSA_NoAction</emphasis> -. +If the +<emphasis>MouseKeys</emphasis> +(see <link linkend="The_MouseKeys_Control">section 10.5.1</link>) control is not enabled, +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events are treated as though the action is +<symbol>XkbSA_NoAction</symbol>. </para> <para> -The <emphasis> -type</emphasis> - field can have any one of the values shown in Table 16.7. +The +<structfield>type</structfield> +field can have any one of the values shown in +<link linkend="table16.7">Table 16.7</link>. </para> -<table frame='topbot'> +<table id='table16.7' frame='topbot'> <title>Pointer Button Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1635,24 +1656,23 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_PtrBtn</emphasis></entry> + <entry><symbol>XkbSA_PtrBtn</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If<emphasis> - XkbSA_UseDfltButton</emphasis> - is set in the <emphasis> -flags</emphasis> - field, the event is generated for the pointer button specified by the -<emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control (see section 10.5.1). Otherwise, the event is generated for the button -specified by the <emphasis> -button</emphasis> - field. +If +<symbol>XkbSA_UseDfltButton</symbol> +is set in the +<structfield>flags</structfield> +field, the event is generated for the pointer button specified by the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>). Otherwise, the event is generated for the button +specified by the +<structfield>button</structfield> +field. </para> </listitem> <listitem> @@ -1660,83 +1680,81 @@ button</emphasis> If the mouse button specified for this action is logically down, the key press and corresponding key release are ignored and have no effect. Otherwise, a key press causes one or more core pointer button events instead of the usual -<emphasis> -KeyPress</emphasis> - event. If <emphasis> -count</emphasis> - is <emphasis> -zero</emphasis> -, a key press generates a single <emphasis> -ButtonPress</emphasis> - event; if <emphasis> -count</emphasis> - is greater than <emphasis> -zero</emphasis> -, a key press generates <emphasis> -count</emphasis> - pairs of <emphasis> -ButtonPress</emphasis> - and <emphasis> -ButtonRelease</emphasis> - events. +<symbol>KeyPress</symbol> +event. If +<structfield>count</structfield> +is +<emphasis>zero</emphasis>, +a key press generates a single +<symbol>ButtonPress</symbol> +event; if +<structfield>count</structfield> +is greater than +<emphasis>zero</emphasis>, +a key press generates +<structfield>count</structfield> +pairs of +<symbol>ButtonPress</symbol> +and +<symbol>ButtonRelease</symbol> +events. </para> </listitem> <listitem> <para> -If <emphasis> -count</emphasis> - is <emphasis> -zero</emphasis> -, a key release generates a core pointer <emphasis> -ButtonRelease</emphasis> - that matches the event generated by the corresponding <emphasis> -KeyPress</emphasis> -; if <emphasis> -count</emphasis> - is nonzero, a key release does not cause a <emphasis> -ButtonRelease</emphasis> - event. A key release never generates a key <emphasis> -KeyRelease</emphasis> - event. +If +<structfield>count</structfield> +is +<emphasis>zero</emphasis>, +a key release generates a core pointer +<symbol>ButtonRelease</symbol> +that matches the event generated by the corresponding +<symbol>KeyPress</symbol>; +if +<structfield>count</structfield> +is nonzero, a key release does not cause a +<symbol>ButtonRelease</symbol> +event. A key release never generates a key +<symbol>KeyRelease</symbol> +event. </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LockPtrBtn</emphasis></entry> + <entry><symbol>XkbSA_LockPtrBtn</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If the button specified by the <emphasis> -MouseKeys</emphasis> - default button<emphasis> - </emphasis> -or <emphasis> -button</emphasis> - is not locked, a key press causes a <emphasis> -ButtonPress</emphasis> - event instead of a <emphasis> -KeyPress</emphasis> - event and locks the button. If the button is already locked or if <emphasis> -XkbSA_LockNoUnlock</emphasis> - is set in the <emphasis> -flags</emphasis> - field, a key press is ignored and has no effect. +If the button specified by the +<emphasis>MouseKeys</emphasis> +default button +or +<structfield>button</structfield> +is not locked, a key press causes a +<symbol>ButtonPress</symbol> +event instead of a +<symbol>KeyPress</symbol> +event and locks the button. If the button is already locked or if +<symbol>XkbSA_LockNoUnlock</symbol> +is set in the +<structfield>flags</structfield> +field, a key press is ignored and has no effect. </para> </listitem> <listitem> <para> -If the corresponding key press was ignored, and if <emphasis> -XkbSA_LockNoLock</emphasis> - is not set in the <emphasis> -flags</emphasis> - field, a key release generates a <emphasis> -ButtonRelease</emphasis> - event instead of a <emphasis> -KeyRelease</emphasis> - event and unlocks the specified button. If the corresponding key press locked +If the corresponding key press was ignored, and if +<symbol>XkbSA_LockNoLock</symbol> +is not set in the +<structfield>flags</structfield> +field, a key release generates a +<symbol>ButtonRelease</symbol> +event instead of a +<symbol>KeyRelease</symbol> +event and unlocks the specified button. If the corresponding key press locked a button, the key release is ignored and has no effect. </para> </listitem> @@ -1748,16 +1766,16 @@ a button, the key release is ignored and has no effect. </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.8. A general meaning is given in the table, but the exact meaning depends on -the action <emphasis> -type.</emphasis> -: +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.8">Table 16.8</link>. +A general meaning is given in the table, but the exact meaning depends on +the action +<structfield>type</structfield>: </para> -<table frame='topbot'> +<table id='table16.8' frame='topbot'> <title>Pointer Button Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1771,32 +1789,32 @@ type.</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_UseDfltButton</emphasis></entry> + <entry><symbol>XkbSA_UseDfltButton</symbol></entry> <entry> -If set, the action uses the pointer button specified by the <emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control (see section 10.5.1). Otherwise, the action uses the pointer button -specified by the<emphasis> - button </emphasis> +If set, the action uses the pointer button specified by the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>). Otherwise, the action uses the pointer button +specified by the +<structfield>button</structfield> field. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockPtrBtn</emphasis> -, the server only unlocks the pointer button. +If set, and the action type is +<symbol>XkbSA_LockPtrBtn</symbol>, +the server only unlocks the pointer button. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockPtrBtn</emphasis> -, the server only locks the pointer button. +If set, and the action type is +<symbol>XkbSA_LockPtrBtn</symbol>, +the server only locks the pointer button. </entry> </row> </tbody> @@ -1806,62 +1824,63 @@ XkbSA_LockPtrBtn</emphasis> </sect2> <sect2 id='Actions_for_Changing_the_Pointer_Button_Simulated'> <title>Actions for Changing the Pointer Button Simulated</title> +<indexterm significance="preferred" zone="Actions_for_Changing_the_Pointer_Button_Simulated"> +<primary><structname>XkbPtrDfltAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbPtrDfltAction</emphasis> - structure change the <emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control (see section 10.5.1): -</para> +Actions associated with the +<structname>XkbPtrDfltAction</structname> +structure change the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>): -<para><programlisting> +<programlisting> typedef struct _XkbPtrDfltAction { - unsigned char type; /* <emphasis> XkbSA_SetPtrDflt</emphasis> */ - unsigned char flags; /* controls the pointer button number */ - unsigned char affect; /* <emphasis> XkbSA_AffectDfltBtn</emphasis> */ - char valueXXX; /* new default button member */ -} <emphasis>XkbPtrDfltAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_SetPtrDflt</symbol> */ + unsigned char flags; /* controls the pointer button number */ + unsigned char affect; /* <symbol>XkbSA_AffectDfltBtn</symbol> */ + char valueXXX; /* new default button member */ +} <structname>XkbPtrDfltAction</structname>; </programlisting></para> <para> -If the <emphasis> -MouseKeys</emphasis> - control is not enabled, <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events are treated as though the action is <emphasis> -XkbSA_NoAction</emphasis> -. Otherwise, this action changes the <emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control. +If the +<emphasis>MouseKeys</emphasis> +control is not enabled, +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events are treated as though the action is +<symbol>XkbSA_NoAction</symbol>. +Otherwise, this action changes the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control. </para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbPtrDfltAction</emphasis> - structure should always be <emphasis> -XkbSA_SetPtrDflt</emphasis> -. +The +<structfield>type</structfield> +field of the +<structname>XkbPtrDfltAction</structname> +structure should always be +<symbol>XkbSA_SetPtrDflt</symbol>. </para> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the values shown in Table -16.9 (currently there is only one value defined). +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the values shown in +<link linkend="table16.9">Table 16.9</link> +(currently there is only one value defined). </para> -<table frame='topbot'> +<table id='table16.9' frame='topbot'> <title>Pointer Default Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1875,13 +1894,13 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_DfltBtnAbsolute</emphasis></entry> + <entry><symbol>XkbSA_DfltBtnAbsolute</symbol></entry> <entry> -If set, the <emphasis> -value</emphasis> - field represents an absolute pointer button. Otherwise, the <emphasis> -value</emphasis> - field represents the amount to be added to the current default button. +If set, the +<structfield>value</structfield> +field represents an absolute pointer button. Otherwise, the +<structfield>value</structfield> +field represents the amount to be added to the current default button. </entry> </row> </tbody> @@ -1889,219 +1908,219 @@ value</emphasis> </table> <para> -The <emphasis> -affect</emphasis> - field specifies what changes as a result of this action. The only valid value -for the <emphasis> -affect</emphasis> - field is <emphasis>XkbSA_AffectDfltBtn</emphasis>. -</para> - -<para> -The <emphasis> -valueXXX</emphasis> - field is a signed character that represents the new button value for the -<emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control (see section 10.5.1). If <emphasis> -XkbSA_DfltBtnAbsolute</emphasis> - is set in <emphasis> -flags</emphasis> -, <emphasis> -valueXXX</emphasis> - specifies the button to be used; otherwise, <emphasis> -valueXXX</emphasis> - specifies the amount to be added to the current default button. In either +The +<structfield>affect</structfield> +field specifies what changes as a result of this action. The only valid value +for the +<structfield>affect</structfield> +field is <symbol>XkbSA_AffectDfltBtn</symbol>. +</para> + +<para> +The +<structfield>valueXXX</structfield> +field is a signed character that represents the new button value for the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>). If +<symbol>XkbSA_DfltBtnAbsolute</symbol> +is set in +<structfield>flags</structfield>, +<structfield>valueXXX</structfield> +specifies the button to be used; otherwise, +<structfield>valueXXX</structfield> +specifies the amount to be added to the current default button. In either case, illegal button choices are wrapped back around into range. Xkb provides the following macros, to convert between the integer and signed character -values in <emphasis> -XkbPtrDfltAction</emphasis> - structures: -</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> -XkbSAPtrDfltValue</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action from which to extract group */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSAPtrDfltValue</emphasis> - returns the <emphasis> -valueXXX</emphasis> - field of <emphasis> -act</emphasis> - converted to a signed int. -</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'> -void <emphasis> -XkbSASetPtrDfltValue</emphasis> -(<emphasis> -act, val</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrDfltAction <emphasis> -act</emphasis> -; /* action in which to set <emphasis> -valueXXX</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -val</emphasis> -; /* value to set in <emphasis> -valueXXX</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +values in +<structname>XkbPtrDfltAction</structname> +structures: +</para> + +<indexterm significance="preferred" zone="XkbSAPtrDfltValue"><primary><function>XkbSAPtrDfltValue</function></primary></indexterm> +<funcsynopsis id="XkbSAPtrDfltValue"> + <funcprototype> + <funcdef>int <function>XkbSAPtrDfltValue</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract group + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSAPtrDfltValue</function> +returns the +<structfield>valueXXX</structfield> +field of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbSASetPtrDfltValue"><primary><function>XkbSASetPtrDfltValue</function></primary></indexterm> +<funcsynopsis id="XkbSASetPtrDfltValue"> + <funcprototype> + <funcdef>void <function>XkbSASetPtrDfltValue</function></funcdef> +<!-- ( +<parameter>act, val</parameter> +) /* macro */ --> + + <paramdef>XkbPtrDfltAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>val</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set <structfield>valueXXX</structfield> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>val</parameter> + </term> + <listitem> + <para> + value to set in <structfield>valueXXX</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSASetPtrDfltValue</emphasis> - sets the <emphasis> -valueXXX</emphasis> - field of <emphasis> -act</emphasis> - from <emphasis> -val</emphasis> -. +<function>XkbSASetPtrDfltValue</function> +sets the +<structfield>valueXXX</structfield> +field of +<parameter>act</parameter> +from +<parameter>val</parameter>. </para> </sect2> <sect2 id='Actions_for_Locking_Modifiers_and_Group'> <title>Actions for Locking Modifiers and Group</title> +<indexterm significance="preferred" zone="Actions_for_Locking_Modifiers_and_Group"> +<primary><structname>XkbISOAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbISOAction</emphasis> - structure lock modifiers and the group according to the ISO9995 specification. +Actions associated with the +<structname>XkbISOAction</structname> +structure lock modifiers and the group according to the ISO9995 specification. </para> <para> -Operated by itself, the <emphasis> -XkbISOAction</emphasis> - is just a caps lock. Operated simultaneously with another modifier key, it -transforms the other key into a locking key. For example, press <emphasis> -ISO_Lock</emphasis> -, press and release <emphasis> -Control_L</emphasis> -, release <emphasis> -ISO_Lock</emphasis> - ends up locking the <emphasis> -Control</emphasis> - modifier. +Operated by itself, the +<structname>XkbISOAction</structname> +is just a caps lock. Operated simultaneously with another modifier key, it +transforms the other key into a locking key. For example, press +<keysym>ISO_Lock</keysym>, +press and release +<keysym>Control_L</keysym>, +release +<keysym>ISO_Lock</keysym> +ends up locking the +<symbol>Control</symbol> +modifier. </para> <para> The default behavior is to convert: -</para> -<literallayout> - {Set,Latch}Mods to: LockMods - {Set,Latch}Group to: LockGroup - SetPtrBtn to: LockPtrBtn - SetControls to: LockControls -</literallayout> +<simplelist type='vert' columns='1'> + <member>{Set,Latch}Mods to: LockMods</member> + <member>{Set,Latch}Group to: LockGroup</member> + <member>SetPtrBtn to: LockPtrBtn</member> + <member>SetControls to: LockControls</member> +</simplelist> +</para> <para> -The <emphasis> -affects</emphasis> - field allows you to turn those effects on or off individually. Set <emphasis> -XkbSA_ISONoAffectMods</emphasis> - to disable the first, <emphasis> -XkbSA_ISONoAffectGroup</emphasis> - to disable the second, and so forth. +The +<emphasis>affects</emphasis> +field allows you to turn those effects on or off individually. Set +<symbol>XkbSA_ISONoAffectMods</symbol> +to disable the first, +<symbol>XkbSA_ISONoAffectGroup</symbol> +to disable the second, and so forth. </para> <para><programlisting> typedef struct _XkbISOAction { - unsigned char type; /* <emphasis>XkbSA_ISOLock</emphasis> */ - unsigned char flags; /* controls changes to group or modifier state */ - unsigned char mask; /* same as <emphasis>mask</emphasis> field of a modifier description */ - unsigned char real_mods; /* same as <emphasis>real_mods</emphasis> field of a modifier description */ - char group_XXX; /* group index or delta group */ - unsigned char affect; /* specifies whether to affect mods, group, ptrbtn, or controls*/ - unsigned char vmods1; /* derived from <emphasis>vmods</emphasis> field of a modifier description */ - unsigned char vmods2; /* derived from <emphasis>vmods</emphasis> field of a modifier description */ -} <emphasis>XkbISOAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_ISOLock</symbol> */ + unsigned char flags; /* controls changes to group or + modifier state */ + unsigned char mask; /* same as <structfield>mask</structfield> field of + a modifier description */ + unsigned char real_mods; /* same as <structfield>real_mods</structfield> field of + a modifier description */ + char group_XXX; /* group index or delta group */ + unsigned char affect; /* specifies whether to affect + mods, group, ptrbtn, or controls */ + unsigned char vmods1; /* derived from <structfield>vmods</structfield> field of + a modifier description */ + unsigned char vmods2; /* derived from <structfield>vmods</structfield> field of + a modifier description */ +} <structname>XkbISOAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbISOAction</emphasis> - structure should always be <emphasis> -XkbSA_ISOLock</emphasis> -. +The +<structfield>type</structfield> +field of the +<structname>XkbISOAction</structname> +structure should always be +<symbol>XkbSA_ISOLock</symbol>. </para> <para> -The interpretation of the <emphasis> -flags</emphasis> - field depends on whether the <emphasis> -XkbSA_ISODfltIsGroup</emphasis> - is set in the <emphasis> -flags</emphasis> - field or not. +The interpretation of the +<structfield>flags</structfield> +field depends on whether the +<symbol>XkbSA_ISODfltIsGroup</symbol> +is set in the +<structfield>flags</structfield> +field or not. </para> <para> -If the <emphasis> -XkbSA_ISODfltIsGroup</emphasis> - is set in the <emphasis> -flags</emphasis> - field, the action is used to change the group state. The remaining valid bits -of the <emphasis> -flags</emphasis> - field are composed of a bitwise inclusive OR using the masks shown in Table -16.10. +If the +<symbol>XkbSA_ISODfltIsGroup</symbol> +is set in the +<structfield>flags</structfield> +field, the action is used to change the group state. The remaining valid bits +of the +<structfield>flags</structfield> +field are composed of a bitwise inclusive OR using the masks shown in +<link linkend="table16.10">Table 16.10</link>. </para> -<table frame='topbot'> +<table id='table16.10' frame='topbot'> <title>ISO Action Flags when XkbSA_ISODfltIsGroup is Set</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2115,85 +2134,85 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_ISODfltIsGroup</emphasis></entry> + <entry><symbol>XkbSA_ISODfltIsGroup</symbol></entry> <entry> <para> If set, the action is used to change the base group state. Must be set for the remaining bits in this table to carry their interpretations. </para> <para> -A key press sets the base group as specified by the <emphasis> -group_XXX</emphasis> - field and the <emphasis> -XkbSA_GroupAbsolute</emphasis> - bit of the <emphasis> -flags</emphasis> - field (see section Note). If no other actions are transformed by the <emphasis> -XkbISO_Lock</emphasis> - action, a key release locks the group. Otherwise, a key release clears group +A key press sets the base group as specified by the +<structfield>group_XXX</structfield> +field and the +<symbol>XkbSA_GroupAbsolute</symbol> +bit of the +<structfield>flags</structfield> +field (see section Note). If no other actions are transformed by the +<symbol>XkbSA_ISOLock</symbol> +action, a key release locks the group. Otherwise, a key release clears group set by the key press. </para> </entry> </row> <row> - <entry><emphasis>XkbSA_GroupAbsolute</emphasis></entry> + <entry><symbol>XkbSA_GroupAbsolute</symbol></entry> <entry> -If set, the <emphasis> -group_XXX</emphasis> - field represents an absolute group number. Otherwise, it represents a group +If set, the +<structfield>group_XXX</structfield> +field represents an absolute group number. Otherwise, it represents a group delta to be added to the current group to determine the new group number. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectMods</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectMods</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetMods</emphasis> - or <emphasis> -XkbSA_LatchMods</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockMod</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetMods</symbol> +or +<symbol>XkbSA_LatchMods</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockMods</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectGroup</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectGroup</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetGroup</emphasis> - or <emphasis> -XkbSA_LatchGroup</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockGroup</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetGroup</symbol> +or +<symbol>XkbSA_LatchGroup</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockGroup</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectPtr</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectPtr</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_PtrBtn</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockPtrBtn</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_PtrBtn</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockPtrBtn</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectCtrls</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectCtrls</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetControls</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockControls</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetControls</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockControls</symbol> +actions instead. </entry> </row> </tbody> @@ -2201,18 +2220,18 @@ XkbSA_LockControls</emphasis> </table> <para> -If the <emphasis> -XkbSA_ISODfltIsGroup</emphasis> - is not set in the <emphasis> -flags</emphasis> - field, the action is used to change the modifier state and the remaining valid -bits of the <emphasis> -flags</emphasis> - field are composed of a bitwise inclusive OR using the masks shown in Table -16.11. +If the +<symbol>XkbSA_ISODfltIsGroup</symbol> +is not set in the +<structfield>flags</structfield> +field, the action is used to change the modifier state and the remaining valid +bits of the +<structfield>flags</structfield> +field are composed of a bitwise inclusive OR using the masks shown in +<link linkend="table16.11">Table 16.11</link>. </para> -<table frame='topbot'> +<table id='table16.11' frame='topbot'> <title>ISO Action Flags when XkbSA_ISODfltIsGroup is Not Set</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2226,7 +2245,7 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_ISODfltIsGroup</emphasis> </entry> + <entry><symbol>XkbSA_ISODfltIsGroup</symbol> </entry> <entry> <para> If not set, action is used to change the base modifier state. Must not be set @@ -2234,96 +2253,91 @@ for the remaining bits in this table to carry their interpretations. </para> <para> A key press sets the action modifiers in the keyboard’s base modifiers using -the <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmods1</emphasis> -, and <emphasis> -vmods2 </emphasis> -fields (see section 16.1.3). If no other actions are transformed by the -<emphasis> -XkbISO_Lock</emphasis> - action, a key release locks the action modifiers. Otherwise, a key release +the +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields (see <link linkend="Actions_for_Changing_Modifiers_State">section 16.1.3</link>). If no other actions are transformed by the +<symbol>XkbSA_ISOLock</symbol> +action, a key release locks the action modifiers. Otherwise, a key release clears the base modifiers set by the key press. </para> </entry> </row> <row> - <entry><emphasis>XkbSA_UseModMapMods</emphasis></entry> + <entry><symbol>XkbSA_UseModMapMods</symbol></entry> <entry> If set, the action modifiers are determined by the modifiers bound by the modifier mapping of the key. Otherwise, the action modifiers are set to the -modifiers specified by the <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmod1</emphasis> -, and <emphasis> -vmod2</emphasis> - fields. +modifiers specified by the +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry>If set, the server only unlocks the action modifiers.</entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry>If set, the server only locks the action modifiers. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectMods</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectMods</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetMods</emphasis> - or <emphasis> -XkbSA_LatchMods</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockMod</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetMods</symbol> +or +<symbol>XkbSA_LatchMods</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockMods</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectGroup</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectGroup</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetGroup</emphasis> - or <emphasis> -XkbSA_LatchGroup</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockGroup</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetGroup</symbol> +or +<symbol>XkbSA_LatchGroup</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockGroup</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectPtr</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectPtr</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_PtrBtn</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockPtrBtn</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_PtrBtn</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockPtrBtn</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectCtrls</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectCtrls</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetControls</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockControls</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetControls</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockControls</symbol> +actions instead. </entry> </row> </tbody> @@ -2331,50 +2345,48 @@ XkbSA_LockControls</emphasis> </table> <para> -The <emphasis> -group_XXX</emphasis> - field represents a signed character. Xkb provides macros to convert between a +The +<structfield>group_XXX</structfield> +field represents a signed character. Xkb provides macros to convert between a signed integer value and a signed character as shown in section Note. </para> <para> -The <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmods1</emphasis> -, and <emphasis> -vmods2</emphasis> - fields represent the components of an Xkb modifier description (see section -7.2). While the <emphasis> -mask</emphasis> - and <emphasis> -real_mods</emphasis> - fields correspond directly to the <emphasis> -mask</emphasis> - and <emphasis> -real_mods</emphasis> - fields of an Xkb modifier description, the <emphasis> -vmods1</emphasis> - and <emphasis> -vmods2</emphasis> - fields are combined to correspond to the <emphasis> -vmods</emphasis> - field of an Xkb modifier description. Xkb provides macros to convert between -the two formats as shown in section 16.1.3. +The +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields represent the components of an Xkb modifier description +(see <link linkend="Modifier_Definitions">section 7.2</link>). While the +<structfield>mask</structfield> +and +<structfield>real_mods</structfield> +fields correspond directly to the +<structfield>mask</structfield> +and +<structfield>real_mods</structfield> +fields of an Xkb modifier description, the +<structfield>vmods1</structfield> +and +<structfield>vmods2</structfield> +fields are combined to correspond to the +<structfield>vmods</structfield> +field of an Xkb modifier description. Xkb provides macros to convert between +the two formats as shown in <link linkend="Actions_for_Changing_Modifiers_State">section 16.1.3</link>. </para> <para> -The <emphasis> -affect</emphasis> - field is composed of a bitwise inclusive OR using the masks shown in Table -16.11. +The +<structfield>affect</structfield> +field is composed of a bitwise inclusive OR using the masks shown in +<link linkend="table16.11">Table 16.11</link>. </para> -<table frame='topbot'> +<table id='table16.12' frame='topbot'> <title>ISO Action Affect Field Values</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2388,63 +2400,63 @@ affect</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_ISODNoAffectMods</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectMods</symbol></entry> <entry> -If <emphasis> -XkbSA_ISONoAffectMods</emphasis> - is not set, any <emphasis> -SA_SetMods</emphasis> - or <emphasis> -SA_LatchMods</emphasis> - actions occurring simultaneously with the <emphasis> -XkbISOAction</emphasis> - are treated as <emphasis> -SA_LockMods</emphasis> - instead. +If +<symbol>XkbSA_ISONoAffectMods</symbol> +is not set, any +<emphasis>SA_SetMods</emphasis> +or +<emphasis>SA_LatchMods</emphasis> +actions occurring simultaneously with the +<structname>XkbISOAction</structname> +are treated as +<emphasis>SA_LockMods</emphasis> +instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectGroup</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectGroup</symbol></entry> <entry> -If <emphasis> -XkbSA_ISONoAffectGroup</emphasis> - is not set, any <emphasis> -SA_SetGroup</emphasis> - or <emphasis> -SA_LatchGroup</emphasis> - actions occurring simultaneously with the <emphasis> -XkbISOAction</emphasis> - are treated as <emphasis> -SA_LockGroup</emphasis> - instead. +If +<symbol>XkbSA_ISONoAffectGroup</symbol> +is not set, any +<emphasis>SA_SetGroup</emphasis> +or +<emphasis>SA_LatchGroup</emphasis> +actions occurring simultaneously with the +<structname>XkbISOAction</structname> +are treated as +<emphasis>SA_LockGroup</emphasis> +instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectPtr</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectPtr</symbol></entry> <entry> -If <emphasis> -XkbSA_ISONoAffectPtr</emphasis> - is not set, any <emphasis> -SA_PtrBtn</emphasis> - actions occurring simultaneously with the <emphasis> -XkbISOAction</emphasis> - are treated as <emphasis> -SA_LockPtrBtn</emphasis> - instead. +If +<symbol>XkbSA_ISONoAffectPtr</symbol> +is not set, any +<emphasis>SA_PtrBtn</emphasis> +actions occurring simultaneously with the +<structname>XkbISOAction</structname> +are treated as +<emphasis>SA_LockPtrBtn</emphasis> +instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectCtrls</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectCtrls</symbol></entry> <entry> -If <emphasis> -XkbSA_ISONoAffectCtrls</emphasis> - is not set, any <emphasis> -SA_SetControls</emphasis> - actions occurring simultaneously with the <emphasis> -XkbISOAction</emphasis> - are treated as <emphasis> -SA_LockControls</emphasis> - instead. +If +<symbol>XkbSA_ISONoAffectCtrls</symbol> +is not set, any +<emphasis>SA_SetControls</emphasis> +actions occurring simultaneously with the +<structname>XkbISOAction</structname> +are treated as +<emphasis>SA_LockControls</emphasis> +instead. </entry> </row> </tbody> @@ -2454,46 +2466,48 @@ SA_LockControls</emphasis> </sect2> <sect2 id='Actions_for_Changing_the_Active_Screen'> <title>Actions for Changing the Active Screen</title> +<indexterm significance="preferred" zone="Actions_for_Changing_the_Active_Screen"> +<primary><structname>XkbSwitchScreenAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbSwitchScreen</emphasis> - action structure change the active screen on a multiscreen display: +Actions associated with the +<structname>XkbSwitchScreenAction</structname> +action structure change the active screen on a multiscreen display: </para> <note><para>This action is optional. Servers are free to ignore the action or any of its flags if they do not support the requested behavior. If the action -is ignored, it behaves like <emphasis> -XkbSA_NoAction</emphasis> -. Otherwise, key press and key release events do not generate an event. +is ignored, it behaves like +<symbol>XkbSA_NoAction</symbol>. +Otherwise, key press and key release events do not generate an event. </para></note> <para><programlisting> typedef struct _XkbSwitchScreenAction { - unsigned char type; /* <emphasis> XkbSA_SwitchScreen</emphasis> */ - unsigned char flags; /* controls screen switching */ - char screenXXX; /* screen number or delta */ -} <emphasis>XkbSwitchScreenAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_SwitchScreen</symbol> */ + unsigned char flags; /* controls screen switching */ + char screenXXX; /* screen number or delta */ +} <structname>XkbSwitchScreenAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbSwitchScreenAction</emphasis> - structure should always be <emphasis> -XkbSA_SwitchScreen</emphasis>. +The +<structfield>type</structfield> +field of the +<structname>XkbSwitchScreenAction</structname> +structure should always be +<symbol>XkbSA_SwitchScreen</symbol>. </para> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.13. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.13">Table 16.13</link>. </para> -<table frame='topbot'> +<table id='table16.13' frame='topbot'> <title>Switch Screen Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2507,16 +2521,16 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_SwitchAbsolute</emphasis></entry> + <entry><symbol>XkbSA_SwitchAbsolute</symbol></entry> <entry> -If set, the <emphasis> -screenXXX</emphasis> - field represents the index of the new screen. Otherwise, it represents an +If set, the +<structfield>screenXXX</structfield> +field represents the index of the new screen. Otherwise, it represents an offset from the current screen to the new screen. </entry> </row> <row> - <entry><emphasis>XkbSA_SwitchApplication</emphasis></entry> + <entry><symbol>XkbSA_SwitchApplication</symbol></entry> <entry> If not set, the action should switch to another screen on the same server. Otherwise, it should switch to another X server or application that @@ -2528,138 +2542,135 @@ shares the same physical display. </table> <para> -The <emphasis> -screenXXX</emphasis> - field is a signed character value that represents either the relative or -absolute screen index, depending on the state of the <emphasis> -XkbSA_SwitchAbsolute</emphasis> - bit in the <emphasis> -flags</emphasis> - field. Xkb provides the following macros to convert between the integer and -signed character value for screen numbers in <emphasis> -XkbSwitchScreenAction</emphasis> - structures: -</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> -XkbSAScreen</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSwitchScreenAction <emphasis> -act</emphasis> -; /* action from which to extract screen */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSAScreen</emphasis> - returns the <emphasis> -screenXXX</emphasis> - field of <emphasis> -act</emphasis> - converted to a signed int. -</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'> -void <emphasis> -XkbSASetScreen</emphasis> -(<emphasis> -act, s</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSwitchScreenAction <emphasis> -act</emphasis> -; /* action in which to set <emphasis> -screenXXX</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -s</emphasis> -; /* value to set in <emphasis> -screenXXX</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +The +<structfield>screenXXX</structfield> +field is a signed character value that represents either the relative or +absolute screen index, depending on the state of the +<symbol>XkbSA_SwitchAbsolute</symbol> +bit in the +<structfield>flags</structfield> +field. Xkb provides the following macros to convert between the integer and +signed character value for screen numbers in +<structname>XkbSwitchScreenAction</structname> +structures: +</para> + +<indexterm significance="preferred" zone="XkbSAScreen"><primary><function>XkbSAScreen</function></primary></indexterm> +<funcsynopsis id="XkbSAScreen"> + <funcprototype> + <funcdef>int <function>XkbSAScreen</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbSwitchScreenAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract screen + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSAScreen</function> +returns the +<structfield>screenXXX</structfield> +field of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbSASetScreen"><primary><function>XkbSASetScreen</function></primary></indexterm> +<funcsynopsis id="XkbSASetScreen"> + <funcprototype> + <funcdef>void <function>XkbSASetScreen</function></funcdef> +<!-- ( +<parameter>act, s</parameter> +) /* macro */ --> + + <paramdef>XkbSwitchScreenAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>s</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set <structfield>screenXXX</structfield> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>s</parameter> + </term> + <listitem> + <para> + value to set in <structfield>screenXXX</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSASetScreen</emphasis> - sets the <emphasis> -screenXXX</emphasis> - field of <emphasis> -act</emphasis> - from <emphasis> -s</emphasis> -. +<function>XkbSASetScreen</function> +sets the +<structfield>screenXXX</structfield> +field of +<parameter>act</parameter> +from +<parameter>s</parameter>. </para> </sect2> <sect2 id='Actions_for_Changing_Boolean_Controls_State'> <title>Actions for Changing Boolean Controls State</title> +<indexterm significance="preferred" zone="Actions_for_Changing_Boolean_Controls_State"> +<primary><structname>XkbCtrlsAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbCtrlsAction</emphasis> - structure change the state of the boolean controls (see section 10.1): -</para> +Actions associated with the +<structname>XkbCtrlsAction</structname> +structure change the state of the boolean controls (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>): -<para><programlisting> +<programlisting> typedef struct _XkbCtrlsAction { - unsigned char type; /* <emphasis> XkbSA_SetControls, - XkbSA_LockControls</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis>, - controls enabling and disabling of controls */ - unsigned char ctrls3; /* <emphasis>ctrls0</emphasis> through - <emphasis> ctrls3</emphasis> represent the boolean controls */ - unsigned char ctrls2; /* <emphasis>ctrls0</emphasis> through - <emphasis> ctrls3</emphasis> represent the boolean controls */ - unsigned char ctrls1; /* <emphasis>ctrls0</emphasis> through - <emphasis> ctrls3</emphasis> represent the boolean controls */ - unsigned char ctrls0; /* <emphasis>ctrls0</emphasis> through - <emphasis> ctrls3</emphasis> represent the boolean controls */ -} <emphasis>XkbCtrlsAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_SetControls</symbol>, + <symbol>XkbSA_LockControls</symbol> */ + unsigned char flags; /* with <structfield>type</structfield>, controls enabling + and disabling of controls */ + unsigned char ctrls3; /* <structfield>ctrls0</structfield> through <structfield>ctrls3</structfield> + represent the boolean controls */ + unsigned char ctrls2; /* <structfield>ctrls0</structfield> through <structfield>ctrls3</structfield> + represent the boolean controls */ + unsigned char ctrls1; /* <structfield>ctrls0</structfield> through <structfield>ctrls3</structfield> + represent the boolean controls */ + unsigned char ctrls0; /* <structfield>ctrls0</structfield> through <structfield>ctrls3</structfield> + represent the boolean controls */ +} <structname>XkbCtrlsAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field can have any one of the values shown in Table 16.14. +The +<structfield>type</structfield> +field can have any one of the values shown in +<link linkend="table16.14">Table 16.14</link>. </para> -<table frame='topbot'> +<table id='table16.14' frame='topbot'> <title>Controls Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2673,14 +2684,14 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_SetControls</emphasis></entry> + <entry><symbol>XkbSA_SetControls</symbol></entry> <entry> <itemizedlist> <listitem> <para> -A key press enables any boolean controls specified in the <emphasis> -ctrls</emphasis> - fields that were not already enabled at the time of the key press. +A key press enables any boolean controls specified in the +<structfield>ctrls</structfield> +fields that were not already enabled at the time of the key press. </para> </listitem> <listitem> @@ -2690,45 +2701,45 @@ A key release disables any controls enabled by the key press. </listitem> <listitem> <para> -This action can cause <emphasis> -XkbControlsNotify</emphasis> - events (see section 10.1). +This action can cause +<symbol>XkbControlsNotify</symbol> +events (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>). </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LockControls</emphasis></entry> + <entry><symbol>XkbSA_LockControls</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If the <emphasis> -XkbSA_LockNoLock</emphasis> - bit is not set in the <emphasis> -flags</emphasis> - field, a key press enables any controls specified in the <emphasis> -ctrls</emphasis> - fields that were not already enabled at the time of the key press. +If the +<symbol>XkbSA_LockNoLock</symbol> +bit is not set in the +<structfield>flags</structfield> +field, a key press enables any controls specified in the +<structfield>ctrls</structfield> +fields that were not already enabled at the time of the key press. </para> </listitem> <listitem> <para> -If the <emphasis> -XkbSA_LockNoUnlock</emphasis> - bit is not set in the <emphasis> -flags</emphasis> - field, a key release disables any controls specified in the <emphasis> -ctrls</emphasis> - fields that were not already disabled at the time of the key press. +If the +<symbol>XkbSA_LockNoUnlock</symbol> +bit is not set in the +<structfield>flags</structfield> +field, a key release disables any controls specified in the +<structfield>ctrls</structfield> +fields that were not already disabled at the time of the key press. </para> </listitem> <listitem> <para> -This action can cause <emphasis> -XkbControlsNotify</emphasis> - events (see section 10.1). +This action can cause +<symbol>XkbControlsNotify</symbol> +events (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>). </para> </listitem> </itemizedlist> @@ -2739,13 +2750,13 @@ XkbControlsNotify</emphasis> </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.15. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.15">Table 16.15</link>. </para> -<table frame='topbot'> +<table id='table16.15' frame='topbot'> <title>Control Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2759,19 +2770,19 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockControls</emphasis> -, the server only disables controls. +If set, and the action type is +<symbol>XkbSA_LockControls</symbol>, +the server only disables controls. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockControls</emphasis> -, the server only enables controls. +If set, and the action type is +<symbol>XkbSA_LockControls</symbol>, +the server only enables controls. </entry> </row> </tbody> @@ -2779,161 +2790,158 @@ XkbSA_LockControls</emphasis> </table> <para> -The <emphasis> -XkbSA_SetControls</emphasis> - action implements a key that enables a boolean control when pressed and -disables it when released. The <emphasis> -XkbSA_LockControls</emphasis> - action is used to implement a key that toggles the state of a boolean control -each time it is pressed and released. The <emphasis> -XkbSA_LockNoLock</emphasis> - and <emphasis> -XkbSA_LockNoUnlock</emphasis> - flags allow modifying the toggling behavior to only unlock or only lock the +The +<symbol>XkbSA_SetControls</symbol> +action implements a key that enables a boolean control when pressed and +disables it when released. The +<symbol>XkbSA_LockControls</symbol> +action is used to implement a key that toggles the state of a boolean control +each time it is pressed and released. The +<symbol>XkbSA_LockNoLock</symbol> +and +<symbol>XkbSA_LockNoUnlock</symbol> +flags allow modifying the toggling behavior to only unlock or only lock the boolean control. </para> <para> -The <emphasis> -ctrls0</emphasis> -, <emphasis> -ctrls1</emphasis> -, <emphasis> -ctrls2</emphasis> -, and <emphasis> -ctrls3</emphasis> - fields represent the boolean controls in the <emphasis> -enabled_ctrls</emphasis> - field of the controls structure (see section 10.1). Xkb provides the following +The +<structfield>ctrls0</structfield>, +<structfield>ctrls1</structfield>, +<structfield>ctrls2</structfield>, +and +<structfield>ctrls3</structfield> +fields represent the boolean controls in the +<structfield>enabled_ctrls</structfield> +field of the controls structure (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>). Xkb provides the following macros, to convert between the two formats: </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 int <emphasis> -XkbActionCtrls</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbCtrlsAction <emphasis> -act</emphasis> -; /* action from which to extract controls */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbActionCtrls</emphasis> - returns the <emphasis> -ctrls</emphasis> - fields of <emphasis> -act</emphasis> - converted to an unsigned int. -</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'> -void <emphasis> -XkbSAActionSetCtrls</emphasis> -(<emphasis> -act, ctrls</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbCtrlsAction <emphasis> -act</emphasis> -; /* action in which to set ctrls0-ctrls3 */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -ctrls</emphasis> -; /* value to set in ctrls0-ctrls3 */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbActionCtrls"><primary><function>XkbActionCtrls</function></primary></indexterm> +<funcsynopsis id="XkbActionCtrls"> + <funcprototype> + <funcdef>unsigned int <function>XkbActionCtrls</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbCtrlsAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract controls + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbActionCtrls</function> +returns the +<structfield>ctrls</structfield> +fields of +<parameter>act</parameter> +converted to an unsigned int. +</para> + + +<indexterm significance="preferred" zone="XkbSAActionSetCtrls"><primary><function>XkbSAActionSetCtrls</function></primary></indexterm> +<funcsynopsis id="XkbSAActionSetCtrls"> + <funcprototype> + <funcdef>void <function>XkbSAActionSetCtrls</function></funcdef> +<!-- ( +<parameter>act, ctrls</parameter> +) /* macro */ --> + + <paramdef>XkbCtrlsAction <parameter>act</parameter></paramdef> + <paramdef>unsigned int <parameter>ctrls</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set ctrls0-ctrls3 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls</parameter> + </term> + <listitem> + <para> + value to set in ctrls0-ctrls3 + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSAActionSetCtrls</emphasis> - sets the <emphasis> -ctrls0</emphasis> - through <emphasis> -ctrls3</emphasis> - fields of <emphasis> -act</emphasis> - from <emphasis> -ctrls</emphasis> -. +<function>XkbSAActionSetCtrls</function> +sets the +<structfield>ctrls0</structfield> +through +<structfield>ctrls3</structfield> +fields of +<parameter>act</parameter> +from +<parameter>ctrls</parameter>. </para> </sect2> <sect2 id='Actions_for_Generating_Messages'> <title>Actions for Generating Messages</title> +<indexterm significance="preferred" zone="Actions_for_Generating_Messages"> +<primary><structname>XkbMessageAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbMessageAction</emphasis> - structure generate <emphasis> -XkbActionMessage</emphasis> - events: -</para> +Actions associated with the +<structname>XkbMessageAction</structname> +structure generate +<symbol>XkbActionMessage</symbol> +events: + +<programlisting> +#define XkbActionMessageLength 6 -<para><programlisting> -#define XkbActionMessageLength 6 -</programlisting></para> -<para><programlisting> typedef struct _XkbMessageAction { - unsigned char type; /* <emphasis> XkbSA_ActionMessage</emphasis> */ - unsigned char flags; /* controls event generation via key presses and releases */ - unsigned char message[XkbActionMessageLength]; /* message */ -} <emphasis>XkbMessageAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_ActionMessage</symbol> */ + unsigned char flags; /* controls event generation via + key presses and releases */ + unsigned char message[XkbActionMessageLength]; /* message */ +} <structname>XkbMessageAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbMessageAction</emphasis> - structure should always be <emphasis> -XkbSA_ActionMessage</emphasis> -. +The +<structfield>type</structfield> +field of the +<structname>XkbMessageAction</structname> +structure should always be +<symbol>XkbSA_ActionMessage</symbol>. </para> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.16. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.16">Table 16.16</link>. </para> -<table frame='topbot'> +<table id='table16.16' frame='topbot'> <title>Message Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2947,35 +2955,35 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_MessageOnPress</emphasis></entry> + <entry><symbol>XkbSA_MessageOnPress</symbol></entry> <entry> -If set, key press events generate an <emphasis> -XkbActionMessage</emphasis> - event that reports the keycode, event type, and contents of the <emphasis> -message</emphasis> - field. +If set, key press events generate an +<symbol>XkbActionMessage</symbol> +event that reports the keycode, event type, and contents of the +<structfield>message</structfield> +field. </entry> </row> <row> - <entry><emphasis>XkbSA_MessageOnRelease</emphasis></entry> + <entry><symbol>XkbSA_MessageOnRelease</symbol></entry> <entry> -If set, key release events generate an <emphasis> -XkbActionMessage</emphasis> - event that reports the keycode, event type, and contents of the <emphasis> -message</emphasis> - field. +If set, key release events generate an +<symbol>XkbActionMessage</symbol> +event that reports the keycode, event type, and contents of the +<structfield>message</structfield> +field. </entry> </row> <row> - <entry><emphasis>XkbSA_MessageGenKeyEvent</emphasis></entry> + <entry><symbol>XkbSA_MessageGenKeyEvent</symbol></entry> <entry> -If set, key press and key release events generate <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events, regardless of whether they generate <emphasis> -XkbActionMessage</emphasis> - events. +If set, key press and key release events generate +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events, regardless of whether they generate +<symbol>XkbActionMessage</symbol> +events. </entry> </row> </tbody> @@ -2983,143 +2991,145 @@ XkbActionMessage</emphasis> </table> <para> -The <emphasis> -message</emphasis> - field is an array of <emphasis> -XkbActionMessageLength</emphasis> - unsigned characters and may be set to anything the keymap designer wishes. +The +<structfield>message</structfield> +field is an array of +<symbol>XkbActionMessageLength</symbol> +unsigned characters and may be set to anything the keymap designer wishes. </para> <sect3 id='Detecting_Key_Action_Messages'> <title>Detecting Key Action Messages</title> +<indexterm significance="preferred" zone="Detecting_Key_Action_Messages"> +<primary>events</primary><secondary><symbol>XkbActionMessage</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Detecting_Key_Action_Messages"> +<primary><structname>XkbActionMessageEvent</structname></primary></indexterm> <para> -To receive <emphasis> -XkbActionMessage</emphasis> - events by calling either <emphasis> -XkbSelectEvents</emphasis> - or <emphasis> -XkbSelectEventDetails</emphasis> - (see section 4.3). +To receive +<symbol>XkbActionMessage</symbol> +events by calling either +<function>XkbSelectEvents</function> +or +<function>XkbSelectEventDetails</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>). </para> <para> -To receive <emphasis> -XkbActionMessage</emphasis> - events under all possible conditions, use <emphasis> -XkbSelectEvents</emphasis> - and pass <emphasis> -XkbActionMessageMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +To receive +<symbol>XkbActionMessage</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +and pass +<symbol>XkbActionMessageMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -The <emphasis> -XkbActionMessage</emphasis> - event has no event details. However, you can call <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbActionMessage</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying <emphasis> -XkbAllActionMessageMask</emphasis> - in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits.</emphasis> - This has the same effect as a call to <emphasis> -XkbSelectEvents</emphasis>. +The +<symbol>XkbActionMessage</symbol> +event has no event details. However, you can call +<function>XkbSelectEventDetails</function> +using +<symbol>XkbActionMessage</symbol> +as the +<structfield>event_type</structfield> +and specifying +<symbol>XkbAllActionMessagesMask</symbol> +in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. +This has the same effect as a call to +<function>XkbSelectEvents</function>. </para> <para> -The structure for the <emphasis> -XkbActionMessage</emphasis> - event is defined as follows: -</para> +The structure for the +<symbol>XkbActionMessage</symbol> +event is defined as follows: -<para><programlisting> +<programlisting> typedef struct _XkbActionMessage { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis>True</emphasis> => synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis>XkbActionMessage</emphasis> */ - int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ - KeyCode keycode; /* keycode of key triggering event */ - Bool press; /* <emphasis>True</emphasis> => key press, - <emphasis>False</emphasis> => release */ - Bool key_event_follows; /* <emphasis>True</emphasis> => KeyPress/KeyRelease follows */ - char message[XkbActionMessageLength+1]; /* message text */ -} <emphasis>XkbActionMessageEvent</emphasis>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbActionMessage</symbol> */ + int device; /* Xkb device ID, + will not be <symbol>XkbUseCoreKbd</symbol> */ + KeyCode keycode; /* keycode of key triggering event */ + Bool press; /* <symbol>True</symbol> ⇒ key press, + <symbol>False</symbol> ⇒ release */ + Bool key_event_follows;/* <symbol>True</symbol> ⇒ KeyPress/KeyRelease follows */ + char message[XkbActionMessageLength+1]; /* message text */ +} <structname>XkbActionMessageEvent</structname>; </programlisting></para> <para> -The <emphasis> -keycode</emphasis> - is the keycode of the key that was pressed or released. The <emphasis> -press</emphasis> - field specifies whether the event was the result of a key press or key +The +<structfield>keycode</structfield> +is the keycode of the key that was pressed or released. The +<structfield>press</structfield> +field specifies whether the event was the result of a key press or key release. </para> <para> -The <emphasis> -key_event_follows</emphasis> - specifies whether a <emphasis> -KeyPress</emphasis> - (if <emphasis> -press</emphasis> - is <emphasis> -True</emphasis> -) or <emphasis> -KeyRelease</emphasis> - (if <emphasis> -press</emphasis> - is <emphasis> -False</emphasis> -) event is also sent to the client. As with all other Xkb events, <emphasis> -XkbActionMessageEvent</emphasis> -s are delivered to all clients requesting them, regardless of the current -keyboard focus. However, the <emphasis> -KeyPress</emphasis> - or <emphasis> -KeyRelease</emphasis> - event that conditionally follows an <emphasis> -XkbActionMessageEvent</emphasis> - is sent only to the client selected by the current keyboard focus. <emphasis> -key_event_follows</emphasis> - is <emphasis> -True</emphasis> - only for the client that is actually sent the following <emphasis> -KeyPress</emphasis> - or <emphasis> -KeyRelease</emphasis> - event. -</para> - - -<para> -The <emphasis> -message</emphasis> - field is set to the message specified in the action and is guaranteed to be -<emphasis> -NULL</emphasis> --terminated; the Xkb extension forces a <emphasis> -NULL</emphasis> - into <emphasis> -message</emphasis> -[<emphasis> -XkbActionMessageLength</emphasis> +The +<structfield>key_event_follows</structfield> +specifies whether a +<symbol>KeyPress</symbol> +(if +<structfield>press</structfield> +is +<symbol>True</symbol>) +or +<symbol>KeyRelease</symbol> +(if +<structfield>press</structfield> +is +<symbol>False</symbol>) +event is also sent to the client. As with all other Xkb events, +<structname>XkbActionMessageEvent</structname>s +are delivered to all clients requesting them, regardless of the current +keyboard focus. However, the +<symbol>KeyPress</symbol> +or +<symbol>KeyRelease</symbol> +event that conditionally follows an +<structname>XkbActionMessageEvent</structname> +is sent only to the client selected by the current keyboard focus. +<structfield>key_event_follows</structfield> +is +<symbol>True</symbol> +only for the client that is actually sent the following +<symbol>KeyPress</symbol> +or +<symbol>KeyRelease</symbol> +event. +</para> + + +<para> +The +<structfield>message</structfield> +field is set to the message specified in the action and is guaranteed to be +<symbol>NULL</symbol> +-terminated; the Xkb extension forces a +<symbol>NULL</symbol> +into +<structfield>message</structfield> +[ +<symbol>XkbActionMessageLength</symbol> ]. </para> @@ -3128,87 +3138,88 @@ XkbActionMessageLength</emphasis> </sect2> <sect2 id='Actions_for_Generating_a_Different_Keycode'> <title>Actions for Generating a Different Keycode</title> +<indexterm significance="preferred" zone="Actions_for_Generating_a_Different_Keycode"> +<primary><structname>XkbRedirectKeyAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbRedirectKeyAction</emphasis> - structure generate <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events containing a keycode different from the key that was pressed or +Actions associated with the +<structname>XkbRedirectKeyAction</structname> +structure generate +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events containing a keycode different from the key that was pressed or released: -</para> -<para><programlisting> +<programlisting> typedef struct _XkbRedirectKeyAction { - unsigned char type; /* <emphasis> XkbSA_RedirectKey</emphasis> */ - unsigned char new_key; /* keycode to be put in event */ - unsigned char mods_mask; /* mask of real mods to be reset */ - unsigned char mods; /* mask of real mods to take values from */ - unsigned char vmods_mask0; /* first half of mask of virtual mods to be reset */ - unsigned char vmods_mask1; /* other half of mask of virtual mods to be reset */ - unsigned char vmods0; /* first half of mask of virtual mods to take values from */ - unsigned char vmods1; /* other half of mask of virtual mods to take values from */ -} <emphasis>XkbRedirectKeyAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_RedirectKey</symbol> */ + unsigned char new_key; /* keycode to be put in event */ + unsigned char mods_mask; /* mask of real mods to be reset */ + unsigned char mods; /* mask of real mods to take values from */ + unsigned char vmods_mask0; /* first half of mask of virtual mods + to be reset */ + unsigned char vmods_mask1; /* other half of mask of virtual mods + to be reset */ + unsigned char vmods0; /* first half of mask of virtual mods + to take values from */ + unsigned char vmods1; /* other half of mask of virtual mods + to take values from */ +} <structname>XkbRedirectKeyAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field for the <emphasis> -XkbRedirectKeyAction</emphasis> - structure should always be <emphasis> -XkbSA_RedirectKey</emphasis> -. +The +<structfield>type</structfield> +field for the +<structname>XkbRedirectKeyAction</structname> +structure should always be +<symbol>XkbSA_RedirectKey</symbol>. </para> <para> -Key presses cause a <emphasis> -KeyPress</emphasis> - event for the key specified by the <emphasis> -new_key</emphasis> - field instead of the actual key. The state reported in this event reports the +Key presses cause a +<symbol>KeyPress</symbol> +event for the key specified by the +<structfield>new_key</structfield> +field instead of the actual key. The state reported in this event reports the current effective modifiers changed as follows: any real modifiers selected by -the <emphasis> -mods_mask</emphasis> - field are set to corresponding values from the <emphasis> -mods</emphasis> - field. Any real modifiers bound to the virtual modifiers specified by the -<emphasis> -vmods_mask0</emphasis> - and <emphasis> -vmods_mask1</emphasis> - fields are either set or cleared, depending on the corresponding values in the -<emphasis> -vmods0</emphasis> - and <emphasis> -vmods1</emphasis> - fields. If the real and virtual modifier definitions specify conflicting +the +<structfield>mods_mask</structfield> +field are set to corresponding values from the +<structfield>mods</structfield> +field. Any real modifiers bound to the virtual modifiers specified by the +<structfield>vmods_mask0</structfield> +and +<structfield>vmods_mask1</structfield> +fields are either set or cleared, depending on the corresponding values in the +<structfield>vmods0</structfield> +and +<structfield>vmods1</structfield> +fields. If the real and virtual modifier definitions specify conflicting values for a single modifier, the real modifier definition has priority. </para> <para> -Key releases cause a <emphasis> -KeyRelease</emphasis> - event for the key specified by the <emphasis> -new_key</emphasis> - field instead of the actual key. The state for this event consists of the +Key releases cause a +<symbol>KeyRelease</symbol> +event for the key specified by the +<structfield>new_key</structfield> +field instead of the actual key. The state for this event consists of the effective keyboard modifiers at the time of the release, changed as described previously. </para> <para> -The <emphasis> -XkbSA_RedirectKey</emphasis> - action normally redirects to another key on the same device as the key that +The +<symbol>XkbSA_RedirectKey</symbol> +action normally redirects to another key on the same device as the key that caused the event, unless that device does not belong to the input extension -<emphasis> -KeyClass</emphasis> -, in which case this action causes an event on the core keyboard device. (The +<symbol>KeyClass</symbol>, +in which case this action causes an event on the core keyboard device. (The input extension categorizes devices by breaking them into classes. Keyboards, and other input devices with keys, are classified as KeyClass devices by the input extension.) @@ -3216,215 +3227,219 @@ input extension.) <para> -The <emphasis> -vmods_mask0</emphasis> - and <emphasis> -vmods_mask1</emphasis> - fields actually represent one <emphasis> -vmods_mask</emphasis> - value, as described in Chapter 7. Xkb provides the following macros, to +The +<structfield>vmods_mask0</structfield> +and +<structfield>vmods_mask1</structfield> +fields actually represent one +<emphasis>vmods_mask</emphasis> +value, as described in <xref linkend="Virtual_Modifiers" />. Xkb provides the following macros, to convert between the two formats: </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 int <emphasis> -XkbSARedirectVModsMask</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRedirectKeyAction <emphasis> -act</emphasis> -; /* action from which to extract vmods */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSARedirectVModsMask</emphasis> - returns the <emphasis> -vmods_mask0</emphasis> - and <emphasis> -vmods_mask1</emphasis> - fields of <emphasis> -act</emphasis> - converted to an unsigned int. -</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'> -void <emphasis> -XkbSARedirectSetVModsMask</emphasis> -(<emphasis> -act, vm</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRedirectKeyAction <emphasis> -act</emphasis> -; /* action in which to set vmods */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -vm</emphasis> -; /* new value for virtual modifier mask */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSARedirectVModsMask"><primary><function>XkbSARedirectVModsMask</function></primary></indexterm> +<funcsynopsis id="XkbSARedirectVModsMask"> + <funcprototype> + <funcdef>unsigned int <function>XkbSARedirectVModsMask</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbRedirectKeyAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract vmods + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSARedirectVModsMask</function> +returns the +<structfield>vmods_mask0</structfield> +and +<structfield>vmods_mask1</structfield> +fields of +<parameter>act</parameter> +converted to an unsigned int. +</para> + + +<indexterm significance="preferred" zone="XkbSARedirectSetVModsMask"><primary><function>XkbSARedirectSetVModsMask</function></primary></indexterm> +<funcsynopsis id="XkbSARedirectSetVModsMask"> + <funcprototype> + <funcdef>void <function>XkbSARedirectSetVModsMask</function></funcdef> +<!-- ( +<parameter>act, vm</parameter> +) /* macro */ --> + + <paramdef>XkbRedirectKeyAction <parameter>act</parameter></paramdef> + <paramdef>unsigned int <parameter>vm</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set vmods + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>vm</parameter> + </term> + <listitem> + <para> + new value for virtual modifier mask + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSARedirectSetVModsMask</emphasis> - sets the <emphasis> -vmods_mask0</emphasis> - and <emphasis> -vmods_mask1</emphasis> - fields of <emphasis> -act</emphasis> - from <emphasis> -vm</emphasis> -. +<function>XkbSARedirectSetVModsMask</function> +sets the +<structfield>vmods_mask0</structfield> +and +<structfield>vmods_mask1</structfield> +fields of +<parameter>act</parameter> +from +<parameter>vm</parameter>. </para> <para> -Similarly, the <emphasis> -vmods0</emphasis> - and <emphasis> -vmods1</emphasis> - fields actually represent one <emphasis> -vmods </emphasis> -value, as described in Chapter 7. To convert between the two formats, Xkb +Similarly, the +<structfield>vmods0</structfield> +and +<structfield>vmods1</structfield> +fields actually represent one +<structfield>vmods</structfield> +value, as described in <xref linkend="Virtual_Modifiers" />. To convert between the two formats, Xkb provides the following convenience macros: </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 int <emphasis> -XkbSARedirectVMods</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRedirectKeyAction <emphasis> -act</emphasis> -; /* action from which to extract vmods */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSARedirectVMods"><primary><function>XkbSARedirectVMods</function></primary></indexterm> +<funcsynopsis id="XkbSARedirectVMods"> + <funcprototype> + <funcdef>unsigned int <function>XkbSARedirectVMods</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbRedirectKeyAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract vmods + </para> + </listitem> + </varlistentry> +</variablelist> -<literallayout> - <emphasis>XkbSARedirectVModsMask</emphasis> returns the <emphasis>vmods0</emphasis> - and <emphasis>vmods1</emphasis> fields of <emphasis>act</emphasis> +<para> + <function>XkbSARedirectVModsMask</function> returns the <structfield>vmods0</structfield> + and <structfield>vmods1</structfield> fields of <parameter>act</parameter> converted to an unsigned int. -</literallayout> +</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'> -void <emphasis> -XkbSARedirectSetVMods</emphasis> -(<emphasis> -act, vm</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRedirectKeyAction <emphasis> -act</emphasis> -; /* action in which to set vmods */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -v</emphasis> -; /* new value for virtual modifiers */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> -<literallayout> - <emphasis> XkbSARedirectSetVModsMask</emphasis> sets the <emphasis>vmods0</emphasis> - and <emphasis>vmods1</emphasis> of <emphasis>act</emphasis> from <emphasis>v</emphasis>. -</literallayout> +<indexterm significance="preferred" zone="XkbSARedirectSetVMods"><primary><function>XkbSARedirectSetVMods</function></primary></indexterm> +<funcsynopsis id="XkbSARedirectSetVMods"> + <funcprototype> + <funcdef>void <function>XkbSARedirectSetVMods</function></funcdef> +<!-- ( +<parameter>act, vm</parameter> +) /* macro */ --> + + <paramdef>XkbRedirectKeyAction <parameter>act</parameter></paramdef> + <paramdef>unsigned int <parameter>v</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set vmods + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>v</parameter> + </term> + <listitem> + <para> + new value for virtual modifiers + </para> + </listitem> + </varlistentry> +</variablelist> +<para> + <function>XkbSARedirectSetVModsMask</function> sets the <structfield>vmods0</structfield> + and <structfield>vmods1</structfield> of <parameter>act</parameter> from <parameter>v</parameter>. +</para> </sect2> <sect2 id='Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease'> <title>Actions for Generating DeviceButtonPress and DeviceButtonRelease</title> - -<para> -Actions associated with <emphasis> -XkbDeviceBtnAction</emphasis> - structures generate <emphasis> -DeviceButtonPress</emphasis> - and <emphasis> -DeviceButtonRelease</emphasis> - events instead of normal <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events: -</para> - -<para><programlisting> +<indexterm significance="preferred" zone="Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease"> +<primary><structname>XkbDeviceBtnAction</structname></primary></indexterm> + +<para> +Actions associated with +<structname>XkbDeviceBtnAction</structname> +structures generate +<symbol>DeviceButtonPress</symbol> +and +<symbol>DeviceButtonRelease</symbol> +events instead of normal +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events: + +<programlisting> typedef struct _XkbDeviceBtnAction { - unsigned char type; /* <emphasis> XkbSA_DeviceBtn, XkbSA_LockDeviceBtn</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis> , specifies locking or unlocking */ - unsigned char count; /* controls number of DeviceButtonPress and Release events */ - unsigned char button; /* index of button on <emphasis> device</emphasis> */ - unsigned char device; /* device ID of an X input extension device */ -} <emphasis>XkbDeviceBtnAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_DeviceBtn</symbol>, <symbol>XkbSA_LockDeviceBtn</symbol> */ + unsigned char flags; /* with <structfield>type</structfield>, specifies locking or unlocking */ + unsigned char count; /* controls number of DeviceButtonPress + and Release events */ + unsigned char button; /* index of button on <structfield>device</structfield> */ + unsigned char device; /* device ID of an X input extension device */ +} <structname>XkbDeviceBtnAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field can have any one of the values shown in Table 16.17. +The +<structfield>type</structfield> +field can have any one of the values shown in +<link linkend="table16.17">Table 16.17</link>. </para> -<table frame='topbot'> +<table id='table16.17' frame='topbot'> <title>Device Button Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -3438,90 +3453,89 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_DeviceBtn</emphasis></entry> + <entry><symbol>XkbSA_DeviceBtn</symbol></entry> <entry> <itemizedlist> <listitem> <para> If the button specified by this action is logically down, the key press and corresponding release are ignored and have no effect. If the device or button -specified by this action are illegal, this action behaves like <emphasis> -XkbSA_NoAction</emphasis>. +specified by this action are illegal, this action behaves like +<symbol>XkbSA_NoAction</symbol>. </para> </listitem> <listitem> <para> Otherwise, key presses cause one or more input extension device events instead -of the usual key press event. If the <emphasis> -count</emphasis> - field is zero, a key press generates a single <emphasis> -DeviceButtonPress</emphasis> - event. If count is greater than zero, a key press event generates <emphasis> -count</emphasis> - pairs of <emphasis> -DeviceButtonPress</emphasis> - and <emphasis> -DeviceButtonRelease</emphasis> - events. +of the usual key press event. If the +<structfield>count</structfield> +field is zero, a key press generates a single +<symbol>DeviceButtonPress</symbol> +event. If count is greater than zero, a key press event generates +<structfield>count</structfield> +pairs of +<symbol>DeviceButtonPress</symbol> +and +<symbol>DeviceButtonRelease</symbol> +events. </para> </listitem> <listitem> <para> -If <emphasis> -count</emphasis> - is zero, a key release generates an input extension <emphasis> -DeviceButtonRelease</emphasis> - event that matches the event generated by the corresponding key press. If -<emphasis> -count</emphasis> - is nonzero, a key release does not cause a <emphasis> -DeviceButtonRelease</emphasis> - event. Key releases never cause <emphasis> -KeyRelease</emphasis> - events. +If +<structfield>count</structfield> +is zero, a key release generates an input extension +<symbol>DeviceButtonRelease</symbol> +event that matches the event generated by the corresponding key press. If +<structfield>count</structfield> +is nonzero, a key release does not cause a +<symbol>DeviceButtonRelease</symbol> +event. Key releases never cause +<symbol>KeyRelease</symbol> +events. </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LockDeviceBtn</emphasis></entry> + <entry><symbol>XkbSA_LockDeviceBtn</symbol></entry> <entry> <itemizedlist> <listitem> <para> If the device or button specified by this action are illegal, this action -behaves like <emphasis>XkbSA_NoAction</emphasis>. +behaves like <symbol>XkbSA_NoAction</symbol>. </para> </listitem> <listitem> <para> -Otherwise, if the specified button is not locked and the <emphasis> -XkbSA_LockNoLock</emphasis> - bit is not set in the <emphasis> -flags</emphasis> - field, a key press generates an input extension <emphasis> -DeviceButtonPress</emphasis> - event instead of a <emphasis> -KeyPress</emphasis> - event and locks the button. If the button is already locked or if <emphasis> -XkbSA_LockNoLock</emphasis> - bit is set in the <emphasis> -flags</emphasis> - field, the key press is ignored and has no effect. +Otherwise, if the specified button is not locked and the +<symbol>XkbSA_LockNoLock</symbol> +bit is not set in the +<structfield>flags</structfield> +field, a key press generates an input extension +<symbol>DeviceButtonPress</symbol> +event instead of a +<symbol>KeyPress</symbol> +event and locks the button. If the button is already locked or if +<symbol>XkbSA_LockNoLock</symbol> +bit is set in the +<structfield>flags</structfield> +field, the key press is ignored and has no effect. </para> </listitem> <listitem> <para> -If the corresponding key press was ignored, and if the <emphasis> -XkbSA_LockNoUnlock</emphasis> - bit is not set in the <emphasis> -flags</emphasis> - field, a key release generates an input extension <emphasis> -DeviceButtonRelease</emphasis> - event instead of a <emphasis> -KeyRelease</emphasis> - event and unlocks the button. If the corresponding key press locked a button, +If the corresponding key press was ignored, and if the +<symbol>XkbSA_LockNoUnlock</symbol> +bit is not set in the +<structfield>flags</structfield> +field, a key release generates an input extension +<symbol>DeviceButtonRelease</symbol> +event instead of a +<symbol>KeyRelease</symbol> +event and unlocks the button. If the corresponding key press locked a button, the key release is ignored and has no effect. </para> </listitem> @@ -3533,13 +3547,13 @@ the key release is ignored and has no effect. </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.18. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.18">Table 16.18</link>. </para> -<table frame='topbot'> +<table id='table16.18' frame='topbot'> <title>Device Button Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -3553,19 +3567,19 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockDeviceBtn</emphasis> -, the server only unlocks the button. +If set, and the action type is +<symbol>XkbSA_LockDeviceBtn</symbol>, +the server only unlocks the button. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockDeviceBtn</emphasis> -, the server only locks the button. +If set, and the action type is +<symbol>XkbSA_LockDeviceBtn</symbol>, +the server only locks the button. </entry> </row> </tbody> @@ -3575,64 +3589,71 @@ XkbSA_LockDeviceBtn</emphasis> </sect2> <sect2 id='Actions_for_Simulating_Events_from_Device_Valuators'> <title>Actions for Simulating Events from Device Valuators</title> - -<para> -A <emphasis> -valuator</emphasis> - manipulates a range of values for some entity, like a mouse axis, a slider or -a dial. Actions associated with <emphasis> -XkbDeviceValuatorAction</emphasis> - structures are used to simulate events from one or two input extension device +<indexterm significance="preferred" zone="Actions_for_Simulating_Events_from_Device_Valuators"> +<primary><structname>XkbDeviceValuatorAction</structname></primary></indexterm> + +<para> +A +<firstterm>valuator</firstterm> +<indexterm significance="preferred" zone="Actions_for_Simulating_Events_from_Device_Valuators"> +<primary>valuator</primary></indexterm> +manipulates a range of values for some entity, like a mouse axis, a slider or +a dial. Actions associated with +<structname>XkbDeviceValuatorAction</structname> +structures are used to simulate events from one or two input extension device valuators. </para> <para><programlisting> typedef struct _XkbDeviceValuatorAction { - unsigned char type; /*<emphasis> XkbSA_DeviceValuator</emphasis> */ - unsigned char device; /* device ID */ - unsigned char v1_what; /* determines how valuator is to behave for valuator 1 */ - unsigned char v1_ndx; /* specifies a real valuator */ - unsigned char v1_value; /* the value for valuator 1 */ - unsigned char v2_what; /* determines how valuator is to behave for valuator 2 */ - unsigned char v2_ndx; /* specifies a real valuator */ - unsigned char v2_value; /* the value for valuator 1 */ -} <emphasis>XkbDeviceValuatorAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_DeviceValuator</symbol> */ + unsigned char device; /* device ID */ + unsigned char v1_what; /* determines how valuator is + to behave for valuator 1 */ + unsigned char v1_ndx; /* specifies a real valuator */ + unsigned char v1_value; /* the value for valuator 1 */ + unsigned char v2_what; /* determines how valuator is + to behave for valuator 2 */ + unsigned char v2_ndx; /* specifies a real valuator */ + unsigned char v2_value; /* the value for valuator 1 */ +} <structname>XkbDeviceValuatorAction</structname>; </programlisting></para> <para> -If <emphasis> -device</emphasis> - is illegal or if neither <emphasis> -v1_ndx</emphasis> - nor <emphasis> -v2_ndx</emphasis> - specifies a legal valuator, this action behaves like <emphasis> -XkbSA_NoAction</emphasis>. -</para> - - -<para> -The low four bits of <emphasis> -v1_what</emphasis> - and <emphasis> -v2_what</emphasis> - specify the corresponding scale value (denoted <emphasis> -val<n>Scale</emphasis> - in Table 16.17), if needed. The high four bits of <emphasis> -v1_what</emphasis> - and <emphasis> -v2_what</emphasis> - specify the operation to perform to set the values. The high four bits of -<emphasis> -v1_what</emphasis> - and <emphasis> -v2_what</emphasis> - can have the values shown in Table 16.17; the use of <emphasis> -val<n>Scale</emphasis> - is shown in that table also. -</para> - -<table frame='topbot'> +If +<structfield>device</structfield> +is illegal or if neither +<structfield>v1_ndx</structfield> +nor +<structfield>v2_ndx</structfield> +specifies a legal valuator, this action behaves like +<symbol>XkbSA_NoAction</symbol>. +</para> + + +<para> +The low four bits of +<structfield>v1_what</structfield> +and +<structfield>v2_what</structfield> +specify the corresponding scale value (denoted +<structfield>val<n>Scale</structfield> +in <link linkend="table16.17">Table 16.17</link>), if needed. +The high four bits of +<structfield>v1_what</structfield> +and +<structfield>v2_what</structfield> +specify the operation to perform to set the values. The high four bits of +<structfield>v1_what</structfield> +and +<structfield>v2_what</structfield> +can have the values shown in <link linkend="table16.17">Table 16.17</link>; +the use of +<structfield>val<n>Scale</structfield> +is shown in that table also. +</para> + +<table id='table16.19' frame='topbot'> <title>Device Valuator v<n>_what High Bits Values</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -3646,40 +3667,40 @@ val<n>Scale</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_IgnoreVal</emphasis></entry> + <entry><symbol>XkbSA_IgnoreVal</symbol></entry> <entry>No action</entry> </row> <row> - <entry><emphasis>XkbSA_SetValMin</emphasis></entry> + <entry><symbol>XkbSA_SetValMin</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis> is set to its minimum legal value. +<structfield>v<n>_value</structfield> is set to its minimum legal value. </entry> </row> <row> - <entry><emphasis>XkbSA_SetValCenter</emphasis></entry> + <entry><symbol>XkbSA_SetValCenter</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis>is centered (to (max-min)/2). +<structfield>v<n>_value</structfield>is centered (to (max-min)/2). </entry> </row> <row> - <entry><emphasis>XkbSA_SetValMax</emphasis></entry> + <entry><symbol>XkbSA_SetValMax</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis> is set to its maximum legal value. +<structfield>v<n>_value</structfield> is set to its maximum legal value. </entry> </row> <row> - <entry><emphasis>XkbSA_SetValRelative</emphasis></entry> + <entry><symbol>XkbSA_SetValRelative</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis> * (2 -<emphasis>val<n>Scale</emphasis>) is added to -<emphasis>v<n>_value</emphasis>. +<structfield>v<n>_value</structfield> * (2 +<structfield>val<n>Scale</structfield>) is added to +<structfield>v<n>_value</structfield>. </entry> </row> <row> - <entry><emphasis>XkbSA_SetValAbsolute</emphasis></entry> + <entry><symbol>XkbSA_SetValAbsolute</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis> - is set to (2 <emphasis>val<n>Scale</emphasis>). +<structfield>v<n>_value</structfield> +is set to (2 <structfield>val<n>Scale</structfield>). </entry> </row> </tbody> @@ -3687,39 +3708,37 @@ val<n>Scale</emphasis> </table> <para> -Illegal values for <emphasis> -XkbSA_SetValRelative</emphasis> - or <emphasis> -XkbSA_SetValAbsolute</emphasis> - are clamped into range. Note that all of these possibilities are legal for -absolute valuators. For relative valuators, only <emphasis> -XkbSA_SetValRelative</emphasis> - is permitted. Part of the input extension description of a device is the range +Illegal values for +<symbol>XkbSA_SetValRelative</symbol> +or +<symbol>XkbSA_SetValAbsolute</symbol> +are clamped into range. Note that all of these possibilities are legal for +absolute valuators. For relative valuators, only +<symbol>XkbSA_SetValRelative</symbol> +is permitted. Part of the input extension description of a device is the range of legal values for all absolute valuators, whence the maximum and minimum -legal values shown in Table 16.17. +legal values shown in <link linkend="table16.17">Table 16.17</link>. </para> <para> The following two masks are provided as a convenience to select either portion -of <emphasis> -v1_what</emphasis> - or <emphasis> -v2_what</emphasis> -: -</para> +of +<structfield>v1_what</structfield> +or +<structfield>v2_what</structfield>: -<literallayout> - #define XkbSA_ValOpMask (0x70) - #define XkbSA_ValScaleMask (0x07) -</literallayout> +<programlisting> +#define XkbSA_ValOpMask (0x70) +#define XkbSA_ValScaleMask (0x07) +</programlisting> +</para> <para> -<emphasis> -v1_ndx</emphasis> - and <emphasis> -v2_ndx</emphasis> - specify valuators that actually exists. For example, most mice have two +<structfield>v1_ndx</structfield> +and +<structfield>v2_ndx</structfield> +specify valuators that actually exists. For example, most mice have two valuators (x and y axes) so the only legal values for a mouse would be 0 and 1. For a dial box with eight dials, any value in the range 0..7 would be correct. </para> @@ -3730,118 +3749,120 @@ For a dial box with eight dials, any value in the range 0..7 would be correct. <title>Obtaining Key Actions for Keys from the Server</title> <para> -To update the actions (the <emphasis> -key_acts</emphasis> - array) for a subset of the keys in a keyboard description, use <emphasis> -XkbGetKeyActions</emphasis> -. -</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> -XkbGetKeyActions</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -, <emphasis> -num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first</emphasis> -; /* keycode of first key of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* number of keys desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* pointer to keyboard description where result is stored */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To update the actions (the +<structfield>key_acts</structfield> +array) for a subset of the keys in a keyboard description, use +<function>XkbGetKeyActions</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetKeyActions"><primary><function>XkbGetKeyActions</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyActions"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyActions</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + number of keys desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + pointer to keyboard description where result is stored + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyActions</emphasis> - sends a request to the server to obtain the actions for <emphasis> -num</emphasis> - keys on the keyboard starting with key <emphasis> -first</emphasis> -. It waits for a reply and returns the actions in the <emphasis> -server</emphasis> --><emphasis> -key_acts</emphasis> - field of <emphasis> -xkb</emphasis> -. If successful, <emphasis> -XkbGetKeyActions</emphasis> - returns <emphasis> -Success</emphasis> -. The <emphasis> -xkb</emphasis> - parameter must be a pointer to a valid Xkb keyboard description. +<function>XkbGetKeyActions</function> +sends a request to the server to obtain the actions for +<parameter>num</parameter> +keys on the keyboard starting with key +<parameter>first</parameter>. +It waits for a reply and returns the actions in the +<structfield>server</structfield>-><structfield>key_acts</structfield> +field of +<parameter>xkb</parameter>. +If successful, +<function>XkbGetKeyActions</function> +returns +<symbol>Success</symbol>. +The +<parameter>xkb</parameter> +parameter must be a pointer to a valid Xkb keyboard description. </para> <para> -If the <emphasis> -server</emphasis> - map in the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeyActions</emphasis> - allocates and initializes it before obtaining the actions. +If the +<structfield>server</structfield> +map in the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeyActions</function> +allocates and initializes it before obtaining the actions. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetKeyActions</emphasis> - returns <emphasis> -BadAccess</emphasis> -. If <emphasis> -num</emphasis> - is less than 1 or greater than <emphasis> -XkbMaxKeyCount</emphasis> -, <emphasis> -XkbGetKeyActions</emphasis> - returns <emphasis> -BadValue</emphasis> -. If any allocation errors occur, <emphasis> -XkbGetKeyActions</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +has not been properly initialized, +<function>XkbGetKeyActions</function> +returns +<errorname>BadAccess</errorname>. +If +<parameter>num</parameter> +is less than 1 or greater than +<symbol>XkbMaxKeyCount</symbol>, +<function>XkbGetKeyActions</function> +returns +<errorname>BadValue</errorname>. +If any allocation errors occur, +<function>XkbGetKeyActions</function> +returns +<errorname>BadAlloc</errorname>. </para> @@ -3850,128 +3871,126 @@ BadAlloc</emphasis> <title>Changing the Number of Actions Bound to a Key</title> <para> -To change the number of actions bound to a key, use <emphasis> -XkbResizeKeyAction</emphasis> -. -</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'> -XkbAction *<emphasis> -XkbResizeKeyActions</emphasis> -(<emphasis> -xkb</emphasis> -,<emphasis> - key</emphasis> -,<emphasis> - needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescRec *<emphasis> - xkb</emphasis> -; /* keyboard description to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - key</emphasis> -; /* keycode of key to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - needed</emphasis> -; /* new number of actions required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The <emphasis> -xkb</emphasis> - parameter points to the keyboard description containing the <emphasis> -key</emphasis> - whose number of actions is to be changed. The <emphasis> -key</emphasis> - parameter is the keycode of the key to change, and <emphasis> -needed</emphasis> - specifies the new number of actions required for the key. -</para> - - -<para> -<emphasis> -XkbResizeKeyActions</emphasis> - reserves the space needed for the actions and returns a pointer to the -beginning of the new array that holds the actions. It can change the <emphasis> -acts</emphasis> -, <emphasis> -num_acts</emphasis> -, and <emphasis> -size_acts</emphasis> - fields of <emphasis> -xkb</emphasis> --><emphasis> -server</emphasis> - if it is necessary to reallocate the <emphasis> -acts </emphasis> +To change the number of actions bound to a key, use +<function>XkbResizeKeyActions</function>. +</para> + +<indexterm significance="preferred" zone="XkbResizeKeyActions"><primary><function>XkbResizeKeyActions</function></primary></indexterm> +<funcsynopsis id="XkbResizeKeyActions"> + <funcprototype> + <funcdef>XkbAction *<function>XkbResizeKeyActions</function></funcdef> +<!-- ( +<parameter>xkb</parameter>, +<parameter>key</parameter>, +<parameter>needed</parameter> +) --> + + <paramdef>XkbDescRec *<parameter>xkb</parameter></paramdef> + <paramdef>int <parameter>key</parameter></paramdef> + <paramdef>int <parameter>needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>key</parameter> + </term> + <listitem> + <para> + keycode of key to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>needed</parameter> + </term> + <listitem> + <para> + new number of actions required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>xkb</parameter> +parameter points to the keyboard description containing the +<parameter>key</parameter> +whose number of actions is to be changed. The +<parameter>key</parameter> +parameter is the keycode of the key to change, and +<parameter>needed</parameter> +specifies the new number of actions required for the key. +</para> + + +<para> +<function>XkbResizeKeyActions</function> +reserves the space needed for the actions and returns a pointer to the +beginning of the new array that holds the actions. It can change the +<structfield>acts</structfield>, +<structfield>num_acts</structfield>, +and +<structfield>size_acts</structfield> +fields of +<parameter>xkb</parameter>-><structfield>server</structfield> +if it is necessary to reallocate the +<structfield>acts</structfield> array. </para> <para> -If <emphasis> -needed</emphasis> - is greater than the current number of keysyms for the key, <emphasis> -XkbResizeKeyActions</emphasis> - initializes all new actions in the array to <emphasis> -NoAction</emphasis> -. +If +<parameter>needed</parameter> +is greater than the current number of keysyms for the key, +<function>XkbResizeKeyActions</function> +initializes all new actions in the array to +<emphasis>NoAction</emphasis>. </para> <para> Because the number of actions needed by a key is normally computed as width * -number of groups, and <emphasis> -XkbResizeKeyActions</emphasis> - does not modify either the width or number of groups for the key, a -discrepancy exists on return from <emphasis> -XkbResizeKeyActions</emphasis> - between the space allocated for the actions and the number required. The -unused entries in the list of actions returned by <emphasis> -XkbResizeKeyActions</emphasis> - are not preserved across future calls to any of the map editing functions, so +number of groups, and +<function>XkbResizeKeyActions</function> +does not modify either the width or number of groups for the key, a +discrepancy exists on return from +<function>XkbResizeKeyActions</function> +between the space allocated for the actions and the number required. The +unused entries in the list of actions returned by +<function>XkbResizeKeyActions</function> +are not preserved across future calls to any of the map editing functions, so you must update the key actions (which updates the width and number of groups -for the key) before calling another allocator function. A call to <emphasis> -XkbChangeTypesOfKey</emphasis> - updates these. +for the key) before calling another allocator function. A call to +<function>XkbChangeTypesOfKey</function> +updates these. </para> <para> If any allocation errors occur while resizing the number of actions bound to -the key, <emphasis> -XkbResizeKeyActions</emphasis> - returns <emphasis> -NULL</emphasis> -. +the key, +<function>XkbResizeKeyActions</function> +returns +<symbol>NULL</symbol>. </para> <note><para>A change to the number of actions bound to a key should be accompanied by a change in the number of symbols bound to a key. Refer to -section 15.3.7 for more information on changing the number of symbols bound to +<link linkend="Changing_the_Number_of_Symbols_Bound_to_a_Key">section 15.3.7</link> for more information on changing the number of symbols bound to a key.</para></note> @@ -3982,9 +4001,9 @@ a key.</para></note> <para> Key behavior refers to the demeanor of a key. For example, the expected -behavior of the <emphasis> -CapsLock</emphasis> - key is that it logically locks when pressed, and then logically unlocks when +behavior of the +<keycap>CapsLock</keycap> +key is that it logically locks when pressed, and then logically unlocks when pressed again. </para> @@ -3993,80 +4012,79 @@ pressed again. <title>Radio Groups</title> <para> -Keys that belong to the same radio group have the <emphasis> -XkbKB_RadioGroup</emphasis> - type in the <emphasis> -type</emphasis> - field and the radio group index specified in the <emphasis> -data</emphasis> - field in the <emphasis> -XkbBehavior</emphasis> - structure. If the radio group has a name in the <emphasis> -XkbNamesRec</emphasis> - structure, the radio group index is the index into the <emphasis> -radio_group</emphasis> - array in the <emphasis> -XkbNamesRec</emphasis> - structure. A radio group key when pressed stays logically down until another +Keys that belong to the same radio group have the +<symbol>XkbKB_RadioGroup</symbol> +type in the +<structfield>type</structfield> +field and the radio group index specified in the +<structfield>data</structfield> +field in the +<structname>XkbBehavior</structname> +structure. If the radio group has a name in the +<structname>XkbNamesRec</structname> +structure, the radio group index is the index into the +<structfield>radio_group</structfield> +array in the +<structname>XkbNamesRec</structname> +structure. A radio group key when pressed stays logically down until another key in the radio group is pressed, when the first key becomes logically up and -the new key becomes logically down. Setting the <emphasis> -XkbKB_RGAllowNone</emphasis> - bit in the behavior for all of the keys of the radio group means that pressing +the new key becomes logically down. Setting the +<symbol>XkbKB_RGAllowNone</symbol> +bit in the behavior for all of the keys of the radio group means that pressing the logically down member of the radio group causes it to logically release, in which case none of the keys of the radio group would be logically down. If -<emphasis> -XkbKB_RGAllowNone</emphasis> - is not set, there is no way to release the logically down member of the group. +<symbol>XkbKB_RGAllowNone</symbol> +is not set, there is no way to release the logically down member of the group. </para> <para> -The low five bits of the <emphasis> -data</emphasis> - field of the <emphasis> -XkbBehavior</emphasis> - structure are the group number, the high three bits are flags. The only flag +The low five bits of the +<structfield>data</structfield> +field of the +<structname>XkbBehavior</structname> +structure are the group number, the high three bits are flags. The only flag currently defined is: -</para> -<para><programlisting> -#define XkbRG_AllowNone 0x80 +<programlisting> +#define XkbKB_RGAllowNone 0x80 </programlisting></para> </sect2> <sect2 id='The_XkbBehavior_Structure'> <title>The XkbBehavior Structure</title> +<indexterm significance="preferred" zone="The_XkbBehavior_Structure"> +<primary><structname>XkbBehavior</structname></primary></indexterm> <para> -The <emphasis> -behaviors</emphasis> - field of the server map is an array of <emphasis> -XkbBehavior</emphasis> - structures, indexed by keycode, and contains the behavior for each key. The -<emphasis> -XkbBehavior</emphasis> - structure is defined as follows: -</para> +The +<structfield>behaviors</structfield> +field of the server map is an array of +<structname>XkbBehavior</structname> +structures, indexed by keycode, and contains the behavior for each key. The +<structname>XkbBehavior</structname> +structure is defined as follows: -<para><programlisting> +<programlisting> typedef struct _XkbBehavior { - unsigned char type; /* behavior type + optional - <emphasis> XkbKB_Permanent</emphasis> bit */ - unsigned char data; -} <emphasis>XkbBehavior</emphasis>; + unsigned char type; /* behavior type + optional + <symbol>XkbKB_Permanent</symbol> bit */ + unsigned char data; +} <structname>XkbBehavior</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field specifies the Xkb behavior, and the value of the <emphasis> -data</emphasis> - field depends on the <emphasis> -type</emphasis> -. Xkb supports the key behaviors shown in Table 16.20. +The +<structfield>type</structfield> +field specifies the Xkb behavior, and the value of the +<structfield>data</structfield> +field depends on the +<structfield>type</structfield>. +Xkb supports the key behaviors shown in +<link linkend="table16.20">Table 16.20</link>. </para> -<table frame='topbot'> +<table id='table16.20' frame='topbot'> <title>Key Behaviors</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -4080,43 +4098,43 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbKB_Default</emphasis></entry> + <entry><symbol>XkbKB_Default</symbol></entry> <entry> -Press and release events are processed normally. The <emphasis> -data</emphasis> - field is unused. +Press and release events are processed normally. The +<structfield>data</structfield> +field is unused. </entry> </row> <row> - <entry><emphasis>XkbKB_Lock</emphasis></entry> + <entry><symbol>XkbKB_Lock</symbol></entry> <entry> If a key is logically up (that is, the corresponding bit of the core key map is cleared) when it is pressed, the key press is processed normally and the corresponding release is ignored. If the key is logically down when pressed, the key press is ignored but the corresponding release is processed normally. -The <emphasis> -data</emphasis> - field is unused. +The +<structfield>data</structfield> +field is unused. </entry> </row> <row> - <entry><emphasis>XkbKB_RadioGroup</emphasis></entry> + <entry><symbol>XkbKB_RadioGroup</symbol></entry> <entry> <para> If another member of the radio group is logically down (all members of the -radio group have the same index, specified in <emphasis> -data</emphasis> -) when a key is pressed, the server synthesizes a key release for the member +radio group have the same index, specified in +<structfield>data</structfield>) +when a key is pressed, the server synthesizes a key release for the member that is logically down and then processes the new key press event normally. </para> <para> If the key itself is logically down when pressed, the key press event is ignored, but the processing of the corresponding key release depends on the -value of the <emphasis> -Xkb_RGAllowNone</emphasis> - bit in <emphasis> -flags</emphasis> -. If it is set, the key release is processed normally; otherwise, the key +value of the +<symbol>XkbKB_RGAllowNone</symbol> +bit in +<structfield>flags</structfield>. +If it is set, the key release is processed normally; otherwise, the key release is also ignored. </para> <para> @@ -4125,29 +4143,29 @@ All other key release events are ignored. </entry> </row> <row> - <entry><emphasis>XkbKB_Overlay1</emphasis></entry> + <entry><symbol>XkbKB_Overlay1</symbol></entry> <entry> -If the <emphasis> -Overlay1</emphasis> - control is enabled (see section 10.4), <emphasis> -data</emphasis> - is interpreted as a keycode, and events from this key are reported as if they -came from <emphasis> -data</emphasis> -’s keycode. Otherwise, press and release events are processed normally. +If the +<emphasis>Overlay1</emphasis> +control is enabled (see <link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">section 10.4</link>), +<structfield>data</structfield> +is interpreted as a keycode, and events from this key are reported as if they +came from +<structfield>data</structfield>’s +keycode. Otherwise, press and release events are processed normally. </entry> </row> <row> - <entry><emphasis>XkbKB_Overlay2</emphasis></entry> + <entry><symbol>XkbKB_Overlay2</symbol></entry> <entry> -If the <emphasis> -Overlay2</emphasis> - control is enabled (see section 10.4), <emphasis> -data</emphasis> - is interpreted as a keycode, and events from this key are reported as if they -came from <emphasis> -data</emphasis> -’s keycode. Otherwise, press and release events are processed normally. +If the +<emphasis>Overlay2</emphasis> +control is enabled (see <link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">section 10.4</link>), +<structfield>data</structfield> +is interpreted as a keycode, and events from this key are reported as if they +came from +<structfield>data</structfield>’s +keycode. Otherwise, press and release events are processed normally. </entry> </row> </tbody> @@ -4155,15 +4173,15 @@ data</emphasis> </table> <para> -Xkb also provides the mask, <emphasis> -XkbKB_Permanent</emphasis> - to specify whether the key behavior type should be simulated by Xkb or whether +Xkb also provides the mask, +<symbol>XkbKB_Permanent</symbol> +to specify whether the key behavior type should be simulated by Xkb or whether the key behavior describes an unalterable physical, electrical, or software -aspect of the keyboard. If the <emphasis> -XkbKB_Permanent</emphasis> - bit is not set in the <emphasis> -type</emphasis> - field, Xkb simulates the behavior in software. Otherwise, Xkb relies upon the +aspect of the keyboard. If the +<symbol>XkbKB_Permanent</symbol> +bit is not set in the +<structfield>type</structfield> +field, Xkb simulates the behavior in software. Otherwise, Xkb relies upon the keyboard to implement the behavior. </para> @@ -4173,117 +4191,118 @@ keyboard to implement the behavior. <title>Obtaining Key Behaviors for Keys from the Server</title> <para> -To obtain the behaviors (the <emphasis> -behaviors</emphasis> - array) for a subset of the keys in a keyboard description from the server, use -<emphasis> -XkbGetKeyBehaviors</emphasis> -: -</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> -XkbGetKeyBehaviors</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first</emphasis> -; /* keycode of first key to get */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* number of keys for which behaviors are desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description to contain the result */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To obtain the behaviors (the +<structfield>behaviors</structfield> +array) for a subset of the keys in a keyboard description from the server, use +<function>XkbGetKeyBehaviors</function>: + +</para> + +<indexterm significance="preferred" zone="XkbGetKeyBehaviors"><primary><function>XkbGetKeyBehaviors</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyBehaviors"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyBehaviors</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key to get + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + number of keys for which behaviors are desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description to contain the result + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyBehaviors</emphasis> - sends a request to the server to obtain the behaviors for <emphasis> -num</emphasis> - keys on the keyboard starting with the key whose keycode is <emphasis> -first</emphasis> -. It waits for a reply and returns the behaviors in the <emphasis> -server</emphasis> --><emphasis> -behaviors</emphasis> - field of <emphasis> -xkb</emphasis> -. If successful, <emphasis> -XkbGetKeyBehaviors</emphasis> - returns <emphasis> -Success</emphasis> -. +<function>XkbGetKeyBehaviors</function> +sends a request to the server to obtain the behaviors for +<parameter>num</parameter> +keys on the keyboard starting with the key whose keycode is +<parameter>first</parameter>. +It waits for a reply and returns the behaviors in the +<structfield>server</structfield>-><structfield>behaviors</structfield> +field of +<parameter>xkb</parameter>. +If successful, +<function>XkbGetKeyBehaviors</function> +returns +<symbol>Success</symbol>. </para> <para> -If the <emphasis> -server</emphasis> - map in the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeyBehaviors</emphasis> - allocates and initializes it before obtaining the actions. +If the +<structfield>server</structfield> +map in the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeyBehaviors</function> +allocates and initializes it before obtaining the actions. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetKeyBehaviors</emphasis> - returns <emphasis> -BadAccess</emphasis> -. If <emphasis> -num</emphasis> - is less than 1 or greater than <emphasis> -XkbMaxKeyCount</emphasis> -, <emphasis> -XkbGetKeyBehaviors</emphasis> - returns <emphasis> -BadValue</emphasis> -. If any allocation errors occur, <emphasis> -XkbGetKeyBehaviors</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +has not been properly initialized, +<function>XkbGetKeyBehaviors</function> +returns +<errorname>BadAccess</errorname>. +If +<parameter>num</parameter> +is less than 1 or greater than +<symbol>XkbMaxKeyCount</symbol>, +<function>XkbGetKeyBehaviors</function> +returns +<errorname>BadValue</errorname>. +If any allocation errors occur, +<function>XkbGetKeyBehaviors</function> +returns +<errorname>BadAlloc</errorname>. </para> @@ -4295,7 +4314,7 @@ BadAlloc</emphasis> <para> Whenever a client remaps the keyboard using core protocol requests, Xkb examines the map to determine likely default values for the components that -cannot be specified using the core protocol (see section 17.1.2 for more +cannot be specified using the core protocol (see <link linkend="Core_Keyboard_Mapping_to_Xkb_Keyboard_Mapping_Transformation">section 17.1.2</link> for more information on how Xkb chooses the default values). </para> @@ -4310,14 +4329,14 @@ mapping. <para> -The explicit components masks are held in the <emphasis> -explicit</emphasis> - field of the server map, which is an array indexed by keycode. Each entry in +The explicit components masks are held in the +<structfield>explicit</structfield> +field of the server map, which is an array indexed by keycode. Each entry in this array is a mask that is a bitwise inclusive OR of the values shown in -Table 16.21. +<link linkend="table16.21">Table 16.21</link>. </para> -<table frame='topbot'> +<table id='table16.21' frame='topbot'> <title>Explicit Component Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -4336,32 +4355,32 @@ Table 16.21. <entry><emphasis>ExplicitKeyType1</emphasis></entry> <entry>(1<<0)</entry> <entry> -Automatic determination of the key type associated with <emphasis> -Group1.</emphasis> +Automatic determination of the key type associated with +<emphasis>Group1</emphasis>. </entry> </row> <row> <entry><emphasis>ExplicitKeyType2</emphasis></entry> <entry>(1<<1)</entry> <entry> -Automatic determination of the key type associated with <emphasis> -Group2.</emphasis> +Automatic determination of the key type associated with +<emphasis>Group2</emphasis>. </entry> </row> <row> <entry><emphasis>ExplicitKeyType3</emphasis></entry> <entry>(1<<2)</entry> <entry> -Automatic determination of the key type associated with <emphasis> -Group3.</emphasis> +Automatic determination of the key type associated with +<emphasis>Group3</emphasis>. </entry> </row> <row> <entry><emphasis>ExplicitKeyType4</emphasis></entry> <entry>(1<<3)</entry> <entry> -Automatic determination of the key type associated with <emphasis> -Group4.</emphasis> +Automatic determination of the key type associated with +<emphasis>Group4</emphasis>. </entry> </row> <row> @@ -4382,11 +4401,11 @@ specified in a symbol interpretation.</entry> <entry><emphasis>ExplicitBehavior</emphasis></entry> <entry>(1<<6)</entry> <entry> -Automatic assignment of the <emphasis> -XkbKB_Lock</emphasis> - behavior to the key, if the <emphasis> -XkbSI_LockingKey</emphasis> - flag is set in a symbol interpretation. +Automatic assignment of the +<symbol>XkbKB_Lock</symbol> +behavior to the key, if the +<symbol>XkbSI_LockingKey</symbol> +flag is set in a symbol interpretation. </entry> </row> <row> @@ -4406,117 +4425,120 @@ match the key. <title>Obtaining Explicit Components for Keys from the Server</title> <para> -To obtain the explicit components (the <emphasis> -explicit</emphasis> - array) for a subset of the keys in a keyboard description, use <emphasis> -XkbGetKeyExplicitComponents</emphasis>. -</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> -XkbGetKeyExplicitComponents</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first</emphasis> -; /* keycode of first key to fetch */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* number of keys for which to get explicit info */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description in which to put results */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To obtain the explicit components (the +<structfield>explicit</structfield> +array) for a subset of the keys in a keyboard description, use +<function>XkbGetKeyExplicitComponents</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetKeyExplicitComponents"><primary><function>XkbGetKeyExplicitComponents</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyExplicitComponents"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyExplicitComponents</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key to fetch + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + number of keys for which to get explicit info + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description in which to put results + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyExplicitComponents</emphasis> - sends a request to the server to obtain the explicit components for <emphasis> -num</emphasis> - keys on the keyboard starting with key <emphasis> -first</emphasis> -. It waits for a reply and returns the explicit components in the <emphasis> -server</emphasis> --><emphasis> -explicit</emphasis> - array of <emphasis> -xkb</emphasis> -. If successful, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - returns <emphasis> -Success</emphasis> -. The <emphasis> -xkb</emphasis> - parameter must be a pointer to a valid Xkb keyboard description. +<function>XkbGetKeyExplicitComponents</function> +sends a request to the server to obtain the explicit components for +<parameter>num</parameter> +keys on the keyboard starting with key +<parameter>first</parameter>. +It waits for a reply and returns the explicit components in the +<structfield>server</structfield>-><structfield>explicit</structfield> +array of +<parameter>xkb</parameter>. +If successful, +<function>XkbGetKeyExplicitComponents</function> +returns +<symbol>Success</symbol>. +The +<parameter>xkb</parameter> +parameter must be a pointer to a valid Xkb keyboard description. </para> <para> -If the <emphasis> -server</emphasis> - map in the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - allocates and initializes it before obtaining the actions. +If the +<structfield>server</structfield> +map in the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeyExplicitComponents</function> +allocates and initializes it before obtaining the actions. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - returns <emphasis> -BadMatch</emphasis> -. If <emphasis> -num</emphasis> - is less than 1 or greater than <emphasis> -XkbMaxKeyCount</emphasis> -, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - returns <emphasis> -BadValue</emphasis> -. If any allocation errors occur, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +has not been properly initialized, +<function>XkbGetKeyExplicitComponents</function> +returns +<errorname>BadMatch</errorname>. +If +<parameter>num</parameter> +is less than 1 or greater than +<symbol>XkbMaxKeyCount</symbol>, +<function>XkbGetKeyExplicitComponents</function> +returns +<errorname>BadValue</errorname>. +If any allocation errors occur, +<function>XkbGetKeyExplicitComponents</function> +returns +<errorname>BadAlloc</errorname>. </para> @@ -4526,71 +4548,71 @@ BadAlloc</emphasis> <title>Virtual Modifier Mapping</title> <para> -The <emphasis> -vmods</emphasis> - member of the server map is a fixed-length array containing <emphasis> -XkbNumVirtualMods</emphasis> - entries. Each entry corresponds to a virtual modifier and provides the binding -of the virtual modifier to the real modifier bits. Each entry in the <emphasis> -vmods</emphasis> - array is a bitwise inclusive OR of the legal modifier masks: -</para> - -<literallayout> - <emphasis>ShiftMask</emphasis> - <emphasis>LockMask</emphasis> - <emphasis>ControlMask</emphasis> - <emphasis>Mod1Mask</emphasis> - <emphasis>Mod2Mask</emphasis> - <emphasis>Mod3Mask</emphasis> - <emphasis>Mod4Mask</emphasis> - <emphasis>Mod5Mask</emphasis> -</literallayout> - -<para> -The <emphasis> -vmodmap</emphasis> - member of the server map is similar to the <emphasis> -modmap</emphasis> - array of the client map (see section 15.4), but is used to define the virtual -modifier mapping for each key. Like the <emphasis> -modmap</emphasis> - member, it is indexed by keycode, and each entry is a mask representing the +The +<structfield>vmods</structfield> +member of the server map is a fixed-length array containing +<symbol>XkbNumVirtualMods</symbol> +entries. Each entry corresponds to a virtual modifier and provides the binding +of the virtual modifier to the real modifier bits. Each entry in the +<structfield>vmods</structfield> +array is a bitwise inclusive OR of the legal modifier masks: +</para> + +<simplelist type='vert' columns='1'> + <member><symbol>ShiftMask</symbol></member> + <member><symbol>LockMask</symbol></member> + <member><symbol>ControlMask</symbol></member> + <member><symbol>Mod1Mask</symbol></member> + <member><symbol>Mod2Mask</symbol></member> + <member><symbol>Mod3Mask</symbol></member> + <member><symbol>Mod4Mask</symbol></member> + <member><symbol>Mod5Mask</symbol></member> +</simplelist> + +<para> +The +<structfield>vmodmap</structfield> +member of the server map is similar to the +<structfield>modmap</structfield> +array of the client map (see <link linkend="The_Per_Key_Modifier_Map">section 15.4</link>), but is used to define the virtual +modifier mapping for each key. Like the +<structfield>modmap</structfield> +member, it is indexed by keycode, and each entry is a mask representing the virtual modifiers bound to the corresponding key: </para> <itemizedlist> <listitem> <para> -Each of the bits in a <emphasis> -vmodmap</emphasis> - entry represents an index into the <emphasis> -vmods</emphasis> - member. That is, bit 0 of a <emphasis> -vmodmap</emphasis> - entry refers to index 0 of the <emphasis> -vmods</emphasis> - array, bit 1 refers to index 1, and so on. +Each of the bits in a +<structfield>vmodmap</structfield> +entry represents an index into the +<structfield>vmods</structfield> +member. That is, bit 0 of a +<structfield>vmodmap</structfield> +entry refers to index 0 of the +<structfield>vmods</structfield> +array, bit 1 refers to index 1, and so on. </para> </listitem> <listitem> <para> -If a bit is set in the <emphasis> -vmodmap</emphasis> - entry for a key, that key is bound to the corresponding virtual modifier in -the <emphasis> -vmods</emphasis> - array. +If a bit is set in the +<structfield>vmodmap</structfield> +entry for a key, that key is bound to the corresponding virtual modifier in +the +<structfield>vmods</structfield> +array. </para> </listitem> </itemizedlist> <para> -The <emphasis> -vmodmap</emphasis> - and <emphasis> -vmods</emphasis> - members of the server map are the "master" virtual modifier definitions. Xkb +The +<structfield>vmodmap</structfield> +and +<structfield>vmods</structfield> +members of the server map are the <quote>master</quote> virtual modifier definitions. Xkb automatically propagates any changes to these fields to all other fields that use virtual modifier mappings. </para> @@ -4598,14 +4620,16 @@ use virtual modifier mappings. <para> The overall relationship of fields dealing with virtual modifiers in an Xkb -keyboard description are shown in Figure 16.2. +keyboard description are shown in <link linkend="figure16.2">Figure 16.2</link>. </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-17.svg"/> - </imageobject> -<caption>Virtual Modifier Relationships</caption> -</mediaobject> +<figure id='figure16.2'> + <title>Virtual Modifier Relationships</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-17.svg"/> + </imageobject> + </mediaobject> +</figure> @@ -4618,104 +4642,106 @@ Virtual Modifier Relationships</H5> <title>Obtaining Virtual Modifier Bindings from the Server</title> <para> -To obtain a subset of the virtual modifier bindings (the <emphasis> -vmods</emphasis> - array) in a keyboard description, use <emphasis> -XkbGetVirtualMods</emphasis> -: -</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> -XkbGetVirtualMods</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - which</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask indicating virtual modifier bindings to get */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description where results will be placed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To obtain a subset of the virtual modifier bindings (the +<structfield>vmods</structfield> +array) in a keyboard description, use +<function>XkbGetVirtualMods</function>: + +</para> + +<indexterm significance="preferred" zone="XkbGetVirtualMods"><primary><function>XkbGetVirtualMods</function></primary></indexterm> +<funcsynopsis id="XkbGetVirtualMods"> + <funcprototype> + <funcdef>Status <function>XkbGetVirtualMods</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>which</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask indicating virtual modifier bindings to get + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description where results will be placed + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetVirtualMods</emphasis> - sends a request to the server to obtain the <emphasis> -vmods</emphasis> - entries for the virtual modifiers specified in the mask, <emphasis> -which</emphasis> -, and waits for a reply. See section 7.1 for a description of how to determine -the virtual modifier mask. For each bit set in <emphasis> -which</emphasis> -, <emphasis> -XkbGetVirtualMods</emphasis> - updates the corresponding virtual modifier definition in the <emphasis> -server->vmods</emphasis> - array of <emphasis> -xkb</emphasis> -. The <emphasis> -xkb</emphasis> - parameter must be a pointer to a valid Xkb keyboard description. If -successful, <emphasis> -XkbGetVirtualMods</emphasis> - returns <emphasis> -Success</emphasis> -. +<function>XkbGetVirtualMods</function> +sends a request to the server to obtain the +<structfield>vmods</structfield> +entries for the virtual modifiers specified in the mask, +<parameter>which</parameter>, +and waits for a reply. See <link linkend="Virtual_Modifier_Names_and_Masks">section 7.1</link> for a description of how to determine +the virtual modifier mask. For each bit set in +<parameter>which</parameter>, +<function>XkbGetVirtualMods</function> +updates the corresponding virtual modifier definition in the +<structfield>server->vmods</structfield> +array of +<parameter>xkb</parameter>. +The +<parameter>xkb</parameter> +parameter must be a pointer to a valid Xkb keyboard description. If +successful, +<function>XkbGetVirtualMods</function> +returns +<symbol>Success</symbol>. </para> <para> -If the <emphasis> -server</emphasis> - map has not been allocated in the <emphasis> -xkb</emphasis> - parameter, <emphasis> -XkbGetVirtualMods</emphasis> - allocates and initializes it before obtaining the virtual modifier bindings. +If the +<structfield>server</structfield> +map has not been allocated in the +<parameter>xkb</parameter> +parameter, +<function>XkbGetVirtualMods</function> +allocates and initializes it before obtaining the virtual modifier bindings. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetVirtualMods</emphasis> - returns <emphasis> -BadMatch</emphasis> -. Any errors in allocation cause <emphasis> -XkbGetVirtualMods </emphasis> -to return <emphasis> -BadAlloc</emphasis>. +has not been properly initialized, +<function>XkbGetVirtualMods</function> +returns +<errorname>BadMatch</errorname>. +Any errors in allocation cause +<function>XkbGetVirtualMods</function> +to return +<errorname>BadAlloc</errorname>. </para> @@ -4724,120 +4750,121 @@ BadAlloc</emphasis>. <title>Obtaining Per-Key Virtual Modifier Mappings from the Server</title> <para> -To obtain the virtual modifier map (the <emphasis> -vmodmap</emphasis> - array) for a subset of the keys in a keyboard description, use <emphasis> -XkbGetKeyVirtualModMap</emphasis> -: -</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> -XkbGetKeyVirtualModMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first</emphasis> -; /* keycode of first key to fetch */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* # keys for which virtual mod maps are desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description where results will be placed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To obtain the virtual modifier map (the +<structfield>vmodmap</structfield> +array) for a subset of the keys in a keyboard description, use +<function>XkbGetKeyVirtualModMap</function>: + +</para> + +<indexterm significance="preferred" zone="XkbGetKeyVirtualModMap"><primary><function>XkbGetKeyVirtualModMap</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyVirtualModMap"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyVirtualModMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key to fetch + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + # keys for which virtual mod maps are desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description where results will be placed + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyVirutalModmap </emphasis> +<function>XkbGetKeyVirtualModmap</function> sends a request to the server to obtain the virtual modifier mappings for -<emphasis> -num</emphasis> - keys on the keyboard starting with key <emphasis> -first</emphasis> -. It waits for a reply and returns the virtual modifier mappings in the -<emphasis> -server</emphasis> --><emphasis> -vmodmap</emphasis> - array of <emphasis> -xkb</emphasis> -. If successful, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - returns <emphasis> -Success</emphasis> -. The <emphasis> -xkb</emphasis> - parameter must be a pointer to a valid Xkb keyboard description +<parameter>num</parameter> +keys on the keyboard starting with key +<parameter>first</parameter>. +It waits for a reply and returns the virtual modifier mappings in the +<structfield>server</structfield>-><structfield>vmodmap</structfield> +array of +<parameter>xkb</parameter>. +If successful, +<function>XkbGetKeyVirtualModMap</function> +returns +<symbol>Success</symbol>. +The +<parameter>xkb</parameter> +parameter must be a pointer to a valid Xkb keyboard description </para> <para> -If the <emphasis> -server</emphasis> - map in the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - allocates and initializes it before obtaining the virtual modifier mappings. +If the +<structfield>server</structfield> +map in the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeyVirtualModMap</function> +allocates and initializes it before obtaining the virtual modifier mappings. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - returns <emphasis> -BadMatch</emphasis> -. If <emphasis> -num</emphasis> - is less than 1 or greater than <emphasis> -XkbMaxKeyCount</emphasis> -, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - returns <emphasis> -BadValue</emphasis> -. If any allocation errors occur, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +has not been properly initialized, +<function>XkbGetKeyVirtualModMap</function> +returns +<errorname>BadMatch</errorname>. +If +<parameter>num</parameter> +is less than 1 or greater than +<symbol>XkbMaxKeyCount</symbol>, +<function>XkbGetKeyVirtualModMap</function> +returns +<errorname>BadValue</errorname>. +If any allocation errors occur, +<function>XkbGetKeyVirtualModMap</function> +returns +<errorname>BadAlloc</errorname>. </para> </sect2> |