1169 lines
36 KiB
XML
1169 lines
36 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='Server_Database_of_Keyboard_Components'>
|
||
<title>Server Database of Keyboard Components</title>
|
||
|
||
<para>
|
||
The X server maintains a database of keyboard components, identified by
|
||
component type. The database contains all the information necessary to build a
|
||
complete keyboard description for a particular device, as well as to assemble
|
||
partial descriptions. <link linkend="table20.1">Table 20.1</link>
|
||
identifies the component types and the type of information they contain.
|
||
</para>
|
||
|
||
<table id='table20.1' frame='topbot'>
|
||
<title>Server Database Keyboard Components</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.5*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Component Type</entry>
|
||
<entry>Component Primary Contents</entry>
|
||
<entry>May also contain</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry>Keymap</entry>
|
||
<entry>
|
||
<para>Complete keyboard description</para>
|
||
<para>Normally assembled using a complete component from each of the other types</para>
|
||
</entry>
|
||
<entry></entry>
|
||
</row>
|
||
<row>
|
||
<entry>Keycodes</entry>
|
||
<entry>
|
||
<para>Symbolic name for each key</para>
|
||
<para>Minimum and maximum legal keycodes</para>
|
||
</entry>
|
||
<entry>
|
||
<para>Aliases for some keys</para>
|
||
<para>Symbolic names for indicators</para>
|
||
<para>Description of indicators physically present</para>
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry>Types</entry>
|
||
<entry>Key types</entry>
|
||
<entry>
|
||
Real modifier bindings and symbolic names for some virtual modifiers
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry>Compatibility</entry>
|
||
<entry>Rules used to assign actions to keysyms</entry>
|
||
<entry>
|
||
<para>Maps for some indicators</para>
|
||
<para>Real modifier bindings and symbolic names for some virtual modifiers</para>
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry>Symbols</entry>
|
||
<entry>
|
||
<para>Symbol mapping for keyboard keys</para>
|
||
<para>Modifier mapping</para>
|
||
<para>Symbolic names for groups</para>
|
||
</entry>
|
||
<entry>
|
||
<para>Explicit actions and behaviors for some keys</para>
|
||
<para>Real modifier bindings and symbolic names for some virtual modifiers</para>
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry>Geometry</entry>
|
||
<entry>Layout of the keyboard</entry>
|
||
<entry>
|
||
<para>Aliases for some keys; overrides keycodes component aliases</para>
|
||
<para>Symbolic names for some indicators</para>
|
||
<para>Description of indicators physically present</para>
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
While a keymap is a database entry for a complete keyboard description, and
|
||
therefore logically different from the individual component database entries,
|
||
the rules for processing keymap entries are identical to those for the
|
||
individual components. In the discussion that follows, the term component is
|
||
used to refer to either individual components or a keymap.
|
||
</para>
|
||
|
||
<para>
|
||
There may be multiple entries for each of the component types. An entry may be
|
||
either
|
||
<emphasis>complete</emphasis>
|
||
or
|
||
<emphasis>partial</emphasis>.
|
||
Partial entries describe only a piece of the corresponding keyboard component
|
||
and are designed to be combined with other entries of the same type to form a
|
||
complete entry.
|
||
</para>
|
||
|
||
<para>
|
||
For example, a partial symbols map might describe the differences between a
|
||
common ASCII keyboard and some national layout. Such a partial map is not
|
||
useful on its own because it does not include those symbols that are the same
|
||
on both the ASCII and national layouts (such as function keys). On the other
|
||
hand, this partial map can be used to configure
|
||
<emphasis>any</emphasis>
|
||
ASCII keyboard to use a national layout.
|
||
</para>
|
||
|
||
<para>
|
||
When a keyboard description is built, the components are processed in the order
|
||
in which they appear in <link linkend="table20.1">Table 20.1</link>;
|
||
later definitions override earlier ones.
|
||
</para>
|
||
|
||
<sect1 id='Component_Names'>
|
||
<title>Component Names</title>
|
||
|
||
<para>
|
||
Component names have the form “<replaceable>class(member)</replaceable>” where
|
||
<replaceable>class</replaceable>
|
||
describes a subset of the available components for a particular type and the
|
||
optional
|
||
<replaceable>member</replaceable>
|
||
identifies a specific component from that subset. For example, the name
|
||
"atlantis(acme)" for a symbols component might specify the symbols used for the
|
||
atlantis national keyboard layout by the vendor "acme." Each class has an
|
||
optional
|
||
<emphasis>default</emphasis>
|
||
member — references that specify a class but not a member refer to the
|
||
default member of the class, if one exists. Xkb places no constraints on the
|
||
interpretation of the class and member names used in component names.
|
||
</para>
|
||
|
||
<para>
|
||
The
|
||
<replaceable>class</replaceable>
|
||
and
|
||
<replaceable>member</replaceable>
|
||
names are both specified using characters from the Latin-1 character set. Xkb
|
||
implementations must accept all alphanumeric characters, minus (‘-’) and
|
||
underscore (‘_’) in class or member names, and must not accept parentheses,
|
||
plus, vertical bar, percent sign, asterisk, question mark, or white space. The
|
||
use of other characters is implementation-dependent.
|
||
</para>
|
||
|
||
</sect1>
|
||
<sect1 id='Listing_the_Known_Keyboard_Components'>
|
||
<title>Listing the Known Keyboard Components</title>
|
||
|
||
<para>
|
||
You may ask the server for a list of components for one or more component
|
||
types. The request takes the form of a set of patterns, one pattern for each of
|
||
the component types, including a pattern for the complete keyboard description.
|
||
To obtain this list, use
|
||
<function>XkbListComponents</function>.
|
||
</para>
|
||
|
||
<indexterm significance="preferred" zone="XkbListComponents"><primary><function>XkbListComponents</function></primary></indexterm>
|
||
<funcsynopsis id="XkbListComponents">
|
||
<funcprototype>
|
||
<funcdef>XkbComponentListPtr <function>XkbListComponents</function></funcdef>
|
||
<!-- (
|
||
<parameter>dpy</parameter>,
|
||
<parameter>device_spec</parameter>,
|
||
<parameter>ptrns</parameter>,
|
||
<parameter>max_inout</parameter>
|
||
) -->
|
||
|
||
<paramdef>Display *<parameter>dpy</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
|
||
<paramdef>XkbComponentNamesPtr <parameter>ptrns</parameter></paramdef>
|
||
<paramdef>int *<parameter>max_inout</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>dpy</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
connection to X server
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>device_spec</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
device ID, or <symbol>XkbUseCoreKbd</symbol>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>ptrns</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
namelist for components of interest
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>max_inout</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
max # returned names, # left over
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XkbListComponents</function>
|
||
queries the server for a list of component names matching the patterns
|
||
specified in
|
||
<parameter>ptrns</parameter>.
|
||
It waits for a reply and returns the matching component names in an
|
||
<structname>XkbComponentListRec</structname>
|
||
structure. When you are done using the structure, you should free it using
|
||
<function>XkbFreeComponentList</function>.
|
||
<parameter>device_spec</parameter>
|
||
indicates a particular device in which the caller is interested. A server is
|
||
allowed (but not required) to restrict its reply to portions of the database
|
||
that are relevant for that particular device.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
<parameter>ptrns</parameter>
|
||
is a pointer to an
|
||
<structname>XkbComponentNamesRec</structname>,
|
||
described below. Each of the fields in
|
||
<parameter>ptrns</parameter>
|
||
contains a pattern naming the components of interest. Each of the patterns is
|
||
composed of characters from the ISO
|
||
<emphasis>Latin1</emphasis>
|
||
encoding, but can contain only parentheses, the wildcard characters
|
||
‘<literal>?</literal>’ and ‘<literal>*</literal>’,
|
||
and characters permitted in a component class or member name
|
||
(see <link linkend="Component_Names">section 20.1</link>). A pattern may be
|
||
<symbol>NULL</symbol>,
|
||
in which case no components for that type is returned. Pattern matches with
|
||
component names are case sensitive. The
|
||
‘<literal>?</literal>’
|
||
wildcard matches any single character, except a left or right parenthesis;
|
||
the ‘<literal>*</literal>’
|
||
wildcard matches any number of characters, except a left or right
|
||
parenthesis. If an implementation allows additional characters in a component
|
||
class or member name other than those required by the Xkb extension (see
|
||
<link linkend="Component_Names">section 20.1</link>), the result of comparing one of the additional characters to
|
||
either of the wildcard characters is implementation-dependent.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
If a pattern contains illegal characters, the illegal characters are ignored.
|
||
The matching process is carried out as if the illegal characters were omitted
|
||
from the pattern.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
<parameter>max_inout</parameter>
|
||
is used to throttle the amount of data passed to and from the server. On
|
||
input, it specifies the maximum number of names to be returned (the total
|
||
number of names in all component categories). Upon return from
|
||
<function>XkbListComponents</function>,
|
||
<parameter>max_inout</parameter>
|
||
contains the number of names that matched the request but were not returned
|
||
because of the limit.
|
||
</para>
|
||
|
||
|
||
<para id='XkbComponentNamesRec'>
|
||
<indexterm significance="preferred" zone="XkbComponentNamesRec">
|
||
<primary><structname>XkbComponentNamesRec</structname></primary></indexterm>
|
||
The component name patterns used to describe the request are passed to
|
||
<function>XkbListComponents</function>
|
||
using an
|
||
<structname>XkbComponentNamesRec</structname>
|
||
structure. This structure has no special allocation constraints or
|
||
interrelationships with other structures; allocate and free this structure
|
||
using standard
|
||
<function>malloc</function>
|
||
and
|
||
<function>free</function>
|
||
calls or their equivalent:
|
||
|
||
<programlisting>
|
||
typedef struct _XkbComponentNames {
|
||
char * keymap; /* keymap names */
|
||
char * keycodes; /* keycode names */
|
||
char * types; /* type names */
|
||
char * compat; /* compatibility map names */
|
||
char * symbols; /* symbol names */
|
||
char * geometry; /* geometry names */
|
||
} <structname>XkbComponentNamesRec</structname>, *XkbComponentNamesPtr;
|
||
</programlisting></para>
|
||
|
||
<para id='XkbComponentListRec'>
|
||
<indexterm significance="preferred" zone="XkbComponentListRec">
|
||
<primary><structname>XkbComponentListRec</structname></primary></indexterm>
|
||
<indexterm significance="preferred" zone="XkbComponentListRec">
|
||
<primary><structname>XkbComponentNameRec</structname></primary></indexterm>
|
||
<function>XkbListComponents</function>
|
||
returns a pointer to an
|
||
<structname>XkbComponentListRec</structname>:
|
||
|
||
<programlisting>
|
||
typedef struct _XkbComponentList {
|
||
int num_keymaps; /* number of entries in keymap */
|
||
int num_keycodes; /* number of entries in keycodes */
|
||
int num_types; /* number of entries in types */
|
||
int num_compat; /* number of entries in compat */
|
||
int num_symbols; /* number of entries in symbols */
|
||
int num_geometry; /* number of entries in geometry;
|
||
XkbComponentNamePtr keymap; /* keymap names */
|
||
XkbComponentNamePtr keycodes; /* keycode names */
|
||
XkbComponentNamePtr types; /* type names */
|
||
XkbComponentNamePtr compat; /* compatibility map names */
|
||
XkbComponentNamePtr symbols; /* symbol names */
|
||
XkbComponentNamePtr geometry; /* geometry names */
|
||
} <structname>XkbComponentListRec</structname>, *XkbComponentListPtr;
|
||
|
||
typedef struct _XkbComponentName {
|
||
unsigned short flags; /* hints regarding component name */
|
||
char * name; /* name of component */
|
||
} <structname>XkbComponentNameRec</structname>, *XkbComponentNamePtr;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
Note that the structure used to specify patterns on input is an
|
||
<structname>XkbComponentNamesRec</structname>,
|
||
and that used to hold the individual component names upon return is an
|
||
<structname>XkbComponentNameRec</structname>
|
||
(no trailing ‘s’ in Name).
|
||
</para>
|
||
|
||
|
||
<para>
|
||
When you are done using the structure returned by
|
||
<function>XkbListComponents</function>,
|
||
free it using
|
||
<function>XkbFreeComponentList</function>.
|
||
</para>
|
||
|
||
|
||
<indexterm significance="preferred" zone="XkbFreeComponentList"><primary><function>XkbFreeComponentList</function></primary></indexterm>
|
||
<funcsynopsis id="XkbFreeComponentList">
|
||
<funcprototype>
|
||
<funcdef>void <function>XkbFreeComponentList</function></funcdef>
|
||
<!-- (list) -->
|
||
|
||
<paramdef>XkbComponentListPtr <parameter>list</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>list</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
pointer to <structname>XkbComponentListRec</structname> to free
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='Component_Hints'>
|
||
<title>Component Hints</title>
|
||
|
||
<para>
|
||
A set of flags is associated with each component; these flags provide
|
||
additional hints about the component’s use. These hints are designated by bit
|
||
masks in the flags field of the
|
||
<structname>XkbComponentNameRec</structname>
|
||
structures contained in the
|
||
<structname>XkbComponentListRec</structname>
|
||
returned from
|
||
<function>XkbListComponents</function>.
|
||
The least significant byte of the flags field has the same meaning for all
|
||
types of keyboard components; the interpretation of the most significant byte
|
||
is dependent on the type of component. The flags bits are defined in
|
||
<link linkend="table20.2">Table 20.2</link>.
|
||
The symbols hints in <link linkend="table20.2">Table 20.2</link>
|
||
apply only to partial symbols components
|
||
(those with
|
||
<symbol>XkbLC_Partial</symbol>
|
||
also set); full symbols components are assumed to specify all of the pieces.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The alphanumeric, modifier, keypad or function keys symbols hints should
|
||
describe the primary intent of the component designer and should not be simply
|
||
an exhaustive list of the kinds of keys that are affected. For example,
|
||
national keyboard layouts affect primarily alphanumeric keys, but many affect a
|
||
few modifier keys as well; such mappings should set only the
|
||
<symbol>XkbLC_AlphanumericKeys</symbol>
|
||
hint. In general, symbols components should set only one of the four flags
|
||
(
|
||
<symbol>XkbLC_AlternateGroup</symbol>
|
||
may be combined with any of the other flags).
|
||
</para>
|
||
|
||
<table id='table20.2' frame='topbot'>
|
||
<title>XkbComponentNameRec Flags Bits</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='4' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.5*'/>
|
||
<colspec colname='c2' colwidth='3.0*'/>
|
||
<colspec colname='c3' colwidth='2.0*'/>
|
||
<colspec colname='c4' colwidth='1.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Component Type</entry>
|
||
<entry>Component Hints (flags)</entry>
|
||
<entry>Meaning</entry>
|
||
<entry>Value</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry>All Components</entry>
|
||
<entry><para><symbol>XkbLC_Hidden</symbol></para></entry>
|
||
<entry>Do not present to user</entry>
|
||
<entry>(1L<<0)</entry>
|
||
</row>
|
||
<row>
|
||
<entry></entry>
|
||
<entry><symbol>XkbLC_Default</symbol></entry>
|
||
<entry>Default member of class</entry>
|
||
<entry>(1L<<1)</entry>
|
||
</row>
|
||
<row>
|
||
<entry></entry>
|
||
<entry><symbol>XkbLC_Partial</symbol></entry>
|
||
<entry>Partial component</entry>
|
||
<entry>(1L<<2)</entry>
|
||
</row>
|
||
<row>
|
||
<entry>Keymap</entry>
|
||
<entry>none</entry>
|
||
<entry></entry>
|
||
<entry></entry>
|
||
</row>
|
||
<row>
|
||
<entry>Keycodes</entry>
|
||
<entry>none</entry>
|
||
<entry></entry>
|
||
<entry></entry>
|
||
</row>
|
||
<row>
|
||
<entry>Types</entry>
|
||
<entry>none</entry>
|
||
<entry></entry>
|
||
<entry></entry>
|
||
</row>
|
||
<row>
|
||
<entry>Compatibility</entry>
|
||
<entry>none</entry>
|
||
<entry></entry>
|
||
<entry></entry>
|
||
</row>
|
||
<row>
|
||
<entry>Symbols</entry>
|
||
<entry><symbol>XkbLC_AlphanumericKeys</symbol></entry>
|
||
<entry>Bindings primarily for alphanumeric keyboard section</entry>
|
||
<entry>(1L<<8)</entry>
|
||
</row>
|
||
<row>
|
||
<entry></entry>
|
||
<entry><symbol>XkbLC_ModifierKeys</symbol></entry>
|
||
<entry>Bindings primarily for modifier keys</entry>
|
||
<entry>(1L<<9)</entry>
|
||
</row>
|
||
<row>
|
||
<entry></entry>
|
||
<entry><symbol>XkbLC_KeypadKeys</symbol></entry>
|
||
<entry>Bindings primarily for numeric keypad keys</entry>
|
||
<entry>(1L<<10)</entry>
|
||
</row>
|
||
<row>
|
||
<entry></entry>
|
||
<entry><symbol>XkbLC_FunctionKeys</symbol></entry>
|
||
<entry>Bindings primarily for function keys</entry>
|
||
<entry>(1L<<11)</entry>
|
||
</row>
|
||
<row>
|
||
<entry></entry>
|
||
<entry><symbol>XkbLC_AlternateGroup</symbol></entry>
|
||
<entry>Bindings for an alternate group</entry>
|
||
<entry>(1L<<12)</entry>
|
||
</row>
|
||
<row>
|
||
<entry>Geometry</entry>
|
||
<entry>none</entry>
|
||
<entry></entry>
|
||
<entry></entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
</sect1>
|
||
<sect1 id='Building_a_Keyboard_Description_Using_the_Server_Database'>
|
||
<title>Building a Keyboard Description Using the Server Database</title>
|
||
|
||
<para>
|
||
A client may request that the server fetch one or more components from its
|
||
database and use those components to build a new server keyboard description.
|
||
The new keyboard description may be built from scratch, or it may be built
|
||
starting with the current keyboard description for a particular device. Once
|
||
the keyboard description is built, all or part of it may be returned to the
|
||
client. The parts returned to the client need not include all of the parts used
|
||
to build the description. At the time it requests the server to build a new
|
||
keyboard description, a client may also request that the server use the new
|
||
description internally to replace the current keyboard description for a
|
||
specific device, in which case the behavior of the device changes accordingly.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To build a new keyboard description from a set of named components, and to
|
||
optionally have the server use the resulting description to replace an active
|
||
one, use
|
||
<function>XkbGetKeyboardByName</function>.
|
||
</para>
|
||
|
||
<indexterm significance="preferred" zone="XkbGetKeyboardByName"><primary><function>XkbGetKeyboardByName</function></primary></indexterm>
|
||
<funcsynopsis id="XkbGetKeyboardByName">
|
||
<funcprototype>
|
||
<funcdef>XkbDescPtr <function>XkbGetKeyboardByName</function></funcdef>
|
||
<!-- (
|
||
<parameter>dpy</parameter>,
|
||
<parameter>device_spec</parameter>,
|
||
<parameter>names</parameter>,
|
||
<parameter>want</parameter>,
|
||
<parameter>need</parameter>,
|
||
<parameter>load</parameter>
|
||
) -->
|
||
|
||
<paramdef>Display *<parameter>dpy</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
|
||
<paramdef>XkbComponentNamesPtr <parameter>names</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>want</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>need</parameter></paramdef>
|
||
<paramdef>Bool <parameter>load</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>dpy</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
connection to X server
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>device_spec</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
device ID, or <symbol>XkbUseCoreKbd</symbol>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>names</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
names of components to fetch
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>want</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
desired structures in returned record
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>need</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
mandatory structures in returned record
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>load</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
<symbol>True</symbol> ⇒ load into <parameter>device_spec</parameter>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<parameter>names</parameter>
|
||
contains a set of expressions describing the keyboard components the server
|
||
should use to build the new keyboard description.
|
||
<parameter>want</parameter>
|
||
and
|
||
<parameter>need</parameter>
|
||
are bit fields describing the parts of the resulting keyboard description that
|
||
should be present in the returned
|
||
<structname>XkbDescRec</structname>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The individual fields in
|
||
<parameter>names</parameter>
|
||
are
|
||
<firstterm>component expressions</firstterm>
|
||
composed of keyboard component names (no wildcarding as may be used in
|
||
<function>XkbListComponents</function>),
|
||
the special component name symbol ‘<literal>%</literal>’,
|
||
and the special operator characters
|
||
‘<literal>+</literal>’ and ‘<literal>|</literal>’.
|
||
A component expression is parsed left to right, as follows:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
The special component name “<literal>computed</literal>”
|
||
may be used in
|
||
<structfield>keycodes</structfield>
|
||
component expressions and refers to a component consisting of a set of
|
||
keycodes computed automatically by the server as needed.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The special component name “<literal>canonical</literal>” may be used in
|
||
<structfield>types</structfield>
|
||
component expressions and refers to a partial component defining the four
|
||
standard key types:
|
||
<emphasis>ALPHABETIC</emphasis>,
|
||
<emphasis>ONE_LEVEL</emphasis>,
|
||
<emphasis>TWO_LEVEL</emphasis>,
|
||
and
|
||
<emphasis>KEYPAD</emphasis>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The special component name ‘<literal>%</literal>’
|
||
refers to the keyboard description for the device specified in
|
||
<parameter>device_spec</parameter>
|
||
or the keymap names component. If a keymap names component is specified that
|
||
does not begin with
|
||
‘<literal>+</literal>’ or ‘<literal>|</literal>’ and does not contain
|
||
‘<literal>%</literal>’, then ‘<literal>%</literal>’
|
||
refers to the description generated by the keymap names component.
|
||
Otherwise, it refers to the keyboard description for
|
||
<parameter>device_spec</parameter>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The ‘<literal>+</literal>’
|
||
operator specifies that the following component should
|
||
<emphasis>override</emphasis>
|
||
the currently assembled description; any definitions that are present in both
|
||
components are taken from the second.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The ‘<literal>|</literal>’
|
||
operator specifies that the next specified component should
|
||
<emphasis>augment</emphasis>
|
||
the currently assembled description; any definitions that are present in both
|
||
components are taken from the first.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If the component expression begins with an operator, a leading
|
||
‘<literal>%</literal>’ is implied.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If any unknown or illegal characters appear anywhere in the expression, the
|
||
entire expression is invalid and is ignored.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
For example, if
|
||
<structfield>names->symbols</structfield>
|
||
contained the expression "+de", it specifies that the default member of the
|
||
"de" class of symbols should be applied to the current keyboard mapping,
|
||
overriding any existing definitions (it could also be written "+de(default)").
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Here is a slightly more involved example: the expression
|
||
"acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping for the
|
||
ASCII keyboard supplied by the "acme" vendor. The new definition begins with
|
||
the symbols for the ASCII keyboard for Acme
|
||
(<literal>acme(ascii)</literal>),
|
||
overrides them with definitions for the basic German keyboard
|
||
(<literal>de(basic)</literal>),
|
||
and then applies the definitions from the default iso9995-3 keyboard
|
||
(
|
||
<literal>iso9995-3</literal>)
|
||
to any undefined keys or groups of keys (part three of the iso9995 standard
|
||
defines a common set of bindings for the secondary group, but allows national
|
||
layouts to override those definitions where necessary).
|
||
</para>
|
||
|
||
<note><para>The interpretation of the above expression components (acme, ascii,
|
||
de, basic, iso9995-3) is not defined by Xkb; only the operations and their
|
||
ordering are.</para></note>
|
||
|
||
<para>
|
||
Note that the presence of a keymap
|
||
<parameter>names</parameter>
|
||
component that does not contain
|
||
‘<literal>%</literal>’
|
||
(either explicit or implied by virtue of an expression starting with an
|
||
operator) indicates a description that is independent of the keyboard
|
||
description for the device specified in
|
||
<parameter>device_spec</parameter>.
|
||
The same is true of requests in which the keymap names component is empty and
|
||
all five other names components contain expressions void of references to
|
||
‘<literal>%</literal>’.
|
||
Requests of this form allow you to deal with keyboard definitions
|
||
independent of any actual device.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The server parses all non-
|
||
<symbol>NULL</symbol>
|
||
fields in
|
||
<parameter>names</parameter>
|
||
and uses them to build a keyboard description. However, before parsing the
|
||
expressions in
|
||
<parameter>names</parameter>,
|
||
the server ORs the bits in
|
||
<parameter>want</parameter>
|
||
and
|
||
<parameter>need</parameter>
|
||
together and examines the result in relationship to the expressions in
|
||
<parameter>names</parameter>.
|
||
<link linkend="table20.3">Table 20.3</link>
|
||
identifies the components that are required for each of the
|
||
possible bits in
|
||
<parameter>want</parameter>
|
||
or
|
||
<parameter>need</parameter>.
|
||
If a required component has not been specified in the
|
||
<parameter>names</parameter>
|
||
structure (the corresponding field is
|
||
<symbol>NULL</symbol>),
|
||
the server substitutes the expression
|
||
“<literal>%</literal>”,
|
||
resulting in the component values being taken from
|
||
<parameter>device_spec</parameter>.
|
||
In addition, if
|
||
<parameter>load</parameter>
|
||
is
|
||
<symbol>True</symbol>,
|
||
the server modifies
|
||
<parameter>names</parameter>
|
||
if necessary (again using a
|
||
“<literal>%</literal>”
|
||
entry) to ensure all of the following fields are non-
|
||
<symbol>NULL</symbol>:
|
||
|
||
<structfield>types</structfield>,
|
||
<structfield>keycodes</structfield>,
|
||
<structfield>symbols</structfield>,
|
||
and
|
||
<structfield>compat</structfield>.
|
||
</para>
|
||
|
||
<table id='table20.3' frame='topbot'>
|
||
<title>Want and Need Mask Bits and Required Names Components</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='2.4*'/>
|
||
<colspec colname='c2' colwidth='2.6*'/>
|
||
<colspec colname='c3' colwidth='1.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>want or need mask bit</entry>
|
||
<entry>Required names Components</entry>
|
||
<entry>value</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbGBN_TypesMask</symbol></entry>
|
||
<entry>Types</entry>
|
||
<entry>(1L<<0)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_CompatMapMask</symbol></entry>
|
||
<entry>Compat</entry>
|
||
<entry>(1L<<1)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_ClientSymbolsMask</symbol></entry>
|
||
<entry>Types + Symbols + Keycodes</entry>
|
||
<entry>(1L<<2)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_ServerSymbolsMask</symbol></entry>
|
||
<entry>Types + Symbols + Keycodes</entry>
|
||
<entry>(1L<<3)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_SymbolsMask</symbol></entry>
|
||
<entry>Symbols</entry>
|
||
<entry>(1L<<1)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_IndicatorMapMask</symbol></entry>
|
||
<entry>Compat</entry>
|
||
<entry>(1L<<4)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_KeyNamesMask</symbol></entry>
|
||
<entry>Keycodes</entry>
|
||
<entry>(1L<<5)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_GeometryMask</symbol></entry>
|
||
<entry>Geometry</entry>
|
||
<entry>(1L<<6)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_OtherNamesMask</symbol></entry>
|
||
<entry>Types + Symbols + Keycodes + Compat + Geometry</entry>
|
||
<entry>(1L<<7)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_AllComponentsMask</symbol></entry>
|
||
<entry></entry>
|
||
<entry>(0xff)</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
<parameter>need</parameter>
|
||
specifies a set of keyboard components that the server must be able to resolve
|
||
in order for
|
||
<function>XkbGetKeyboardByName</function>
|
||
to succeed; if any of the components specified in
|
||
<parameter>need</parameter>
|
||
cannot be successfully resolved,
|
||
<function>XkbGetKeyboardByName</function>
|
||
fails.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
<parameter>want</parameter>
|
||
specifies a set of keyboard components that the server should attempt to
|
||
resolve, but that are not mandatory. If the server is unable to resolve any of
|
||
these components,
|
||
<function>XkbGetKeyboardByName</function>
|
||
still succeeds. Bits specified in
|
||
<parameter>want</parameter>
|
||
that are also specified in
|
||
<parameter>need</parameter>
|
||
have no effect in the context of
|
||
<parameter>want</parameter>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
If
|
||
<parameter>load</parameter>
|
||
is
|
||
<symbol>True</symbol>,
|
||
the server updates its keyboard description for
|
||
<parameter>device_spec</parameter>
|
||
to match the result of the keyboard description just built. If load is
|
||
<symbol>False</symbol>,
|
||
the server’s description for device
|
||
<parameter>device_spec</parameter>
|
||
is not updated. In all cases, the parts specified by
|
||
<parameter>want</parameter>
|
||
and
|
||
<parameter>need</parameter>
|
||
from the just-built keyboard description are returned.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The
|
||
<parameter>names</parameter>
|
||
structure in an
|
||
<structname>XkbDescRec</structname>
|
||
keyboard description record (see <xref linkend="Symbolic_Names" />) contains one field for each of
|
||
the five component types used to build a keyboard description. When a keyboard
|
||
description is built from a set of database components, the corresponding
|
||
fields in this
|
||
<parameter>names</parameter>
|
||
structure are set to match the expressions used to build the component.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The entire process of building a new keyboard description from the server
|
||
database of components and returning all or part of it is diagrammed in Figure
|
||
20.1:
|
||
</para>
|
||
|
||
<figure id='figure20.1'>
|
||
<title>Building a New Keyboard Description from the Server Database</title>
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-21.svg"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
<para>
|
||
The information returned to the client in the
|
||
<structname>XkbDescRec</structname>
|
||
is essentially the result of a series of calls to extract information from a
|
||
fictitious device whose description matches the one just built. The calls
|
||
corresponding to each of the mask bits are summarized in
|
||
<link linkend="table20.4">Table 20.4</link>, together with the
|
||
<structname>XkbDescRec</structname>
|
||
components that are filled in.
|
||
</para>
|
||
|
||
<table id='table20.4' frame='topbot'>
|
||
<title>XkbDescRec Components Returned for Values of Want & Needs</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>Request (want+need)</entry>
|
||
<entry>Fills in Xkb components</entry>
|
||
<entry>Equivalent Function Call</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><symbol>XkbGBN_TypesMask</symbol></entry>
|
||
<entry>map.types</entry>
|
||
<entry>XkbGetUpdatedMap(dpy, XkbTypesMask, Xkb)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_ServerSymbolsMask</symbol></entry>
|
||
<entry>server</entry>
|
||
<entry>XkbGetUpdatedMap(dpy, XkbAllClientInfoMask, Xkb)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_ClientSymbolsMask</symbol></entry>
|
||
<entry>map, including map.types</entry>
|
||
<entry>XkbGetUpdatedMap(dpy, XkbAllServerInfoMask, Xkb)</entry>
|
||
</row>
|
||
<row>
|
||
<entry>XkbGBN_IndicatorMaps</entry>
|
||
<entry>indicators</entry>
|
||
<entry>XkbGetIndicatorMap(dpy, XkbAllIndicators, Xkb)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_CompatMapMask</symbol></entry>
|
||
<entry>compat</entry>
|
||
<entry>XkbGetCompatMap(dpy, XkbAllCompatMask, Xkb)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_GeometryMask</symbol></entry>
|
||
<entry>geom</entry>
|
||
<entry>XkbGetGeometry(dpy, Xkb)</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_KeyNamesMask</symbol></entry>
|
||
<entry>
|
||
<para>names.keys</para>
|
||
<para>names.key_aliases</para>
|
||
</entry>
|
||
<entry>
|
||
XkbGetNames(dpy, XkbKeyNamesMask | XkbKeyAliasesMask, Xkb)
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><symbol>XkbGBN_OtherNamesMask</symbol></entry>
|
||
<entry>
|
||
<para>names.keycodes</para>
|
||
<para>names.geometry</para>
|
||
<para>names.symbols</para>
|
||
<para>names.types</para>
|
||
<para>map.types[*].lvl_names[*]</para>
|
||
<para>names.compat</para>
|
||
<para>names.vmods</para>
|
||
<para>names.indicators</para>
|
||
<para>names.groups</para>
|
||
<para>names.radio_groups</para>
|
||
<para>names.phys_symbols</para>
|
||
</entry>
|
||
<entry>
|
||
<para>XkbGetNames(dpy, XkbAllNamesMask &</para>
|
||
<para>~(XkbKeyNamesMask | XkbKeyAliasesMask),</para>
|
||
<para>Xkb)</para>
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
There is no way to determine which components specified in
|
||
<parameter>want</parameter>
|
||
(but not in
|
||
<parameter>need</parameter>)
|
||
were actually fetched, other than breaking the call into successive calls to
|
||
<function>XkbGetKeyboardByName</function>
|
||
and specifying individual components.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
<function>XkbGetKeyboardByName</function>
|
||
always sets
|
||
<structfield>min_key_code</structfield>
|
||
and
|
||
<structfield>max_key_code</structfield>
|
||
in the returned
|
||
<structname>XkbDescRec</structname>
|
||
structure.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
<function>XkbGetKeyboardByName</function>
|
||
is synchronous; it sends the request to the server to build a new keyboard
|
||
description and waits for the reply. If successful, the return value is
|
||
non-<symbol>NULL</symbol>.
|
||
<function>XkbGetKeyboardByName</function>
|
||
generates a <errorname>BadMatch</errorname>
|
||
protocol error if errors are encountered when building the keyboard
|
||
description.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
If you simply want to obtain information about the current keyboard device,
|
||
rather than generating a new keyboard description from elements in the server
|
||
database, use
|
||
<function>XkbGetKeyboard</function>
|
||
(see <link linkend="Obtaining_a_Keyboard_Description_from_the_Server">section 6.2</link>).
|
||
</para>
|
||
|
||
<indexterm significance="preferred" zone="XkbGetKeyboard"><primary><function>XkbGetKeyboard</function></primary></indexterm>
|
||
<funcsynopsis id="XkbGetKeyboard.20">
|
||
<funcprototype>
|
||
<funcdef>XkbDescPtr <function>XkbGetKeyboard</function></funcdef>
|
||
<!-- (
|
||
<parameter>dpy</parameter>,
|
||
<parameter>which</parameter>,
|
||
<parameter>device_spec</parameter>
|
||
) -->
|
||
|
||
<paramdef>Display *<parameter>dpy</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>which</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>dpy</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
connection to X server
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>which</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
mask of components of <structname>XkbDescRec</structname> of interest
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<parameter>device_spec</parameter>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
device ID
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XkbGetKeyboard</function>
|
||
is used to read the current description for one or more components of a
|
||
keyboard device. It calls
|
||
<function>XkbGetKeyboardByName</function>
|
||
as follows:
|
||
</para>
|
||
|
||
|
||
<para>
|
||
<function>XkbGetKeyboardByName</function>
|
||
(
|
||
<parameter>dpy</parameter>,
|
||
<parameter>device_spec</parameter>,
|
||
<symbol>NULL</symbol>,
|
||
<parameter>which</parameter>,
|
||
<parameter>which</parameter>,
|
||
<symbol>False</symbol>).
|
||
|
||
</para>
|
||
|
||
</sect1>
|
||
</chapter>
|