1638 lines
45 KiB
XML
1638 lines
45 KiB
XML
|
<chapter id='xkb_keyboard_mapping'>
|
|||
|
<title>Xkb Keyboard Mapping</title>
|
|||
|
|
|||
|
<para>
|
|||
|
The Xkb keyboard mapping contains all the information the server and clients
|
|||
|
need to interpret key events. This chapter provides an overview of the
|
|||
|
terminology used to describe an Xkb keyboard mapping and introduces common
|
|||
|
utilities for manipulating the keyboard mapping.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
The mapping consists of two components, a server map and a client map. The
|
|||
|
<emphasis>
|
|||
|
client</emphasis>
|
|||
|
map is the collection of information a client needs to interpret key events
|
|||
|
from the keyboard. It contains a global list of key types and an array of key
|
|||
|
symbol maps, each of which describes the symbols bound to a key and the rules
|
|||
|
to be used to interpret those symbols. The <emphasis>
|
|||
|
server</emphasis>
|
|||
|
map contains the information the server needs to interpret key events. This
|
|||
|
includes actions and behaviors for each key, explicit components for a key, and
|
|||
|
the virtual modifiers and the per-key virtual modifier mapping.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
For detailed information on particular components of the keyboard map, refer to
|
|||
|
Chapter 15, "Xkb Client Keyboard Mapping" and Chapter 16, "Xkb Server Keyboard
|
|||
|
Mapping."
|
|||
|
</para>
|
|||
|
|
|||
|
<sect1 id='notation_and_terminology'>
|
|||
|
<title>Notation and Terminology</title>
|
|||
|
|
|||
|
<para>
|
|||
|
The graphic characters or control functions that may be accessed by one key are
|
|||
|
logically arranged in groups and levels, where <emphasis>
|
|||
|
group</emphasis>
|
|||
|
and <emphasis>
|
|||
|
level</emphasis>
|
|||
|
are defined as in the ISO9995 standard:
|
|||
|
</para>
|
|||
|
|
|||
|
<variablelist>
|
|||
|
<varlistentry>
|
|||
|
<term>Group:</term>
|
|||
|
<listitem>
|
|||
|
<para>
|
|||
|
A logical state of a keyboard providing access to a collection of
|
|||
|
graphic characters. Usually these graphic characters logically belong together
|
|||
|
and may be arranged on several levels within a group.
|
|||
|
</para>
|
|||
|
</listitem>
|
|||
|
</varlistentry>
|
|||
|
<varlistentry>
|
|||
|
<term>Level:</term>
|
|||
|
<listitem>
|
|||
|
<para>
|
|||
|
One of several states (normally 2 or 3) governing which graphic
|
|||
|
character is produced when a graphic key is actuated. In certain cases the
|
|||
|
level may also affect function keys.
|
|||
|
</para>
|
|||
|
</listitem>
|
|||
|
</varlistentry>
|
|||
|
</variablelist>
|
|||
|
|
|||
|
<para>
|
|||
|
These definitions, taken from the ISO standard, refer to graphic keys and
|
|||
|
characters. In the context of Xkb, Group and Level are not constrained to
|
|||
|
graphic keys and characters; they may be used with any key to access any
|
|||
|
character the key is capable of generating.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
Level is often referred to as "Shift Level". Levels are numbered sequentially
|
|||
|
starting at one.
|
|||
|
</para>
|
|||
|
|
|||
|
<note><para>Shift level is derived from the modifier state, but not necessarily
|
|||
|
in the same way for all keys. For example, the <emphasis>
|
|||
|
Shift</emphasis>
|
|||
|
modifier selects shift level 2 on most keys, but for keypad keys the modifier
|
|||
|
bound to <emphasis>
|
|||
|
Num_Lock</emphasis>
|
|||
|
(that is, the <emphasis>
|
|||
|
NumLock</emphasis>
|
|||
|
virtual modifier) also selects shift level 2.</para></note>
|
|||
|
|
|||
|
<para>
|
|||
|
For example, consider the following key (the gray characters indicate symbols
|
|||
|
that are implied or expected but are not actually engraved on the key):
|
|||
|
</para>
|
|||
|
|
|||
|
<mediaobject>
|
|||
|
<imageobject> <imagedata format="SVG" fileref="XKBlib-14.svg"/>
|
|||
|
</imageobject>
|
|||
|
<caption>Shift Levels and Groups</caption>
|
|||
|
</mediaobject>
|
|||
|
|
|||
|
|
|||
|
<!--
|
|||
|
<H5 CLASS="Figure">
|
|||
|
Shift Levels and Groups</H5>
|
|||
|
-->
|
|||
|
|
|||
|
<para>
|
|||
|
This key has two groups, indicated by the columns, and each group has two shift
|
|||
|
levels. For the first group (Group1), the symbol shift level one is <emphasis>
|
|||
|
a</emphasis>
|
|||
|
, and the symbol for shift level two is <emphasis>
|
|||
|
A</emphasis>
|
|||
|
. For the second group, the symbol for shift level one is <emphasis>
|
|||
|
æ</emphasis>
|
|||
|
, and the symbol for shift level two is <emphasis>
|
|||
|
Æ</emphasis>
|
|||
|
.
|
|||
|
</para>
|
|||
|
|
|||
|
<sect2 id='core_implementation'>
|
|||
|
<title>Core Implementation</title>
|
|||
|
|
|||
|
<para>
|
|||
|
The standard interpretation rules for the core X keymap only allow clients to
|
|||
|
access keys such as the one shown in Figure 14.1. That is, clients using the
|
|||
|
standard interpretation rules can only access one of four keysyms for any given
|
|||
|
<emphasis>
|
|||
|
KeyPress</emphasis>
|
|||
|
event — two different symbols in two different groups.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
In general, the <emphasis>
|
|||
|
Shift</emphasis>
|
|||
|
modifier, the <emphasis>
|
|||
|
Lock</emphasis>
|
|||
|
modifier, and the modifier bound to the <emphasis>
|
|||
|
Num_Lock</emphasis>
|
|||
|
key are used to change between shift level 1 and shift level 2. To switch
|
|||
|
between groups, the core implementation uses the modifier bound to the
|
|||
|
<emphasis>
|
|||
|
Mode_switch</emphasis>
|
|||
|
key. When the <emphasis>
|
|||
|
Mode_switch</emphasis>
|
|||
|
modifier is set, the keyboard is logically in Group 2. When the <emphasis>
|
|||
|
Mode_switch</emphasis>
|
|||
|
modifier is not set, the keyboard is logically in Group 1.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
The core implementation does not clearly specify the behavior of keys. For
|
|||
|
example, the locking behavior of the <emphasis>
|
|||
|
CapsLock</emphasis>
|
|||
|
and <emphasis>
|
|||
|
Num_Lock</emphasis>
|
|||
|
keys depends on the vendor.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
</sect2>
|
|||
|
<sect2 id='xkb_implementation'>
|
|||
|
<title>Xkb Implementation</title>
|
|||
|
|
|||
|
<para>
|
|||
|
Xkb extends the core implementation by providing access to up to four keyboard
|
|||
|
groups with up to 63 shift levels per key
|
|||
|
<footnote><para>
|
|||
|
The core implementation restricts the number of symbols per key to 255.
|
|||
|
With four groups, this allows for up to 63 symbols (or shift levels) per
|
|||
|
group. Most keys will only have a few shift levels.
|
|||
|
</para></footnote>. In
|
|||
|
addition, Xkb provides precise specifications regarding the behavior of keys.
|
|||
|
In Xkb, modifier state and the current group are independent (with the
|
|||
|
exception of compatibility mapping, discussed in Chapter 17).
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
Xkb handles switching between groups via key actions, independent of any
|
|||
|
modifier state information. Key actions are in the server map component and are
|
|||
|
described in detail in section 16.1.4.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
Xkb handles shift levels by associating a key type with each group on each key.
|
|||
|
Each key type defines the shift levels available for the groups on keys of its
|
|||
|
type and specifies the modifier combinations necessary to access each level.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
For example, Xkb allows key types where the <emphasis>
|
|||
|
Control</emphasis>
|
|||
|
modifier can be used to access the shift level two of a key. Key types are in
|
|||
|
the client map component and are described in detail in section 15.2. <!-- xref -->
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
Xkb provides precise specification of the behavior of a key using key
|
|||
|
behaviors. Key behaviors are in the server map component and are described in
|
|||
|
detail in section 16.2. <!-- xref -->
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
</sect2>
|
|||
|
</sect1>
|
|||
|
<sect1 id='getting_map_components_from_the_server'>
|
|||
|
<title>Getting Map Components from the Server</title>
|
|||
|
|
|||
|
<para>
|
|||
|
Xkb provides two functions to obtain the keyboard mapping components from the
|
|||
|
server. The first function, <emphasis>
|
|||
|
XkbGetMap</emphasis>
|
|||
|
, allocates an <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure, retrieves mapping components from the server, and stores them in
|
|||
|
the <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure it just allocated. The second function, <emphasis>
|
|||
|
XkbGetUpdatedMap</emphasis>
|
|||
|
, retrieves mapping components from the server and stores them in an <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure that has previously been allocated.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
To allocate an <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure and populate it with the server’s keyboard client map and server
|
|||
|
map, use <emphasis>
|
|||
|
XkbGetMap. XkbGetMap </emphasis>
|
|||
|
is similar to <emphasis>
|
|||
|
XkbGetKeyboard</emphasis>
|
|||
|
(see section 6.2), but is used only for obtaining the address of an <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure that is populated with keyboard mapping components. It allows finer
|
|||
|
control over which substructures of the keyboard mapping components are to be
|
|||
|
populated. <emphasis>
|
|||
|
XkbGetKeyboard</emphasis>
|
|||
|
always returns fully populated components, while <emphasis>
|
|||
|
XkbGetMap</emphasis>
|
|||
|
can be instructed to return a partially populated component.
|
|||
|
</para>
|
|||
|
|
|||
|
<informaltable frame='none'>
|
|||
|
<tgroup cols='1'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functiondecl'>
|
|||
|
XkbDescPtr <emphasis>
|
|||
|
XkbGetMap</emphasis>
|
|||
|
(<emphasis>
|
|||
|
display, which, device_spec</emphasis>
|
|||
|
)
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
Display * <emphasis>
|
|||
|
display</emphasis>
|
|||
|
; /* connection to X server */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int <emphasis>
|
|||
|
which</emphasis>
|
|||
|
; /* mask selecting subcomponents to populate */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int <emphasis>
|
|||
|
device_spec</emphasis>
|
|||
|
; /* device_id, or <emphasis>
|
|||
|
XkbUseCoreKbd</emphasis>
|
|||
|
*/
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</informaltable>
|
|||
|
|
|||
|
<para>
|
|||
|
The <emphasis>
|
|||
|
which</emphasis>
|
|||
|
mask is a bitwise inclusive OR of the masks defined in Table 14.1. Only those
|
|||
|
portions of the keyboard server map and the keyboard client maps that are
|
|||
|
specified in <emphasis>
|
|||
|
which</emphasis>
|
|||
|
are allocated and populated.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
In addition to allocating and obtaining the server map and the client map,
|
|||
|
<emphasis>
|
|||
|
XkbGetMap</emphasis>
|
|||
|
also sets the <emphasis>
|
|||
|
device_spec</emphasis>
|
|||
|
, the <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
<emphasis>
|
|||
|
, </emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields of the keyboard description.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
<emphasis>
|
|||
|
XkbGetMap</emphasis>
|
|||
|
is synchronous; it queries the server for the desired information, waits for a
|
|||
|
reply, and then returns. If successful<emphasis>
|
|||
|
, XkbGetMap</emphasis>
|
|||
|
returns a pointer to the <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure it allocated. If unsuccessful, <emphasis>
|
|||
|
XkbGetMap</emphasis>
|
|||
|
returns <emphasis>
|
|||
|
NULL</emphasis>
|
|||
|
. When unsuccessful, one of the following protocol errors is also generated:
|
|||
|
<emphasis>
|
|||
|
BadAlloc</emphasis>
|
|||
|
(unable to allocate the <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure), <emphasis>
|
|||
|
BadValue</emphasis>
|
|||
|
(some mask bits in <emphasis>
|
|||
|
which</emphasis>
|
|||
|
are undefined)<emphasis>
|
|||
|
,</emphasis>
|
|||
|
or <emphasis>
|
|||
|
BadImplementation</emphasis>
|
|||
|
(a compatible version of the Xkb extension is not available in the server). To
|
|||
|
free the returned data, use <emphasis>
|
|||
|
XkbFreeClientMap</emphasis>
|
|||
|
.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
Xkb also provides convenience functions to get partial component definitions
|
|||
|
from the server. These functions are specified in the "convenience functions"
|
|||
|
column in Table 14.1. Refer to the sections listed in the table for more
|
|||
|
information on these functions.
|
|||
|
</para>
|
|||
|
|
|||
|
<table frame='none'>
|
|||
|
<title>Xkb Mapping Component Masks and Convenience Functions</title>
|
|||
|
<tgroup cols='6'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<thead>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>Mask</entry>
|
|||
|
<entry>Value</entry>
|
|||
|
<entry>Map</entry>
|
|||
|
<entry>Fields</entry>
|
|||
|
<entry>Convenience Functions</entry>
|
|||
|
<entry>Section</entry>
|
|||
|
</row>
|
|||
|
</thead>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbKeyTypesMask</emphasis></entry>
|
|||
|
<entry>(1<<0)</entry>
|
|||
|
<entry>client</entry>
|
|||
|
<entry>
|
|||
|
<para><emphasis>types</emphasis></para>
|
|||
|
<para><emphasis>size_types</emphasis></para>
|
|||
|
<para><emphasis>num_types</emphasis></para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para><emphasis>XkbGetKeyTypes</emphasis></para>
|
|||
|
<para><emphasis>XkbResizeKeyType</emphasis></para>
|
|||
|
<para><emphasis>XkbCopyKeyType</emphasis></para>
|
|||
|
<para><emphasis>XkbCopyKeyTypes</emphasis></para>
|
|||
|
</entry>
|
|||
|
<entry>15.2</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbKeySymsMask</emphasis></entry>
|
|||
|
<entry>(1<<1)</entry>
|
|||
|
<entry>client</entry>
|
|||
|
<entry>
|
|||
|
<para><emphasis>syms</emphasis></para>
|
|||
|
<para><emphasis>size_syms</emphasis></para>
|
|||
|
<para><emphasis>num_syms</emphasis></para>
|
|||
|
<para><emphasis>key_sym_map</emphasis></para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para><emphasis>XkbGetKeySyms</emphasis></para>
|
|||
|
<para><emphasis>XkbResizeKeySyms</emphasis></para>
|
|||
|
<para><emphasis>XkbChangeTypesOfKey</emphasis></para>
|
|||
|
</entry>
|
|||
|
<entry>15.3</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbModifierMapMask</emphasis></entry>
|
|||
|
<entry>(1<<2)</entry>
|
|||
|
<entry>client</entry>
|
|||
|
<entry><emphasis>modmap</emphasis></entry>
|
|||
|
<entry><emphasis>XkbGetKeyModifierMap</emphasis></entry>
|
|||
|
<entry>15.4</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbExplicitComponentsMask</emphasis></entry>
|
|||
|
<entry>(1<<3)</entry>
|
|||
|
<entry>server</entry>
|
|||
|
<entry><emphasis>explicit</emphasis></entry>
|
|||
|
<entry><emphasis>XkbGetKeyExplicitComponents</emphasis></entry>
|
|||
|
<entry>16.3</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbKeyActionsMask</emphasis></entry>
|
|||
|
<entry>(1<<4)</entry>
|
|||
|
<entry>server</entry>
|
|||
|
<entry>
|
|||
|
<para><emphasis>key_acts</emphasis></para>
|
|||
|
<para><emphasis>acts</emphasis></para>
|
|||
|
<para><emphasis>num_acts</emphasis></para>
|
|||
|
<para><emphasis>size_acts</emphasis></para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para><emphasis>XkbGetKeyActions</emphasis></para>
|
|||
|
<para><emphasis>XkbResizeKeyActions</emphasis></para>
|
|||
|
</entry>
|
|||
|
<entry>16.1</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry>
|
|||
|
<entry>(1<<5)</entry>
|
|||
|
<entry>server</entry>
|
|||
|
<entry><emphasis>behaviors</emphasis></entry>
|
|||
|
<entry><emphasis>XkbGetKeyBehaviors</emphasis></entry>
|
|||
|
<entry>16.2</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbVirtualModsMask</emphasis></entry>
|
|||
|
<entry>(1<<6)</entry>
|
|||
|
<entry>server</entry>
|
|||
|
<entry><emphasis>vmods</emphasis></entry>
|
|||
|
<entry><emphasis>XkbGetVirtualMods</emphasis></entry>
|
|||
|
<entry>16.4</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbVirtualModMapMask</emphasis></entry>
|
|||
|
<entry>(1<<7)</entry>
|
|||
|
<entry>server</entry>
|
|||
|
<entry><emphasis>vmodmap</emphasis></entry>
|
|||
|
<entry><emphasis>XkbGetVirtualModMap</emphasis></entry>
|
|||
|
<entry>16.4</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</table>
|
|||
|
|
|||
|
<para>
|
|||
|
Xkb defines combinations of these masks for convenience:
|
|||
|
</para>
|
|||
|
|
|||
|
<para><programlisting>
|
|||
|
#define XkbResizableInfoMask (XkbKeyTypesMask)
|
|||
|
#define XkbAllClientInfoMask (XkbKeyTypesMask | XkbKeySymsMask |
|
|||
|
XkbModifierMapMask)
|
|||
|
#define XkbAllServerInfoMask (XkbExplicitComponentsMask |
|
|||
|
XkbKeyActionsMask| XkbKeyBehaviorsMask |
|
|||
|
XkbVirtualModsMask | XkbVirtualModMapMask)
|
|||
|
#define XkbAllMapComponentsMask (XkbAllClientInfoMask|XkbAllServerInfoMask)
|
|||
|
</programlisting></para>
|
|||
|
|
|||
|
<para>
|
|||
|
Key types, symbol maps, and actions are all interrelated: changes in one
|
|||
|
require changes in the others. The convenience functions make it easier to edit
|
|||
|
these components and handle the interdependencies.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
To update the client or server map information in an existing keyboard
|
|||
|
description, use <emphasis>XkbGetUpdatedMap</emphasis>.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<informaltable frame='none'>
|
|||
|
<tgroup cols='1'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functiondecl'>
|
|||
|
Status <emphasis>
|
|||
|
XkbGetUpdatedMap</emphasis>
|
|||
|
(<emphasis>
|
|||
|
display, which, xkb</emphasis>
|
|||
|
)
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
Display * <emphasis>
|
|||
|
display</emphasis>
|
|||
|
; /* connection to X server */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int<emphasis>
|
|||
|
which</emphasis>
|
|||
|
; /* mask selecting subcomponents to populate */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
XkbDescPtr <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
; /* keyboard description to be updated */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</informaltable>
|
|||
|
|
|||
|
<para>
|
|||
|
The <emphasis>
|
|||
|
which</emphasis>
|
|||
|
parameter is a bitwise inclusive OR of the masks in Table 14.1. If the needed
|
|||
|
components of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
structure are not already allocated, <emphasis>
|
|||
|
XkbGetUpdatedMap</emphasis>
|
|||
|
allocates them. <emphasis>
|
|||
|
XkbGetUpdatedMap</emphasis>
|
|||
|
fetches the requested information for the device specified in the <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
passed in the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
<emphasis>
|
|||
|
XkbGetUpdatedMap</emphasis>
|
|||
|
is synchronous; it queries the server for the desired information, waits for a
|
|||
|
reply, and then returns. If successful<emphasis>
|
|||
|
, XkbGetUpdatedMap</emphasis>
|
|||
|
returns <emphasis>
|
|||
|
Success</emphasis>
|
|||
|
. If unsuccessful, <emphasis>
|
|||
|
XkbGetUpdatedMap</emphasis>
|
|||
|
returns one of the following: <emphasis>
|
|||
|
BadAlloc</emphasis>
|
|||
|
(unable to allocate a component in the <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure), <emphasis>
|
|||
|
BadValue</emphasis>
|
|||
|
(some mask bits in <emphasis>
|
|||
|
which</emphasis>
|
|||
|
are undefined), <emphasis>
|
|||
|
BadImplementation</emphasis>
|
|||
|
(a compatible version of the Xkb extension is not available in the server or
|
|||
|
the reply from the server was invalid).
|
|||
|
</para>
|
|||
|
|
|||
|
</sect1>
|
|||
|
<sect1 id='changing_map_components_in_the_server'>
|
|||
|
<title>Changing Map Components in the Server</title>
|
|||
|
|
|||
|
<para>
|
|||
|
There are two ways to make changes to map components: either change a local
|
|||
|
copy of the keyboard map and call <emphasis>
|
|||
|
XkbSetMap</emphasis>
|
|||
|
to send the modified map to the server, or, to reduce network traffic, use
|
|||
|
an<emphasis>
|
|||
|
XkbMapChangesRec</emphasis>
|
|||
|
structure and call <emphasis>XkbChangeMap</emphasis>.
|
|||
|
</para>
|
|||
|
|
|||
|
<informaltable frame='none'>
|
|||
|
<tgroup cols='1'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functiondecl'>
|
|||
|
Bool <emphasis>
|
|||
|
XkbSetMap</emphasis>
|
|||
|
(<emphasis>
|
|||
|
dpy</emphasis>
|
|||
|
,<emphasis>
|
|||
|
which</emphasis>
|
|||
|
,<emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
)
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
Display *<emphasis>
|
|||
|
dpy</emphasis>
|
|||
|
; /* connection to X server */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int<emphasis>
|
|||
|
which</emphasis>
|
|||
|
; /* mask selecting subcomponents to update */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
XkbDescPtr <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
; /* description from which new values are taken */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</informaltable>
|
|||
|
|
|||
|
<para>
|
|||
|
Use <emphasis>
|
|||
|
XkbSetMap</emphasis>
|
|||
|
to send a complete new set of values for entire components (for example, all
|
|||
|
symbols, all actions, and so on) to the server. The <emphasis>
|
|||
|
which</emphasis>
|
|||
|
parameter specifies the components to be sent to the server, and is a bitwise
|
|||
|
inclusive OR of the masks listed in Table 14.1. The <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter is a pointer to an <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure and contains the information to be copied to the server. For each
|
|||
|
bit set in the <emphasis>
|
|||
|
which</emphasis>
|
|||
|
parameter, <emphasis>
|
|||
|
XkbSetMap</emphasis>
|
|||
|
takes the corresponding structure values from the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter and sends it to the server specified by <emphasis>
|
|||
|
dpy</emphasis>.
|
|||
|
</para>
|
|||
|
|
|||
|
<para>
|
|||
|
If any components specified by <emphasis>
|
|||
|
which</emphasis>
|
|||
|
are not present in the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter, <emphasis>
|
|||
|
XkbSetMap</emphasis>
|
|||
|
returns <emphasis>
|
|||
|
False</emphasis>
|
|||
|
. Otherwise, it sends the update request to the server and returns <emphasis>
|
|||
|
True</emphasis>
|
|||
|
. <emphasis>
|
|||
|
XkbSetMap</emphasis>
|
|||
|
can generate <emphasis>
|
|||
|
BadAlloc</emphasis>
|
|||
|
, <emphasis>
|
|||
|
BadLength</emphasis>
|
|||
|
, and <emphasis>
|
|||
|
BadValue</emphasis>
|
|||
|
protocol errors.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
Key types, symbol maps, and actions are all interrelated; changes in one
|
|||
|
require changes in the others. Xkb provides functions to make it easier to edit
|
|||
|
these components and handle the interdependencies. Table 14.1 lists these
|
|||
|
helper functions and provides a pointer to where they are defined.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<sect2 id='the_xkbmapchangesrec_structure'>
|
|||
|
<title>The XkbMapChangesRec Structure</title>
|
|||
|
|
|||
|
<para>
|
|||
|
Use the <emphasis>
|
|||
|
XkbMapChangesRec</emphasis>
|
|||
|
structure to identify and track partial modifications to the mapping
|
|||
|
components and to reduce the amount of traffic between the server and clients.
|
|||
|
</para>
|
|||
|
|
|||
|
<para><programlisting>
|
|||
|
typedef struct _XkbMapChanges {
|
|||
|
unsigned short changed; /* identifies valid components
|
|||
|
in structure */
|
|||
|
KeyCode min_key_code; /* lowest numbered keycode for
|
|||
|
device */
|
|||
|
KeyCode max_key_code; /* highest numbered keycode for
|
|||
|
device */
|
|||
|
unsigned char first_type; /* index of first key <emphasis>type</emphasis>
|
|||
|
modified */
|
|||
|
unsigned char num_types; /* # types modified */
|
|||
|
KeyCode first_key_sym; /* first key whose <emphasis>key_sym_map</emphasis>
|
|||
|
changed */
|
|||
|
unsigned char num_key_syms; /* # <emphasis>key_sym_map</emphasis>
|
|||
|
entries changed */
|
|||
|
KeyCode first_key_act; /* first key whose <emphasis>key_acts</emphasis>
|
|||
|
entry changed */
|
|||
|
unsigned char num_key_acts; /* # <emphasis>key_acts</emphasis>
|
|||
|
entries changed */
|
|||
|
KeyCode first_key_behavior; /* first key whose <emphasis>behaviors</emphasis>
|
|||
|
changed */
|
|||
|
unsigned char num_key_behaviors; /* # <emphasis>behaviors</emphasis>
|
|||
|
entries changed */
|
|||
|
KeyCode first_key_explicit; /* first key whose <emphasis>explicit</emphasis>
|
|||
|
entry changed */
|
|||
|
unsigned char num_key_explicit; /* # <emphasis> explicit</emphasis>
|
|||
|
entries changed */
|
|||
|
KeyCode first_modmap_key; /* first key whose <emphasis>modmap</emphasis>
|
|||
|
entry changed */
|
|||
|
unsigned char num_modmap_keys; /* # <emphasis>modmap</emphasis>
|
|||
|
entries changed */
|
|||
|
KeyCode first_vmodmap_key; /* first key whose <emphasis>vmodmap</emphasis>
|
|||
|
changed */
|
|||
|
unsigned char num_vmodmap_keys; /* # <emphasis> vmodmap</emphasis>
|
|||
|
entries changed */
|
|||
|
unsigned char pad1; /* reserved */
|
|||
|
unsigned short vmods; /* mask indicating which <emphasis>vmods</emphasis>
|
|||
|
changed */
|
|||
|
} <emphasis>XkbMapChangesRec</emphasis>,*XkbMapChangesPtr;
|
|||
|
</programlisting></para>
|
|||
|
|
|||
|
<para>
|
|||
|
The <emphasis>
|
|||
|
changed</emphasis>
|
|||
|
field identifies the map components that have changed in an <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure and may contain any of the bits in Table 14.1, which are also shown
|
|||
|
in Table 14.2. Every 1 bit in <emphasis>
|
|||
|
changed</emphasis>
|
|||
|
also identifies which other fields in the <emphasis>
|
|||
|
XkbMapChangesRec</emphasis>
|
|||
|
structure contain valid values, as indicated in Table 14.2. The <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields are for reference only; they are ignored on any requests sent to the
|
|||
|
server and are always updated by the server whenever it returns the data for an
|
|||
|
<emphasis>
|
|||
|
XkbMapChangesRec</emphasis>
|
|||
|
.
|
|||
|
</para>
|
|||
|
|
|||
|
<table frame='none'>
|
|||
|
<title>XkbMapChangesRec Masks</title>
|
|||
|
<tgroup cols='3'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<thead>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>Mask</entry>
|
|||
|
<entry>Valid XkbMapChangesRec Fields</entry>
|
|||
|
<entry>XkbDescRec Field Containing Changed Data</entry>
|
|||
|
</row>
|
|||
|
</thead>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbKeyTypesMask</emphasis></entry>
|
|||
|
<entry>
|
|||
|
<para>first_type</para>,
|
|||
|
<para>num_types</para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para>map->type[first_type] ..</para>
|
|||
|
<para>map->type[first_type + num_types - 1]</para>
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbKeySymsMask</emphasis></entry>
|
|||
|
<entry>
|
|||
|
<para>first_key_sym</para>,
|
|||
|
<para>num_key_syms</para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para>map->key_sym_map[first_key_sym] ..</para>
|
|||
|
<para>map->key_sym_map[first_key_sym + num_key_syms - 1]</para>
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbModifierMapMask</emphasis></entry>
|
|||
|
<entry>
|
|||
|
<para>first_modmap_key</para>,
|
|||
|
<para>num_modmap_keys</para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para>map->modmap[first_modmap_key] ..</para>
|
|||
|
<para>map->modmap[first_modmap_key + num_modmap_keys-1]</para>
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbExplicitComponentsMask</emphasis></entry>
|
|||
|
<entry>
|
|||
|
<para>first_key_explicit</para>,
|
|||
|
<para>num_key_explicit</para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para>server->explicit[first_key_explicit] ..</para>
|
|||
|
<para>server->explicit[first_key_explicit + num_key_explicit - 1]</para>
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbKeyActionsMask</emphasis></entry>
|
|||
|
<entry>
|
|||
|
<para>first_key_act,</para>
|
|||
|
<para>num_key_acts</para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para>server->key_acts[first_key_act] ..</para>
|
|||
|
<para>server->key_acts[first_key_act + num_key_acts - 1]</para>
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry>
|
|||
|
<entry>
|
|||
|
<para>first_key_behavior,</para>
|
|||
|
<para>num_key_behaviors</para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para>server->behaviors[first_key_behavior] ..</para>
|
|||
|
<para>server->behaviors[first_key_behavior + num_key_behaviors - 1]</para>
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbVirtuawModsMask</emphasis></entry>
|
|||
|
<entry>vmods</entry>
|
|||
|
<entry>server->vmods[*]</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry><emphasis>XkbVirtualModMapMask</emphasis></entry>
|
|||
|
<entry>
|
|||
|
<para>first_vmodmap_key,</para>
|
|||
|
<para>num_vmodmap_keys</para>
|
|||
|
</entry>
|
|||
|
<entry>
|
|||
|
<para>server->vmodmap[first_vmodmap_key] ..</para>
|
|||
|
<para>server->vmodmap[first_vmodmap_key + num_vmodmap_keys - 1]</para>
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</table>
|
|||
|
|
|||
|
<para>
|
|||
|
To update only partial components of a keyboard description, modify the
|
|||
|
appropriate fields in the server and map components of a local copy of the
|
|||
|
keyboard description, then call <emphasis>
|
|||
|
XkbChangeMap</emphasis>
|
|||
|
with an <emphasis>
|
|||
|
XkbMapChangesRec</emphasis>
|
|||
|
structure indicating which components have changed.
|
|||
|
</para>
|
|||
|
|
|||
|
<informaltable frame='none'>
|
|||
|
<tgroup cols='1'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functiondecl'>
|
|||
|
Bool <emphasis>
|
|||
|
XkbChangeMap</emphasis>
|
|||
|
(<emphasis>
|
|||
|
dpy</emphasis>
|
|||
|
,<emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
,<emphasis>
|
|||
|
changes</emphasis>
|
|||
|
)
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
Display *<emphasis>
|
|||
|
dpy</emphasis>
|
|||
|
; /* connection to X server */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
XkbDescPtr <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
; /* description from which new values are taken */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
XkbMapChangesPtr <emphasis>
|
|||
|
changes</emphasis>
|
|||
|
; /*identifies component parts to update */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</informaltable>
|
|||
|
|
|||
|
<para>
|
|||
|
<emphasis>
|
|||
|
XkbChangeMap</emphasis>
|
|||
|
copies any components specified by the <emphasis>
|
|||
|
changes</emphasis>
|
|||
|
structure from the keyboard description, <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
, to the X server specified by <emphasis>
|
|||
|
dpy</emphasis>
|
|||
|
.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
If any components specified by <emphasis>
|
|||
|
changes</emphasis>
|
|||
|
are not present in the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter, <emphasis>
|
|||
|
XkbChangeMap</emphasis>
|
|||
|
returns <emphasis>
|
|||
|
False</emphasis>
|
|||
|
. Otherwise, it sends a request to the server and returns <emphasis>
|
|||
|
True</emphasis>
|
|||
|
.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
<emphasis>
|
|||
|
XkbChangeMap</emphasis>
|
|||
|
can generate <emphasis>
|
|||
|
BadAlloc</emphasis>
|
|||
|
, <emphasis>
|
|||
|
BadLength</emphasis>
|
|||
|
, and <emphasis>
|
|||
|
BadValue</emphasis>
|
|||
|
protocol errors.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
</sect2>
|
|||
|
</sect1>
|
|||
|
<sect1 id='tracking_changes_to_map_components'>
|
|||
|
<title>Tracking Changes to Map Components</title>
|
|||
|
|
|||
|
<para>
|
|||
|
The Xkb extension reports <emphasis>
|
|||
|
XkbMapNotify</emphasis>
|
|||
|
events to clients wanting notification whenever a map component of the Xkb
|
|||
|
description for a device changes. There are many different types of Xkb
|
|||
|
keyboard map changes. Xkb uses an event detail mask to identify each type of
|
|||
|
change. The event detail masks are identical to the masks listed in Table 14.1.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
To receive <emphasis>
|
|||
|
XkbMapNotify</emphasis>
|
|||
|
events under all possible conditions, use <emphasis>
|
|||
|
XkbSelectEvents</emphasis>
|
|||
|
(see section 4.3) and pass <emphasis>
|
|||
|
XkbMapNotifyMask</emphasis>
|
|||
|
in both <emphasis>
|
|||
|
bits_to_change</emphasis>
|
|||
|
and <emphasis>
|
|||
|
values_for_bits</emphasis>
|
|||
|
.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
To receive <emphasis>
|
|||
|
XkbMapNotify</emphasis>
|
|||
|
events only under certain conditions, use <emphasis>
|
|||
|
XkbSelectEventDetails</emphasis>
|
|||
|
using <emphasis>
|
|||
|
XkbMapNotify</emphasis>
|
|||
|
as the <emphasis>
|
|||
|
event_type</emphasis>
|
|||
|
and specifying the desired map changes in <emphasis>
|
|||
|
bits_to_change</emphasis>
|
|||
|
and <emphasis>
|
|||
|
values_for_bits</emphasis>
|
|||
|
using mask bits from Table 14.1.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
The structure for <emphasis>
|
|||
|
XkbMapNotify</emphasis>
|
|||
|
events is:
|
|||
|
</para>
|
|||
|
|
|||
|
<para><programlisting>
|
|||
|
typedef struct {
|
|||
|
int type; /* Xkb extension base event code */
|
|||
|
unsigned long serial; /* X server serial number for event */
|
|||
|
Bool send_event; /* <emphasis>True</emphasis> => synthetically generated */
|
|||
|
Display * display; /* server connection where event generated */
|
|||
|
Time time; /* server time when event generated */
|
|||
|
int xkb_type; /* <emphasis> XkbMapNotify</emphasis> */
|
|||
|
int device; /* Xkb device ID, will not be <emphasis>XkbUseCoreKbd</emphasis> */
|
|||
|
unsigned int changed; /* identifies valid fields in rest of event */
|
|||
|
unsigned int resized; /* reserved */
|
|||
|
int first_type; /* index of first key <emphasis> type</emphasis> modified */
|
|||
|
int num_types /* # types modified */
|
|||
|
KeyCode min_key_code; /* minimum keycode for device */
|
|||
|
KeyCode max_key_code; /* maximum keycode for device */
|
|||
|
KeyCode first_key_sym; /* first key whose <emphasis>key_sym_map</emphasis> changed */
|
|||
|
KeyCode first_key_act; /* first key whose <emphasis> key_acts</emphasis> entry changed */
|
|||
|
KeyCode first_key_behavior; /* first key whose <emphasis> behaviors</emphasis> changed */
|
|||
|
KeyCode first_key_explicit; /* first key whose <emphasis> explicit </emphasis> entry changed */
|
|||
|
KeyCode first_modmap_key; /* first key whose <emphasis> modmap</emphasis> entry changed */
|
|||
|
KeyCode first_vmodmap_key; /* # <emphasis> modmap</emphasis> entries changed */
|
|||
|
int num_key_syms; /* # <emphasis>key_sym_map</emphasis> entries changed */
|
|||
|
int num_key_acts; /* # <emphasis> key_acts</emphasis> entries changed */
|
|||
|
int num_key_behaviors; /* # <emphasis> behaviors</emphasis> entries changed */
|
|||
|
int num_key_explicit; /* # <emphasis> explicit</emphasis> entries changed */
|
|||
|
int num_modmap_keys; /* # <emphasis> modmap</emphasis> entries changed */
|
|||
|
int num_vmodmap_keys; /* # <emphasis> vmodmap</emphasis> entries changed */
|
|||
|
unsigned in t vmods; /* mask indicating which <emphasis> vmods</emphasis> changed */
|
|||
|
} <emphasis>XkbMapNotifyEvent</emphasis>;
|
|||
|
</programlisting></para>
|
|||
|
|
|||
|
<para>
|
|||
|
The <emphasis>
|
|||
|
changed</emphasis>
|
|||
|
field specifies the map components that have changed and is the bitwise
|
|||
|
inclusive OR of the mask bits defined in Table 14.1. The other fields in this
|
|||
|
event are interpreted as the like-named fields in an <emphasis>
|
|||
|
XkbMapChangesRec</emphasis>
|
|||
|
(see section 14.3.1). The <emphasis>
|
|||
|
XkbMapNotifyEvent</emphasis>
|
|||
|
structure also has an additional <emphasis>
|
|||
|
resized</emphasis>
|
|||
|
field that is reserved for future use.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
</sect1>
|
|||
|
<sect1 id='allocating_and_freeing_client_and_server_maps'>
|
|||
|
<title>Allocating and Freeing Client and Server Maps</title>
|
|||
|
|
|||
|
<para>
|
|||
|
Calling <emphasis>
|
|||
|
XkbGetMap</emphasis>
|
|||
|
(see section 14.2) should be sufficient for most applications to get client
|
|||
|
and server maps. As a result, most applications do not need to directly
|
|||
|
allocate client and server maps.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
If you change the number of key types or construct map components without
|
|||
|
loading the necessary components from the X server, do not allocate any map
|
|||
|
components directly using <emphasis>
|
|||
|
malloc</emphasis>
|
|||
|
or <emphasis>
|
|||
|
Xmalloc</emphasis>
|
|||
|
. Instead, use the Xkb allocators, <emphasis>
|
|||
|
XkbAllocClientMap,</emphasis>
|
|||
|
and <emphasis>
|
|||
|
XkbAllocServerMap</emphasis>
|
|||
|
.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
Similarly, use the Xkb destructors, <emphasis>
|
|||
|
XkbFreeClientMap,</emphasis>
|
|||
|
and <emphasis>
|
|||
|
XkbFreeServerMap</emphasis>
|
|||
|
instead of <emphasis>
|
|||
|
free</emphasis>
|
|||
|
or <emphasis>
|
|||
|
Xfree</emphasis>
|
|||
|
.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<sect2 id='allocating_an_empty_client_map'>
|
|||
|
<title>Allocating an Empty Client Map</title>
|
|||
|
|
|||
|
<para>
|
|||
|
To allocate and initialize an empty client map description record, use
|
|||
|
<emphasis>
|
|||
|
XkbAllocClientMap.</emphasis>
|
|||
|
</para>
|
|||
|
|
|||
|
<informaltable frame='none'>
|
|||
|
<tgroup cols='1'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functiondecl'>
|
|||
|
Status <emphasis>
|
|||
|
XkbAllocClientMap</emphasis>
|
|||
|
(<emphasis>
|
|||
|
xkb, which, type_count</emphasis>
|
|||
|
)
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
XkbDescPtr <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
; /* keyboard description in which to allocate client map */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int<emphasis>
|
|||
|
which</emphasis>
|
|||
|
; /* mask selecting map components to allocate */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int<emphasis>
|
|||
|
type_count</emphasis>
|
|||
|
; /* value of <emphasis>
|
|||
|
num_types</emphasis>
|
|||
|
field in map to be allocated */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</informaltable>
|
|||
|
|
|||
|
<para>
|
|||
|
<emphasis>
|
|||
|
XkbAllocClientMap</emphasis>
|
|||
|
allocates and initializes an empty client map in the <emphasis>
|
|||
|
map</emphasis>
|
|||
|
field of the keyboard description specified by <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
. The <emphasis>
|
|||
|
which</emphasis>
|
|||
|
parameter specifies the particular components of the client map structure to
|
|||
|
allocate and is a mask composed by a bitwise inclusive OR of one or more of the
|
|||
|
masks shown in Table 14.3.
|
|||
|
</para>
|
|||
|
|
|||
|
<table frame='none'>
|
|||
|
<title>XkbAllocClientMap Masks</title>
|
|||
|
<tgroup cols='2'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<thead>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>Mask</entry>
|
|||
|
<entry>Effect</entry>
|
|||
|
</row>
|
|||
|
</thead>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>XkbKeyTypesMask</entry>
|
|||
|
<entry>
|
|||
|
The <emphasis>
|
|||
|
type_count </emphasis>
|
|||
|
field specifies the number of entries to preallocate for the <emphasis>
|
|||
|
types</emphasis>
|
|||
|
field of the client map. If the <emphasis>
|
|||
|
type_count </emphasis>
|
|||
|
field is less than <emphasis>
|
|||
|
XkbNumRequiredTypes</emphasis>
|
|||
|
(see section 15.2.1), returns <emphasis>
|
|||
|
BadValue</emphasis>.
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>XkbKeySymsMask</entry>
|
|||
|
<entry>
|
|||
|
The <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter are used to allocate the <emphasis>
|
|||
|
syms</emphasis>
|
|||
|
and <emphasis>
|
|||
|
key_sym_map</emphasis>
|
|||
|
fields of the client map. The fields are allocated to contain the maximum
|
|||
|
number of entries necessary for <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
- <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
+ 1 keys.
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>XkbModifierMapMask</entry>
|
|||
|
<entry>
|
|||
|
The <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter are used to allocate the <emphasis>
|
|||
|
modmap</emphasis>
|
|||
|
field of the client map. The field is allocated to contain the maximum number
|
|||
|
of entries necessary for <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
- <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
+ 1 keys.
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</table>
|
|||
|
|
|||
|
<note><para>The <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter must be legal values if the <emphasis>
|
|||
|
XkbKeySymsMask</emphasis>
|
|||
|
or <emphasis>
|
|||
|
XkbModifierMapMask</emphasis>
|
|||
|
masks are set in the <emphasis>
|
|||
|
which</emphasis>
|
|||
|
parameter. If they are not valid, <emphasis>
|
|||
|
XkbAllocClientMap</emphasis>
|
|||
|
returns <emphasis>
|
|||
|
BadValue</emphasis>
|
|||
|
. </para></note>
|
|||
|
|
|||
|
<para>
|
|||
|
If the client map of the keyboard description is not <emphasis>
|
|||
|
NULL</emphasis>
|
|||
|
, and any fields are already allocated in the client map, <emphasis>
|
|||
|
XkbAllocClientMap</emphasis>
|
|||
|
does not overwrite the existing values; it simply ignores that part of the
|
|||
|
request. The only exception is the <emphasis>
|
|||
|
types</emphasis>
|
|||
|
array. If <emphasis>
|
|||
|
type_count</emphasis>
|
|||
|
is greater than the current <emphasis>
|
|||
|
num_types</emphasis>
|
|||
|
field of the client map, <emphasis>
|
|||
|
XkbAllocClientMap</emphasis>
|
|||
|
resizes the <emphasis>
|
|||
|
types</emphasis>
|
|||
|
array and resets the <emphasis>
|
|||
|
num_types</emphasis>
|
|||
|
field accordingly.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
If <emphasis>
|
|||
|
XkbAllocClientMap</emphasis>
|
|||
|
is successful, it returns <emphasis>
|
|||
|
Success</emphasis>
|
|||
|
. Otherwise, it can return either <emphasis>
|
|||
|
BadMatch</emphasis>
|
|||
|
, <emphasis>
|
|||
|
BadAlloc</emphasis>
|
|||
|
, or <emphasis>
|
|||
|
BadValue</emphasis>
|
|||
|
errors.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
</sect2>
|
|||
|
<sect2 id='freeing_a_client_map'>
|
|||
|
<title>Freeing a Client Map</title>
|
|||
|
|
|||
|
<para>
|
|||
|
To free memory used by the client map member of an <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure, use <emphasis>
|
|||
|
XkbFreeClientMap.</emphasis>
|
|||
|
</para>
|
|||
|
|
|||
|
<informaltable frame='none'>
|
|||
|
<tgroup cols='1'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functiondecl'>
|
|||
|
void <emphasis>
|
|||
|
XkbFreeClientMap</emphasis>
|
|||
|
(<emphasis>
|
|||
|
xkb, which, free_all</emphasis>
|
|||
|
)
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
XkbDescPtr <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
; /* keyboard description containing client map to free */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int<emphasis>
|
|||
|
which</emphasis>
|
|||
|
; /* mask identifying components of map to free */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
Bool <emphasis>
|
|||
|
free_all</emphasis>
|
|||
|
; /* <emphasis>
|
|||
|
True</emphasis>
|
|||
|
=> free all client components and map itself */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</informaltable>
|
|||
|
|
|||
|
<para>
|
|||
|
<emphasis>
|
|||
|
XkbFreeClientMap</emphasis>
|
|||
|
frees the components of client map specified by <emphasis>
|
|||
|
which</emphasis>
|
|||
|
in the <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure specified by the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter and sets the corresponding structure component values to <emphasis>
|
|||
|
NULL</emphasis>
|
|||
|
. The <emphasis>
|
|||
|
which</emphasis>
|
|||
|
parameter specifies a combination of the client map masks shown in Table 14.3.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
If <emphasis>
|
|||
|
free_all</emphasis>
|
|||
|
is <emphasis>
|
|||
|
True</emphasis>
|
|||
|
, <emphasis>
|
|||
|
which</emphasis>
|
|||
|
is ignored; <emphasis>
|
|||
|
XkbFreeClientMap</emphasis>
|
|||
|
frees every non-<emphasis>
|
|||
|
NULL</emphasis>
|
|||
|
structure component in the client map, frees the <emphasis>
|
|||
|
XkbClientMapRec</emphasis>
|
|||
|
structure referenced by the <emphasis>
|
|||
|
map</emphasis>
|
|||
|
member of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter, and sets the <emphasis>
|
|||
|
map</emphasis>
|
|||
|
member to <emphasis>
|
|||
|
NULL.</emphasis>
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
</sect2>
|
|||
|
<sect2 id='allocating_an_empty_server_map'>
|
|||
|
<title>Allocating an Empty Server Map</title>
|
|||
|
|
|||
|
<para>
|
|||
|
To allocate and initialize an empty server map description record, use
|
|||
|
<emphasis>
|
|||
|
XkbAllocServerMap.</emphasis>
|
|||
|
</para>
|
|||
|
|
|||
|
<informaltable frame='none'>
|
|||
|
<tgroup cols='1'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functiondecl'>
|
|||
|
Status <emphasis>
|
|||
|
XkbAllocServerMap</emphasis>
|
|||
|
(<emphasis>
|
|||
|
xkb, which, count_acts</emphasis>
|
|||
|
)
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
XkbDescPtr <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
; /* keyboard description in which to allocate server map */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int<emphasis>
|
|||
|
which</emphasis>
|
|||
|
; /* mask selecting map components to allocate */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int<emphasis>
|
|||
|
count_acts</emphasis>
|
|||
|
; /* value of <emphasis>
|
|||
|
num_acts</emphasis>
|
|||
|
field in map to be allocated */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</informaltable>
|
|||
|
|
|||
|
<para>
|
|||
|
<emphasis>
|
|||
|
XkbAllocServerMap</emphasis>
|
|||
|
allocates and initializes an empty server map in the <emphasis>
|
|||
|
server</emphasis>
|
|||
|
field of the keyboard description specified by <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
. The <emphasis>
|
|||
|
which</emphasis>
|
|||
|
parameter specifies the particular components of the server map structure to
|
|||
|
allocate, as specified in Table 14.4.
|
|||
|
</para>
|
|||
|
|
|||
|
<table frame='none'>
|
|||
|
<title>XkbAllocServerMap Masks</title>
|
|||
|
<tgroup cols='2'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<thead>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>Mask</entry>
|
|||
|
<entry>Effect</entry>
|
|||
|
</row>
|
|||
|
</thead>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>XkbExplicitComponentsMask</entry>
|
|||
|
<entry>
|
|||
|
The <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter are used to allocate the <emphasis>
|
|||
|
explicit </emphasis>
|
|||
|
field of the server map.
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>XkbKeyActionsMask</entry>
|
|||
|
<entry>
|
|||
|
The <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter are used to allocate the <emphasis>
|
|||
|
key_acts </emphasis>
|
|||
|
field of the server map. The <emphasis>
|
|||
|
count_acts</emphasis>
|
|||
|
parameter is used to allocate the <emphasis>
|
|||
|
acts</emphasis>
|
|||
|
field of the server map.
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>XkbKeyBehaviorsMask</entry>
|
|||
|
<entry>
|
|||
|
The <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter are used to allocate the <emphasis>
|
|||
|
behaviors </emphasis>
|
|||
|
field of the server map.
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry>XkbVirtualModMapMask</entry>
|
|||
|
<entry>
|
|||
|
The <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields of the <emphasis>
|
|||
|
xkb </emphasis>
|
|||
|
parameter are used to allocate the <emphasis>
|
|||
|
vmodmap </emphasis>
|
|||
|
field of the server map.
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</table>
|
|||
|
|
|||
|
<note><para>The <emphasis>
|
|||
|
min_key_code</emphasis>
|
|||
|
and <emphasis>
|
|||
|
max_key_code</emphasis>
|
|||
|
fields of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter must be legal values. If they are not valid, <emphasis>
|
|||
|
XkbAllocServerMap</emphasis>
|
|||
|
returns <emphasis>
|
|||
|
BadValue</emphasis>
|
|||
|
. </para></note>
|
|||
|
|
|||
|
<para>
|
|||
|
If the server map of the keyboard description is not <emphasis>
|
|||
|
NULL</emphasis>
|
|||
|
and any fields are already allocated in the server map, <emphasis>
|
|||
|
XkbAllocServerMap</emphasis>
|
|||
|
does not overwrite the existing values. The only exception is with the
|
|||
|
<emphasis>
|
|||
|
acts </emphasis>
|
|||
|
array. If the <emphasis>
|
|||
|
count_acts </emphasis>
|
|||
|
parameter is greater than the current <emphasis>
|
|||
|
num_acts </emphasis>
|
|||
|
field of the server map, <emphasis>
|
|||
|
XkbAllocServerMap</emphasis>
|
|||
|
resizes the <emphasis>
|
|||
|
acts </emphasis>
|
|||
|
array and resets the <emphasis>
|
|||
|
num_acts </emphasis>
|
|||
|
field accordingly.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
<para>
|
|||
|
If <emphasis>
|
|||
|
XkbAllocServerMap</emphasis>
|
|||
|
is successful, it returns <emphasis>
|
|||
|
Success</emphasis>
|
|||
|
. Otherwise, it can return either <emphasis>
|
|||
|
BadMatch</emphasis>
|
|||
|
or <emphasis>
|
|||
|
BadAlloc</emphasis>
|
|||
|
errors.
|
|||
|
</para>
|
|||
|
|
|||
|
|
|||
|
</sect2>
|
|||
|
<sect2 id='freeing_a_server_map'>
|
|||
|
<title>Freeing a Server Map</title>
|
|||
|
|
|||
|
<para>
|
|||
|
To free memory used by the server member of an <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure, use <emphasis>
|
|||
|
XkbFreeServerMap.</emphasis>
|
|||
|
</para>
|
|||
|
|
|||
|
<informaltable frame='none'>
|
|||
|
<tgroup cols='1'>
|
|||
|
<colspec colsep='0'/>
|
|||
|
<tbody>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functiondecl'>
|
|||
|
void <emphasis>
|
|||
|
XkbFreeServerMap</emphasis>
|
|||
|
(<emphasis>
|
|||
|
xkb, which, free_all</emphasis>
|
|||
|
)
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
XkbDescPtr <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
; /* keyboard description containing server map to free */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
unsigned int<emphasis>
|
|||
|
which</emphasis>
|
|||
|
; /* mask identifying components of map to free */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
<row rowsep='0'>
|
|||
|
<entry role='functionargdecl'>
|
|||
|
Bool <emphasis>
|
|||
|
free_all</emphasis>
|
|||
|
; /* <emphasis>
|
|||
|
True</emphasis>
|
|||
|
=> free all server map components and server itself */
|
|||
|
</entry>
|
|||
|
</row>
|
|||
|
</tbody>
|
|||
|
</tgroup>
|
|||
|
</informaltable>
|
|||
|
|
|||
|
<para>
|
|||
|
The <emphasis>
|
|||
|
XkbFreeServerMap</emphasis>
|
|||
|
function frees the specified components of server map in the <emphasis>
|
|||
|
XkbDescRec</emphasis>
|
|||
|
structure specified by the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter and sets the corresponding structure component values to <emphasis>
|
|||
|
NULL</emphasis>
|
|||
|
. The <emphasis>
|
|||
|
which</emphasis>
|
|||
|
parameter specifies a combination of the server map masks and is a bitwise
|
|||
|
inclusive OR of the masks listed in Table 14.4. If <emphasis>
|
|||
|
free_all</emphasis>
|
|||
|
is <emphasis>
|
|||
|
True</emphasis>
|
|||
|
, <emphasis>
|
|||
|
which</emphasis>
|
|||
|
is ignored and <emphasis>
|
|||
|
XkbFreeServerMap</emphasis>
|
|||
|
frees every non-<emphasis>
|
|||
|
NULL</emphasis>
|
|||
|
structure component in the server map, frees the <emphasis>
|
|||
|
XkbServerMapRec</emphasis>
|
|||
|
structure referenced by the <emphasis>
|
|||
|
server</emphasis>
|
|||
|
member of the <emphasis>
|
|||
|
xkb</emphasis>
|
|||
|
parameter, and sets the <emphasis>
|
|||
|
server</emphasis>
|
|||
|
member to <emphasis>
|
|||
|
NULL.</emphasis>
|
|||
|
</para>
|
|||
|
|
|||
|
</sect2>
|
|||
|
</sect1>
|
|||
|
</chapter>
|