407 lines
11 KiB
XML
407 lines
11 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='Complete_Keyboard_Description'>
|
|
<title>Complete Keyboard Description</title>
|
|
|
|
<para>
|
|
The complete Xkb description for a keyboard device is accessed using a single
|
|
structure containing pointers to major Xkb components. This chapter describes
|
|
this single structure and provides references to other sections of this
|
|
document that discuss the major Xkb components in detail.
|
|
</para>
|
|
|
|
<sect1 id='The_XkbDescRec_Structure'>
|
|
<title>The XkbDescRec Structure</title>
|
|
|
|
<indexterm significance="preferred" zone="The_XkbDescRec_Structure">
|
|
<primary><structname>XkbDescRec</structname></primary></indexterm>
|
|
|
|
<para>
|
|
The complete description of an Xkb keyboard is given by an
|
|
<structname>XkbDescRec</structname>.
|
|
The component structures in the
|
|
<structname>XkbDescRec</structname>
|
|
represent the major Xkb components outlined in <link linkend="figure1.1">Figure 1.1</link>.
|
|
</para>
|
|
|
|
<para><programlisting>
|
|
typedef struct {
|
|
struct _XDisplay * display; /* connection to X server */
|
|
unsigned short flags; /* private to Xkb, do not modify */
|
|
unsigned short device_spec; /* device of interest */
|
|
KeyCode min_key_code; /* minimum keycode for device */
|
|
KeyCode max_key_code; /* maximum keycode for device */
|
|
XkbControlsPtr ctrls; /* controls */
|
|
XkbServerMapPtr server; /* server keymap */
|
|
XkbClientMapPtr map; /* client keymap */
|
|
XkbIndicatorPtr indicators; /* indicator map */
|
|
XkbNamesPtr names; /* names for all components */
|
|
XkbCompatMapPtr compat; /* compatibility map */
|
|
XkbGeometryPtr geom; /* physical geometry of keyboard */
|
|
} <structname>XkbDescRec</structname>, *XkbDescPtr;
|
|
</programlisting></para>
|
|
|
|
<para>
|
|
The
|
|
<parameter>display</parameter>
|
|
field points to an X display structure. The
|
|
<structfield>flags</structfield>
|
|
field is private to the library: modifying
|
|
<structfield>flags</structfield>
|
|
may yield unpredictable results. The
|
|
<parameter>device_spec</parameter>
|
|
field specifies the device identifier of the keyboard input device, or
|
|
<symbol>XkbUseCoreKbd</symbol>,
|
|
which specifies the core keyboard device. The
|
|
<structfield>min_key_code</structfield>
|
|
and
|
|
<structfield>max_key_code</structfield>
|
|
fields specify the least and greatest keycode that can be returned by the
|
|
keyboard.
|
|
</para>
|
|
|
|
|
|
<para>
|
|
The other fields specify structure components of the keyboard description and
|
|
are described in detail in other sections of this document.
|
|
<link linkend="table6.1">Table 6.1</link>
|
|
identifies the subsequent sections of this document that discuss the individual
|
|
components of the
|
|
<structname>XkbDescRec</structname>.
|
|
</para>
|
|
|
|
<table id='table6.1' frame='topbot'>
|
|
<title>XkbDescRec Component References</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>XkbDescRec Field</entry>
|
|
<entry>For more info</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>ctrls</entry>
|
|
<entry><xref linkend="Keyboard_Controls" /></entry>
|
|
</row>
|
|
<row>
|
|
<entry>server</entry>
|
|
<entry><xref linkend="Xkb_Server_Keyboard_Mapping" /></entry>
|
|
</row>
|
|
<row>
|
|
<entry>map</entry>
|
|
<entry><xref linkend="Xkb_Client_Keyboard_Mapping" /></entry>
|
|
</row>
|
|
<row>
|
|
<entry>indicators</entry>
|
|
<entry><xref linkend="Indicators" /></entry>
|
|
</row>
|
|
<row>
|
|
<entry>names</entry>
|
|
<entry><xref linkend="Symbolic_Names" /></entry>
|
|
</row>
|
|
<row>
|
|
<entry>compat</entry>
|
|
<entry><xref linkend="The_Xkb_Compatibility_Map" /></entry>
|
|
</row>
|
|
<row>
|
|
<entry>geom</entry>
|
|
<entry><xref linkend="Keyboard_Geometry" /></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>
|
|
Each structure component has a corresponding mask bit that is used in function
|
|
calls to indicate that the structure should be manipulated in some manner, such
|
|
as allocating it or freeing it. These masks and their relationships to the
|
|
fields in the
|
|
<structname>XkbDescRec</structname>
|
|
are shown in <link linkend="table6.2">Table 6.2</link>.
|
|
</para>
|
|
|
|
<table id='table6.2' frame='topbot'>
|
|
<title>Mask Bits for XkbDescRec</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='1.0*'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Mask Bit</entry>
|
|
<entry>XkbDescRec Field</entry>
|
|
<entry>Value</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><symbol>XkbControlsMask</symbol></entry>
|
|
<entry>ctrls</entry>
|
|
<entry>(1L<<0)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><symbol>XkbServerMapMask</symbol></entry>
|
|
<entry>server</entry>
|
|
<entry>(1L<<1)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XkbIClientMapMask</entry>
|
|
<entry>map</entry>
|
|
<entry>(1L<<2)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><symbol>XkbIndicatorMapMask</symbol></entry>
|
|
<entry>indicators</entry>
|
|
<entry>(1L<<3)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><symbol>XkbNamesMask</symbol></entry>
|
|
<entry>names</entry>
|
|
<entry>(1L<<4)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><symbol>XkbCompatMapMask</symbol></entry>
|
|
<entry>compat</entry>
|
|
<entry>(1L<<5)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><symbol>XkbGeometryMask</symbol></entry>
|
|
<entry>geom</entry>
|
|
<entry>(1L<<6)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><symbol>XkbAllComponentsMask</symbol></entry>
|
|
<entry>All Fields</entry>
|
|
<entry>(0x7f)</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
</sect1>
|
|
<sect1 id='Obtaining_a_Keyboard_Description_from_the_Server'>
|
|
<title>Obtaining a Keyboard Description from the Server</title>
|
|
|
|
<para>
|
|
To retrieve one or more components of a keyboard device description, use
|
|
<function>XkbGetKeyboard</function>
|
|
(see also
|
|
<link linkend="XkbGetKeyboardByName"><function>XkbGetKeyboardByName</function></link>).
|
|
|
|
</para>
|
|
|
|
<indexterm significance="preferred" zone="XkbGetKeyboard"><primary><function>XkbGetKeyboard</function></primary></indexterm>
|
|
<funcsynopsis id="XkbGetKeyboard">
|
|
<funcprototype>
|
|
<funcdef>XkbDescPtr <function>XkbGetKeyboard</function></funcdef>
|
|
<!-- (
|
|
<parameter>display, which, device_spec</parameter>
|
|
) -->
|
|
|
|
<paramdef>Display *<parameter>display</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>which</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>display</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
connection to X server
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>which</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
mask indicating components to return
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>device_spec</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
device for which to fetch description, or
|
|
<symbol>XkbUseCoreKbd</symbol>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
<function>XkbGetKeyboard</function>
|
|
allocates and returns a pointer to a keyboard description. It queries the
|
|
server for those components specified in the
|
|
<parameter>which</parameter>
|
|
parameter for device
|
|
<parameter>device_spec</parameter>
|
|
and copies the results to the
|
|
<structname>XkbDescRec</structname>
|
|
it allocated. The remaining fields in the keyboard description are set to
|
|
<symbol>NULL</symbol>.
|
|
The valid masks for
|
|
<parameter>which</parameter>
|
|
are those listed in <link linkend="table6.2">Table 6.2</link>.
|
|
</para>
|
|
|
|
|
|
<para>
|
|
<function>XkbGetKeyboard</function>
|
|
can generate
|
|
<errorname>BadAlloc</errorname>
|
|
protocol errors.
|
|
</para>
|
|
|
|
|
|
<para>
|
|
To free the returned keyboard description, use
|
|
<function>XkbFreeKeyboard</function>
|
|
(see <link linkend="Allocating_and_Freeing_a_Keyboard_Description">section 6.4</link>).
|
|
</para>
|
|
|
|
|
|
</sect1>
|
|
<sect1 id='Tracking_Changes_to_the_Keyboard_Description_in_the_Server'>
|
|
<title>Tracking Changes to the Keyboard Description in the Server</title>
|
|
|
|
<para>
|
|
The server can generate events whenever its copy of the keyboard description
|
|
for a device changes. Refer to <link linkend="Tracking_Changes_to_Map_Components">section 14.4</link> for detailed information on
|
|
tracking changes to the keyboard description.
|
|
</para>
|
|
|
|
|
|
</sect1>
|
|
<sect1 id='Allocating_and_Freeing_a_Keyboard_Description'>
|
|
<title>Allocating and Freeing a Keyboard Description</title>
|
|
|
|
<para>
|
|
Applications seldom need to directly allocate a keyboard description; calling
|
|
<function>XkbGetKeyboard</function>
|
|
usually suffices. In the event you need to create a keyboard description from
|
|
scratch, however, use
|
|
<function>XkbAllocKeyboard</function>
|
|
rather than directly calling
|
|
<function>malloc</function>
|
|
or
|
|
<function>Xmalloc</function>.
|
|
</para>
|
|
|
|
<indexterm significance="preferred" zone="XkbAllocKeyboard"><primary><function>XkbAllocKeyboard</function></primary></indexterm>
|
|
<funcsynopsis id="XkbAllocKeyboard">
|
|
<funcprototype>
|
|
<funcdef>XkbDescRec *<function>XkbAllocKeyboard</function></funcdef>
|
|
<void />
|
|
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
If
|
|
<function>XkbAllocKeyboard</function>
|
|
fails to allocate the keyboard description, it returns
|
|
<symbol>NULL</symbol>.
|
|
Otherwise, it returns a pointer to an empty keyboard description structure.
|
|
The
|
|
<structfield>device_spec</structfield>
|
|
field will have been initialized to
|
|
<symbol>XkbUseCoreKbd</symbol>.
|
|
You may then either fill in the structure components or use Xkb functions to
|
|
obtain values for the structure components from a keyboard device.
|
|
</para>
|
|
|
|
|
|
<para>
|
|
To destroy either an entire an
|
|
<structname>XkbDescRec</structname>
|
|
or just some of its members, use
|
|
<function>XkbFreeKeyboard</function>.
|
|
</para>
|
|
|
|
|
|
<indexterm significance="preferred" zone="XkbFreeKeyboard"><primary><function>XkbFreeKeyboard</function></primary></indexterm>
|
|
<funcsynopsis id="XkbFreeKeyboard">
|
|
<funcprototype>
|
|
<funcdef>void <function>XkbFreeKeyboard</function></funcdef>
|
|
<!--
|
|
<parameter>(xkb, which, free_all</parameter>
|
|
) -->
|
|
|
|
<paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>which</parameter></paramdef>
|
|
<paramdef>Bool <parameter>free_all</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>xkb</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
keyboard description with components to free
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>which</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
mask selecting components to free
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>free_all</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
<symbol>True</symbol> ⇒ free all components and <parameter>xkb</parameter>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
<function>XkbFreeKeyboard</function>
|
|
frees the components of
|
|
<parameter>xkb</parameter>
|
|
specified by
|
|
<parameter>which</parameter>
|
|
and sets the corresponding values to
|
|
<symbol>NULL</symbol>.
|
|
If
|
|
<parameter>free_all</parameter>
|
|
is
|
|
<symbol>True</symbol>,
|
|
<function>XkbFreeKeyboard</function>
|
|
frees every non-
|
|
<symbol>NULL</symbol>
|
|
component of
|
|
<parameter>xkb</parameter>
|
|
and then frees the
|
|
<parameter>xkb</parameter>
|
|
structure itself.
|
|
</para>
|
|
|
|
</sect1>
|
|
</chapter>
|