4873 lines
136 KiB
XML
4873 lines
136 KiB
XML
<?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
|
||
<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>
|
||
<link linkend="figure16.1">Figure 16.1</link> shows the relationships between elements in the server map:
|
||
</para>
|
||
|
||
<figure id='figure16.1'>
|
||
<title>Server Map Relationships</title>
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-16.svg"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
|
||
<!--
|
||
<H5 CLASS="Figure">
|
||
Server Map Relationships</H5>
|
||
-->
|
||
|
||
<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
|
||
<structname>XkbServerMapRec</structname>:
|
||
|
||
<programlisting>
|
||
#define XkbNumVirtualMods 16
|
||
|
||
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
|
||
<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'>
|
||
<title>Key Actions</title>
|
||
|
||
<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
|
||
<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
|
||
<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
|
||
<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>
|
||
|
||
|
||
<para>
|
||
The key action structures consist only of fields of type char or unsigned char.
|
||
This is done to optimize data transfer when the server sends bytes over the
|
||
wire. If the fields are anything but bytes, the server has to sift through all
|
||
of the actions and swap any nonbyte fields. Because they consist of nothing but
|
||
bytes, it can just copy them out.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Xkb provides the following macros, to simplify accessing information pertaining
|
||
to key actions:
|
||
</para>
|
||
|
||
<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>
|
||
|
||
|
||
<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>
|
||
<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>
|
||
|
||
<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>
|
||
<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
|
||
<structname>XkbAction</structname>
|
||
structure, which is a union of all possible Xkb action types:
|
||
|
||
<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;
|
||
} <structname>XkbAction</structname>;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
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>
|
||
|
||
|
||
</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
|
||
<structname>XkbAnyAction</structname>
|
||
structure is a convenience structure that refers to any of the actions:
|
||
|
||
<programlisting>
|
||
#define XkbAnyActionDataSize 7
|
||
|
||
typedef struct _XkbAnyAction {
|
||
unsigned char type; /* type of action; determines interpretation for data */
|
||
unsigned char data[XkbAnyActionDataSize];
|
||
} <structname>XkbAnyAction</structname>;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
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 id='table16.1' frame='topbot'>
|
||
<title>Action Types</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='4' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.8*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<colspec colname='c3' colwidth='1.5*'/>
|
||
<colspec colname='c4' colwidth='1.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Type</entry>
|
||
<entry>Structure for Data</entry>
|
||
<entry>XkbAction Union Member</entry>
|
||
<entry>Section</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_NoAction</symbol></entry>
|
||
<entry>
|
||
<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>
|
||
<entry></entry>
|
||
</row>
|
||
<row>
|
||
<entry>
|
||
<para><symbol>XkbSA_SetMods</symbol></para>
|
||
<para><symbol>XkbSA_LatchMods</symbol></para>
|
||
<para><symbol>XkbSA_LockMods</symbol></para>
|
||
</entry>
|
||
<entry><para><structname>XkbModAction</structname></para></entry>
|
||
<entry>mods</entry>
|
||
<entry><link linkend="Actions_for_Changing_Modifiers_State">16.1.3</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry>
|
||
<para><symbol>XkbSA_SetGroup</symbol></para>
|
||
<para><symbol>XkbSA_LatchGroup</symbol></para>
|
||
<para><symbol>XkbSA_LockGroup</symbol></para>
|
||
</entry>
|
||
<entry><structname>XkbGroupAction</structname></entry>
|
||
<entry>group</entry>
|
||
<entry><link linkend="Actions_for_Changing_Group_State">16.1.4</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_MovePtr</symbol></entry>
|
||
<entry><structname>XkbPtrAction</structname></entry>
|
||
<entry>ptr</entry>
|
||
<entry><link linkend="Actions_for_Moving_the_Pointer">16.1.5</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry>
|
||
<para><symbol>XkbSA_PtrBtn</symbol></para>
|
||
<para><symbol>XkbSA_LockPtrBtn</symbol></para>
|
||
</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><symbol>XkbSA_SetPtrDflt</symbol></entry>
|
||
<entry><structname>XkbPtrDfltAction</structname></entry>
|
||
<entry>dflt</entry>
|
||
<entry><link linkend="Actions_for_Changing_the_Pointer_Button_Simulated">16.1.7</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_ISOLock</symbol></entry>
|
||
<entry><structname>XkbISOAction</structname></entry>
|
||
<entry>iso</entry>
|
||
<entry><link linkend="Actions_for_Locking_Modifiers_and_Group">16.1.8</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_SwitchScreen</symbol></entry>
|
||
<entry><structname>XkbSwitchScreenAction</structname></entry>
|
||
<entry>screen</entry>
|
||
<entry><link linkend="Actions_for_Changing_the_Active_Screen">16.1.9</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry>
|
||
<para><symbol>XkbSA_SetControls</symbol></para>
|
||
<para><symbol>XkbSA_LockControls</symbol></para>
|
||
</entry>
|
||
<entry><structname>XkbCtrlsAction</structname></entry>
|
||
<entry>ctrls</entry>
|
||
<entry><link linkend="Actions_for_Changing_Boolean_Controls_State">16.1.10</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_ActionMessage</symbol></entry>
|
||
<entry><structname>XkbMessageAction</structname></entry>
|
||
<entry>msg</entry>
|
||
<entry><link linkend="Actions_for_Generating_Messages">16.1.11</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_RedirectKey</symbol></entry>
|
||
<entry><structname>XkbRedirectKeyAction</structname></entry>
|
||
<entry>redirect</entry>
|
||
<entry><link linkend="Actions_for_Generating_a_Different_Keycode">16.1.12</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry>
|
||
<para><symbol>XkbSA_DeviceBtn</symbol></para>
|
||
<para><symbol>XkbSA_LockDeviceBtn</symbol></para>
|
||
</entry>
|
||
<entry><structname>XkbDeviceBtnAction</structname></entry>
|
||
<entry>devbtn</entry>
|
||
<entry><link linkend="Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease">16.1.13</link></entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_DeviceValuator</symbol></entry>
|
||
<entry><structname>XkbDeviceValuatorAction</structname></entry>
|
||
<entry>devval</entry>
|
||
<entry><link linkend="Actions_for_Simulating_Events_from_Device_Valuators">16.1.14</link></entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
</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
|
||
<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):
|
||
|
||
<programlisting>
|
||
typedef struct _XkbModAction {
|
||
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
|
||
<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
|
||
<structfield>type</structfield>
|
||
field can have any of the values shown in
|
||
<link linkend="table16.2">Table 16.2</link>.
|
||
</para>
|
||
|
||
<table id='table16.2' frame='topbot'>
|
||
<title>Modifier Action Types</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Type</entry>
|
||
<entry>Effect</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_SetMods</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
A key press adds any action modifiers to the keyboard’s base modifiers.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A key release clears any action modifiers in the keyboard’s base modifiers,
|
||
provided no other key affecting the same modifiers is logically down.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If no other keys are physically depressed when this key is released, and
|
||
<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><symbol>XkbSA_LatchMods</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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
|
||
<symbol>XkbSA_ClearLocks</symbol>
|
||
have no further effect.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
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
|
||
<symbol>XkbSA_ClearLocks</symbol>
|
||
and
|
||
<symbol>XkbSA_LatchToLock</symbol>
|
||
flags.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockMods</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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
|
||
<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>
|
||
</itemizedlist>
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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 id='table16.3' frame='topbot'>
|
||
<title>Modifier Action Flags</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<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
|
||
<structfield>mask</structfield>,
|
||
<structfield>real_mods</structfield>,
|
||
<structfield>vmods1</structfield>,
|
||
and
|
||
<structfield>vmods2</structfield>
|
||
fields.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<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><symbol>XkbSA_LatchToLock</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_LockNoLock</symbol></entry>
|
||
<entry>
|
||
If set, and the action type is
|
||
<symbol>XkbSA_LockMods</symbol>,
|
||
the server only unlocks the action modifiers.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockNoUnlock</symbol></entry>
|
||
<entry>
|
||
If set, and the action is
|
||
<symbol>XkbSA_LockMods</symbol>,
|
||
the server only locks the action modifiers.
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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
|
||
<structfield>map</structfield>-><structfield>modmap</structfield>
|
||
[
|
||
<parameter>keycode</parameter>
|
||
]) are used instead.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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>
|
||
|
||
<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>
|
||
<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
|
||
<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
|
||
<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):
|
||
|
||
<programlisting>
|
||
typedef struct _XkbGroupAction {
|
||
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
|
||
<structfield>type</structfield>
|
||
field can have any of the following values:
|
||
</para>
|
||
|
||
<table id='table16.4' frame='topbot'>
|
||
<title>Group Action Types</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Type</entry>
|
||
<entry>Effect</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_SetGroup</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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
|
||
<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
|
||
<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
|
||
<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>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LatchGroup</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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
|
||
<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
|
||
<structfield>groups_wrap</structfield>
|
||
field of the controls structure.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Otherwise, the key press adds the key press delta to the latched keyboard group.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockGroup</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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
|
||
<structfield>groups_wrap</structfield>
|
||
field of the controls structure.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A key release has no effect.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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 id='table16.5' frame='topbot'>
|
||
<title>Group Action Flags</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<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.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LatchToLock</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_GroupAbsolute</symbol></entry>
|
||
<entry>
|
||
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>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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>
|
||
|
||
<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>
|
||
<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
|
||
<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
|
||
<structname>XkbPtrAction</structname>
|
||
structure move the pointer when keys are pressed and released:
|
||
|
||
<programlisting>
|
||
typedef struct _XkbPtrAction {
|
||
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 <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
|
||
<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
|
||
<structfield>type</structfield>
|
||
field of the
|
||
<structname>XkbPtrAction</structname>
|
||
structure is always
|
||
<symbol>XkbSA_MovePtr</symbol>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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 id='table16.6' frame='topbot'>
|
||
<title>Pointer Action Types</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Action Type</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_NoAcceleration</symbol></entry>
|
||
<entry>
|
||
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><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><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
|
||
to the current pointer Y coordinate to determine the new pointer Y coordinate.
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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>
|
||
<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
|
||
<structname>XkbPtrBtnAction</structname>
|
||
structure simulate the press and release of pointer buttons when keys are
|
||
pressed and released:
|
||
|
||
<programlisting>
|
||
typedef struct _XkbPtrBtnAction {
|
||
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 <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
|
||
<structfield>type</structfield>
|
||
field can have any one of the values shown in
|
||
<link linkend="table16.7">Table 16.7</link>.
|
||
</para>
|
||
|
||
<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'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Type</entry>
|
||
<entry>Effect</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_PtrBtn</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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>
|
||
<para>
|
||
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
|
||
<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
|
||
<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><symbol>XkbSA_LockPtrBtn</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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
|
||
<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>
|
||
</itemizedlist>
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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 id='table16.8' frame='topbot'>
|
||
<title>Pointer Button Action Flags</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_UseDfltButton</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_LockNoLock</symbol></entry>
|
||
<entry>
|
||
If set, and the action type is
|
||
<symbol>XkbSA_LockPtrBtn</symbol>,
|
||
the server only unlocks the pointer button.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockNoUnlock</symbol></entry>
|
||
<entry>
|
||
If set, and the action type is
|
||
<symbol>XkbSA_LockPtrBtn</symbol>,
|
||
the server only locks the pointer button.
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
</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
|
||
<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>):
|
||
|
||
<programlisting>
|
||
typedef struct _XkbPtrDfltAction {
|
||
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,
|
||
<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
|
||
<structfield>type</structfield>
|
||
field of the
|
||
<structname>XkbPtrDfltAction</structname>
|
||
structure should always be
|
||
<symbol>XkbSA_SetPtrDflt</symbol>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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 id='table16.9' frame='topbot'>
|
||
<title>Pointer Default Flags</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_DfltBtnAbsolute</symbol></entry>
|
||
<entry>
|
||
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>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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
|
||
<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>
|
||
<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
|
||
<structname>XkbISOAction</structname>
|
||
structure lock modifiers and the group according to the ISO9995 specification.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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:
|
||
|
||
<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
|
||
<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; /* <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
|
||
<structfield>type</structfield>
|
||
field of the
|
||
<structname>XkbISOAction</structname>
|
||
structure should always be
|
||
<symbol>XkbSA_ISOLock</symbol>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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
|
||
<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 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'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<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
|
||
<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><symbol>XkbSA_GroupAbsolute</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectMods</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectGroup</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectPtr</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectCtrls</symbol></entry>
|
||
<entry>
|
||
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>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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 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'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_ISODfltIsGroup</symbol> </entry>
|
||
<entry>
|
||
<para>
|
||
If not set, action is used to change the base modifier state. Must not be set
|
||
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
|
||
<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><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
|
||
<structfield>mask</structfield>,
|
||
<structfield>real_mods</structfield>,
|
||
<structfield>vmods1</structfield>,
|
||
and
|
||
<structfield>vmods2</structfield>
|
||
fields.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockNoLock</symbol></entry>
|
||
<entry>If set, the server only unlocks the action modifiers.</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockNoUnlock</symbol></entry>
|
||
<entry>If set, the server only locks the action modifiers. </entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_ISONoAffectMods</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectGroup</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectPtr</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectCtrls</symbol></entry>
|
||
<entry>
|
||
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>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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
|
||
<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
|
||
<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 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'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Affect</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_ISONoAffectMods</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectGroup</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectPtr</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_ISONoAffectCtrls</symbol></entry>
|
||
<entry>
|
||
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>
|
||
</tgroup>
|
||
</table>
|
||
|
||
</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
|
||
<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
|
||
<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; /* <symbol>XkbSA_SwitchScreen</symbol> */
|
||
unsigned char flags; /* controls screen switching */
|
||
char screenXXX; /* screen number or delta */
|
||
} <structname>XkbSwitchScreenAction</structname>;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
The
|
||
<structfield>type</structfield>
|
||
field of the
|
||
<structname>XkbSwitchScreenAction</structname>
|
||
structure should always be
|
||
<symbol>XkbSA_SwitchScreen</symbol>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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 id='table16.13' frame='topbot'>
|
||
<title>Switch Screen Action Flags</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_SwitchAbsolute</symbol></entry>
|
||
<entry>
|
||
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><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
|
||
shares the same physical display.
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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>
|
||
<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
|
||
<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>):
|
||
|
||
<programlisting>
|
||
typedef struct _XkbCtrlsAction {
|
||
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
|
||
<structfield>type</structfield>
|
||
field can have any one of the values shown in
|
||
<link linkend="table16.14">Table 16.14</link>.
|
||
</para>
|
||
|
||
<table id='table16.14' frame='topbot'>
|
||
<title>Controls Action Types</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Type</entry>
|
||
<entry>Effect</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_SetControls</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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>
|
||
<para>
|
||
A key release disables any controls enabled by the key press.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
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><symbol>XkbSA_LockControls</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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
|
||
<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
|
||
<symbol>XkbControlsNotify</symbol>
|
||
events (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>).
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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 id='table16.15' frame='topbot'>
|
||
<title>Control Action Flags</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockNoLock</symbol></entry>
|
||
<entry>
|
||
If set, and the action type is
|
||
<symbol>XkbSA_LockControls</symbol>,
|
||
the server only disables controls.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockNoUnlock</symbol></entry>
|
||
<entry>
|
||
If set, and the action type is
|
||
<symbol>XkbSA_LockControls</symbol>,
|
||
the server only enables controls.
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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
|
||
<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>
|
||
|
||
<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>
|
||
<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
|
||
<structname>XkbMessageAction</structname>
|
||
structure generate
|
||
<symbol>XkbActionMessage</symbol>
|
||
events:
|
||
|
||
<programlisting>
|
||
#define XkbActionMessageLength 6
|
||
|
||
typedef struct _XkbMessageAction {
|
||
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
|
||
<structfield>type</structfield>
|
||
field of the
|
||
<structname>XkbMessageAction</structname>
|
||
structure should always be
|
||
<symbol>XkbSA_ActionMessage</symbol>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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 id='table16.16' frame='topbot'>
|
||
<title>Message Action Flags</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_MessageOnPress</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_MessageOnRelease</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbSA_MessageGenKeyEvent</symbol></entry>
|
||
<entry>
|
||
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>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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
|
||
<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
|
||
<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
|
||
<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
|
||
<symbol>XkbActionMessage</symbol>
|
||
event is defined as follows:
|
||
|
||
<programlisting>
|
||
typedef struct _XkbActionMessage {
|
||
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
|
||
<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
|
||
<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>
|
||
|
||
|
||
</sect3>
|
||
</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
|
||
<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:
|
||
|
||
<programlisting>
|
||
typedef struct _XkbRedirectKeyAction {
|
||
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
|
||
<structfield>type</structfield>
|
||
field for the
|
||
<structname>XkbRedirectKeyAction</structname>
|
||
structure should always be
|
||
<symbol>XkbSA_RedirectKey</symbol>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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
|
||
<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
|
||
<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
|
||
<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
|
||
<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.)
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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>
|
||
|
||
<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>
|
||
<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
|
||
<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>
|
||
|
||
|
||
<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>
|
||
|
||
<para>
|
||
<function>XkbSARedirectVModsMask</function> returns the <structfield>vmods0</structfield>
|
||
and <structfield>vmods1</structfield> fields of <parameter>act</parameter>
|
||
converted to an unsigned int.
|
||
</para>
|
||
|
||
<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>
|
||
<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; /* <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
|
||
<structfield>type</structfield>
|
||
field can have any one of the values shown in
|
||
<link linkend="table16.17">Table 16.17</link>.
|
||
</para>
|
||
|
||
<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'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Type</entry>
|
||
<entry>Effect</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<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
|
||
<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
|
||
<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
|
||
<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><symbol>XkbSA_LockDeviceBtn</symbol></entry>
|
||
<entry>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
If the device or button specified by this action are illegal, this action
|
||
behaves like <symbol>XkbSA_NoAction</symbol>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
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
|
||
<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>
|
||
</itemizedlist>
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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 id='table16.18' frame='topbot'>
|
||
<title>Device Button Action Flags</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Flag</entry>
|
||
<entry>Meaning</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockNoLock</symbol></entry>
|
||
<entry>
|
||
If set, and the action type is
|
||
<symbol>XkbSA_LockDeviceBtn</symbol>,
|
||
the server only unlocks the button.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_LockNoUnlock</symbol></entry>
|
||
<entry>
|
||
If set, and the action type is
|
||
<symbol>XkbSA_LockDeviceBtn</symbol>,
|
||
the server only locks the button.
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
</sect2>
|
||
<sect2 id='Actions_for_Simulating_Events_from_Device_Valuators'>
|
||
<title>Actions for Simulating Events from Device Valuators</title>
|
||
<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; /* <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
|
||
<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'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Value of high bits</entry>
|
||
<entry>Effect</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbSA_IgnoreVal</symbol></entry>
|
||
<entry>No action</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_SetValMin</symbol></entry>
|
||
<entry>
|
||
<structfield>v<n>_value</structfield> is set to its minimum legal value.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_SetValCenter</symbol></entry>
|
||
<entry>
|
||
<structfield>v<n>_value</structfield>is centered (to (max-min)/2).
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_SetValMax</symbol></entry>
|
||
<entry>
|
||
<structfield>v<n>_value</structfield> is set to its maximum legal value.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_SetValRelative</symbol></entry>
|
||
<entry>
|
||
<structfield>v<n>_value</structfield> * (2
|
||
<structfield>val<n>Scale</structfield>) is added to
|
||
<structfield>v<n>_value</structfield>.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbSA_SetValAbsolute</symbol></entry>
|
||
<entry>
|
||
<structfield>v<n>_value</structfield>
|
||
is set to (2 <structfield>val<n>Scale</structfield>).
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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 <link linkend="table16.17">Table 16.17</link>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The following two masks are provided as a convenience to select either portion
|
||
of
|
||
<structfield>v1_what</structfield>
|
||
or
|
||
<structfield>v2_what</structfield>:
|
||
|
||
<programlisting>
|
||
#define XkbSA_ValOpMask (0x70)
|
||
#define XkbSA_ValScaleMask (0x07)
|
||
</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
<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>
|
||
|
||
|
||
</sect2>
|
||
<sect2 id='Obtaining_Key_Actions_for_Keys_from_the_Server'>
|
||
<title>Obtaining Key Actions for Keys from the Server</title>
|
||
|
||
<para>
|
||
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>
|
||
<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
|
||
<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,
|
||
<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>
|
||
|
||
|
||
</sect2>
|
||
<sect2 id='Changing_the_Number_of_Actions_Bound_to_a_Key'>
|
||
<title>Changing the Number of Actions Bound to a Key</title>
|
||
|
||
<para>
|
||
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
|
||
<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
|
||
<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
|
||
<function>XkbChangeTypesOfKey</function>
|
||
updates these.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
If any allocation errors occur while resizing the number of actions bound to
|
||
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
|
||
<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>
|
||
|
||
|
||
</sect2>
|
||
</sect1>
|
||
<sect1 id='Key_Behavior'>
|
||
<title>Key Behavior</title>
|
||
|
||
<para>
|
||
Key behavior refers to the demeanor of a key. For example, the expected
|
||
behavior of the
|
||
<keycap>CapsLock</keycap>
|
||
key is that it logically locks when pressed, and then logically unlocks when
|
||
pressed again.
|
||
</para>
|
||
|
||
|
||
<sect2 id='Radio_Groups_2'>
|
||
<title>Radio Groups</title>
|
||
|
||
<para>
|
||
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
|
||
<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
|
||
<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
|
||
<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:
|
||
|
||
<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
|
||
<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:
|
||
|
||
<programlisting>
|
||
typedef struct _XkbBehavior {
|
||
unsigned char type; /* behavior type + optional
|
||
<symbol>XkbKB_Permanent</symbol> bit */
|
||
unsigned char data;
|
||
} <structname>XkbBehavior</structname>;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
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 id='table16.20' frame='topbot'>
|
||
<title>Key Behaviors</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Type</entry>
|
||
<entry>Effect</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbKB_Default</symbol></entry>
|
||
<entry>
|
||
Press and release events are processed normally. The
|
||
<structfield>data</structfield>
|
||
field is unused.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<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
|
||
<structfield>data</structfield>
|
||
field is unused.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<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
|
||
<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
|
||
<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>
|
||
All other key release events are ignored.
|
||
</para>
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbKB_Overlay1</symbol></entry>
|
||
<entry>
|
||
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><symbol>XkbKB_Overlay2</symbol></entry>
|
||
<entry>
|
||
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>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
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
|
||
<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>
|
||
|
||
|
||
</sect2>
|
||
<sect2 id='Obtaining_Key_Behaviors_for_Keys_from_the_Server'>
|
||
<title>Obtaining Key Behaviors for Keys from the Server</title>
|
||
|
||
<para>
|
||
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>
|
||
<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
|
||
<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,
|
||
<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>
|
||
|
||
|
||
</sect2>
|
||
</sect1>
|
||
<sect1 id='Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server'>
|
||
<title>Explicit Components—Avoiding Automatic Remapping by the Server</title>
|
||
|
||
<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 <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>
|
||
|
||
|
||
<para>
|
||
This automatic remapping might replace definitions explicitly requested by an
|
||
application, so the Xkb keyboard description defines an explicit components
|
||
mask for each key. Any aspects of the automatic remapping listed in the
|
||
explicit components mask for a key are not changed by the automatic keyboard
|
||
mapping.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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
|
||
<link linkend="table16.21">Table 16.21</link>.
|
||
</para>
|
||
|
||
<table id='table16.21' frame='topbot'>
|
||
<title>Explicit Component Masks</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='1.0*'/>
|
||
<colspec colname='c3' colwidth='2.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Bit in Explicit Mask</entry>
|
||
<entry>Value</entry>
|
||
<entry>Protects Against</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><emphasis>ExplicitKeyType1</emphasis></entry>
|
||
<entry>(1<<0)</entry>
|
||
<entry>
|
||
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>.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><emphasis>ExplicitKeyType3</emphasis></entry>
|
||
<entry>(1<<2)</entry>
|
||
<entry>
|
||
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>.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><emphasis>ExplicitInterpret</emphasis></entry>
|
||
<entry>(1<<4)</entry>
|
||
<entry>
|
||
Application of any of the fields of a symbol interpretation to the
|
||
key in question.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><emphasis>ExplicitAutoRepeat</emphasis></entry>
|
||
<entry>(1<<5)</entry>
|
||
<entry>Automatic determination of auto-repeat status for the key, as
|
||
specified in a symbol interpretation.</entry>
|
||
</row>
|
||
<row>
|
||
<entry><emphasis>ExplicitBehavior</emphasis></entry>
|
||
<entry>(1<<6)</entry>
|
||
<entry>
|
||
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>
|
||
<entry><emphasis>ExplicitVModMap</emphasis></entry>
|
||
<entry>(1<<7)</entry>
|
||
<entry>
|
||
Automatic determination of the virtual modifier map for the key
|
||
based on the actions assigned to the key and the symbol interpretations that
|
||
match the key.
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<sect2 id='Obtaining_Explicit_Components_for_Keys_from_the_Server'>
|
||
<title>Obtaining Explicit Components for Keys from the Server</title>
|
||
|
||
<para>
|
||
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>
|
||
<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
|
||
<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,
|
||
<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>
|
||
|
||
|
||
</sect2>
|
||
</sect1>
|
||
<sect1 id='Virtual_Modifier_Mapping'>
|
||
<title>Virtual Modifier Mapping</title>
|
||
|
||
<para>
|
||
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
|
||
<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
|
||
<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
|
||
<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>
|
||
|
||
|
||
<para>
|
||
The overall relationship of fields dealing with virtual modifiers in an Xkb
|
||
keyboard description are shown in <link linkend="figure16.2">Figure 16.2</link>.
|
||
</para>
|
||
|
||
<figure id='figure16.2'>
|
||
<title>Virtual Modifier Relationships</title>
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-17.svg"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
|
||
|
||
<!--
|
||
<H5 CLASS="Figure">
|
||
Virtual Modifier Relationships</H5>
|
||
-->
|
||
|
||
<sect2 id='Obtaining_Virtual_Modifier_Bindings_from_the_Server'>
|
||
<title>Obtaining Virtual Modifier Bindings from the Server</title>
|
||
|
||
<para>
|
||
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>
|
||
<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
|
||
<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,
|
||
<function>XkbGetVirtualMods</function>
|
||
returns
|
||
<errorname>BadMatch</errorname>.
|
||
Any errors in allocation cause
|
||
<function>XkbGetVirtualMods</function>
|
||
to return
|
||
<errorname>BadAlloc</errorname>.
|
||
</para>
|
||
|
||
|
||
</sect2>
|
||
<sect2 id='Obtaining_Per_Key_Virtual_Modifier_Mappings_from_the_Server'>
|
||
<title>Obtaining Per-Key Virtual Modifier Mappings from the Server</title>
|
||
|
||
<para>
|
||
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>
|
||
<function>XkbGetKeyVirtualModmap</function>
|
||
sends a request to the server to obtain the virtual modifier mappings for
|
||
<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
|
||
<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,
|
||
<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>
|
||
</sect1>
|
||
</chapter>
|