405 lines
13 KiB
XML
405 lines
13 KiB
XML
<chapter id='overview'>
|
||
<title>Overview</title>
|
||
|
||
<para>
|
||
The X Keyboard Extension provides capabilities that are lacking or are
|
||
cumbersome in the core X protocol.
|
||
</para>
|
||
|
||
<sect1 id='core_x_protocol_support_for_keyboards'>
|
||
<title>Core X Protocol Support for Keyboards</title>
|
||
|
||
<para>
|
||
The core X protocol specifies the ways that the
|
||
<emphasis>Shift</emphasis>,
|
||
<emphasis>Control</emphasis>, and
|
||
<emphasis>Lock</emphasis>
|
||
modifiers and the modifiers bound to the
|
||
<emphasis>Mode_switch</emphasis> or
|
||
<emphasis>Num_Lock</emphasis>
|
||
keysyms interact to generate keysyms and characters. The core protocol also
|
||
allows users to specify that a key affects one or more modifiers. This behavior
|
||
is simple and fairly flexible, but it has a number of limitations that make it
|
||
difficult or impossible to properly support many common varieties of keyboard
|
||
behavior. The limitations of core protocol support for keyboards include:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
Use of a single, uniform, four-symbol mapping for all keyboard keys makes it
|
||
difficult to properly support keyboard overlays, PC-style break keys, or
|
||
keyboards that comply with ISO9995, or a host of other national and
|
||
international standards.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A second keyboard group may be specified using a modifier, but this has side
|
||
effects that wreak havoc with client grabs and X toolkit translations.
|
||
Furthermore, this approach limits the number of keyboard groups to two.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Poorly specified locking key behavior requires X servers to look for a few
|
||
"magic" keysyms to determine that keys should lock when pressed. This leads to
|
||
incompatibilities between X servers with no way for clients to detect
|
||
implementation differences.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Poorly specified capitalization and control behavior requires modifications to
|
||
X library source code to support new character sets or locales and can lead to
|
||
incompatibilities between system wide and X library capitalization behavior.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Limited interactions between modifiers specified by the core protocol make many
|
||
common keyboard behaviors difficult or impossible to implement. For example,
|
||
there is no reliable way to indicate whether or not the shift modifier should
|
||
"cancel" the lock modifier.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The lack of any explicit descriptions for indicators, most modifiers, and other
|
||
aspects of the keyboard appearance requires clients that wish to clearly
|
||
describe the keyboard to a user to resort to a mish-mash of prior knowledge and
|
||
heuristics.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
</sect1>
|
||
<sect1 id='xkb_keyboard_extension_support_for_keyboards'>
|
||
<title>Xkb Keyboard Extension Support for Keyboards</title>
|
||
|
||
<para>
|
||
The X Keyboard Extension makes it possible to clearly and explicitly specify
|
||
most aspects of keyboard behavior on a per-key basis. It adds the notion of a
|
||
keyboard group to the global keyboard state and provides mechanisms to more
|
||
closely track the logical and physical state of the keyboard. For
|
||
keyboard-control clients, Xkb provides descriptions and symbolic names for many
|
||
aspects of keyboard appearance and behavior.
|
||
</para>
|
||
|
||
<para>
|
||
In addition, the X Keyboard Extension includes additional keyboard controls
|
||
designed to make keyboards more accessible to people with movement impairments.
|
||
</para>
|
||
|
||
</sect1>
|
||
|
||
<sect1 id='xkb_extension_components'>
|
||
<title>Xkb Extension Components</title>
|
||
|
||
<para>
|
||
The Xkb extension is composed of two parts: a server extension, and a
|
||
client-side X library extension. These consist of a loadable module that may be
|
||
activated when an X server is started and a modified version of Xlib. Both
|
||
server and Xlib versions must be at least X11 R6.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Figure 1.1 shows the overall structure of the Xkb extension:
|
||
</para>
|
||
|
||
<mediaobject>
|
||
<imageobject>
|
||
<imagedata format="SVG" fileref="XKBlib-1.svg"/>
|
||
</imageobject>
|
||
<caption>Overall Xkb Structure</caption>
|
||
</mediaobject>
|
||
|
||
|
||
<para>
|
||
The server portion of the Xkb extension encompasses a database of named
|
||
keyboard components, in unspecified format, that may be used to configure a
|
||
keyboard. Internally, the server maintains a <emphasis>
|
||
keyboard description</emphasis>
|
||
that includes the keyboard state and configuration (mapping). By "keyboard" we
|
||
mean the logical keyboard device, which includes not only the physical keys,
|
||
but also potentially a set of up to 32 indicators (usually LEDs) and bells.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The keyboard description is a composite of several different data structures,
|
||
each of which may be manipulated separately. When manipulating the server
|
||
components, the design allows partial components to be transmitted between the
|
||
server and a client. The individual components are shown in Figure 1.1.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>Client Map</term>
|
||
<listitem>
|
||
<para>
|
||
The key mapping information needed to convert arbitrary keycodes to symbols.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Server Map</term>
|
||
<listitem>
|
||
<para>
|
||
The key mapping information categorizing keys by functionality (which keys are
|
||
modifiers, how keys behave, and so on).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Controls</term>
|
||
<listitem>
|
||
<para>
|
||
Client configurable quantities effecting how the keyboard behaves, such as
|
||
repeat behavior and modifications for people with movement impairments.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Indicators</term>
|
||
<listitem>
|
||
<para>
|
||
The mapping of behavior to indicators.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Geometry</term>
|
||
<listitem>
|
||
<para>
|
||
A complete description of the physical keyboard layout, sufficient to draw a
|
||
representation of the keyboard.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Names</term>
|
||
<listitem>
|
||
<para>
|
||
A mapping of names to various aspects of the keyboard such as individual
|
||
virtual modifiers, indicators, and bells.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Compatibility Map</term>
|
||
<listitem>
|
||
<para>
|
||
The definition of how to map core protocol keyboard state to Xkb keyboard state.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
A client application interrogates and manipulates the keyboard by reading and
|
||
writing portions of the server description for the keyboard. In a typical
|
||
sequence a client would fetch the current information it is interested in,
|
||
modify it, and write it back. If a client wishes to track some portion of the
|
||
keyboard state, it typically maintains a local copy of the portion of the
|
||
server keyboard description dealing with the items of interest and updates this
|
||
local copy from events describing state transitions that are sent by the server.
|
||
</para>
|
||
|
||
<para>
|
||
A client may request the server to reconfigure the keyboard either by sending
|
||
explicit reconfiguration instructions to it, or by telling it to load a new
|
||
configuration from its database of named components. Partial reconfiguration
|
||
and incremental reconfiguration are both supported.
|
||
</para>
|
||
|
||
<sect2 id='groups_and_shift_levels'>
|
||
<title>Groups and Shift Levels</title>
|
||
|
||
<para>
|
||
The graphic characters or control functions that may be accessed by one key are
|
||
logically arranged in groups and levels. See section 14.1for a complete
|
||
description of groups and levels.
|
||
</para>
|
||
|
||
|
||
</sect2>
|
||
<sect2 id='radio_groups'>
|
||
<title>Radio Groups</title>
|
||
|
||
<para>
|
||
A radio group is a set of keys whose behavior simulates a set of radio buttons.
|
||
Once a key in a radio group is pressed, it stays logically depressed until
|
||
another key in the group is pressed, at which point the previously depressed
|
||
key is logically released. Consequently, at most one key in a radio group can
|
||
be logically depressed at one time. A radio group is defined by a radio group
|
||
index, an optional name, and by assigning each key in the radio group <emphasis>
|
||
XkbKB_RadioGroup</emphasis>
|
||
behavior and the radio group index.
|
||
</para>
|
||
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id='client_types'>
|
||
<title>Client Types</title>
|
||
|
||
<para>
|
||
This specification differentiates between three different classes of client
|
||
applications:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
Xkb-aware applications
|
||
</para>
|
||
<para>
|
||
These applications make specific use of Xkb functionality and APIs not present
|
||
in the core protocol.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Xkb-capable applications
|
||
</para>
|
||
<para>
|
||
These applications make no use of Xkb extended functionality and Application
|
||
Programming Interfaces (APIs) directly. However, they are linked with a version
|
||
of Xlib that includes Xkb and indirectly benefit from some of Xkb’s
|
||
features.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Xkb-unaware applications
|
||
</para>
|
||
<para>
|
||
These applications make no use of Xkb extended functionality or APIs and
|
||
require Xkb’s functionality to be mapped to core Xlib functionality to
|
||
operate properly.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
</sect1>
|
||
|
||
<sect1 id='compatibility_with_the_core_protocol'>
|
||
<title>Compatibility With the Core Protocol</title>
|
||
|
||
<para>
|
||
Because the Xkb extension allows a keyboard to be configured in ways not
|
||
foreseen by the core protocol, and because Xkb-unaware clients are allowed to
|
||
connect to a server using the Xkb extension, there must be a means of
|
||
converting between the Xkb domain and the core protocol. The Xkb server
|
||
extension maintains a compatibility map as part of its keyboard description;
|
||
this map controls the conversion of Xkb generated events to core protocol
|
||
events and the results of core protocol requests to appropriate Xkb state and
|
||
configuration.
|
||
</para>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='additional_protocol_errors'>
|
||
<title>Additional Protocol Errors</title>
|
||
|
||
<para>
|
||
The Xkb extension adds a single protocol error, <emphasis>
|
||
BadKeyboard</emphasis>
|
||
, to the core protocol error set. See section 2.6 for a discussion of the <!-- xref -->
|
||
<emphasis>
|
||
BadKeyboard</emphasis>
|
||
protocol error.
|
||
</para>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='extension_library_functions'>
|
||
<title>Extension Library Functions</title>
|
||
|
||
<para>
|
||
The X Keyboard Extension replaces the core protocol definition of a keyboard
|
||
with a more comprehensive one. The X Keyboard Extension library interfaces are
|
||
included in Xlib.<footnote><para>
|
||
X11R6.1 is the first release by the X Consortium, Inc.,that includes the X
|
||
Keyboard Extension in Xlib. X11R6 included work in progress on this extension
|
||
as nonstandard additions to the library.
|
||
</para>
|
||
</footnote>
|
||
</para>
|
||
|
||
<para>
|
||
Xlib detects the presence of the X Keyboard server extension and uses Xkb
|
||
protocol to replace some standard X library functions related to the keyboard.
|
||
If an application uses only standard X library functions to examine the
|
||
keyboard or process key events, it should not need to be modified when linked
|
||
with an X library containing the X keyboard extension. All of the
|
||
keyboard-related X library functions have been modified to automatically use
|
||
Xkb protocol when the server extension is present.
|
||
</para>
|
||
|
||
<para>
|
||
The Xkb extension adds library interfaces to allow a client application to
|
||
directly manipulate the new capabilities.
|
||
</para>
|
||
|
||
|
||
<sect2 id='error_indications'>
|
||
<title>Error Indications</title>
|
||
|
||
<para>
|
||
Xkb functions that communicate with the X server check to be sure the Xkb
|
||
extension has been properly initialized prior to doing any other operations. If
|
||
the extension has not been properly initialized or the application, library,
|
||
and server versions are incompatible, these functions return an error
|
||
indication as shown in Table 1.1. Because of this test, <emphasis>
|
||
BadAccess</emphasis>
|
||
and <emphasis>
|
||
BadMatch</emphasis>
|
||
(due to incompatible versions) protocol errors should normally not be
|
||
generated.
|
||
</para>
|
||
|
||
<table frame='none'>
|
||
<!-- <caption>Function Error Returns Due to Extension Problems</caption> -->
|
||
<title>Function Error Returns Due to Extension Problems</title>
|
||
<tgroup cols='2'>
|
||
<colspec align="left" colsep="0"/>
|
||
<colspec align="left" colsep="0"/>
|
||
<thead>
|
||
<row>
|
||
<entry>Functions return type</entry>
|
||
<entry>Return value</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry>pointer to a structure</entry>
|
||
<entry>NULL</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry>Bool</entry>
|
||
<entry>False</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry>Status</entry>
|
||
<entry>BadAccess</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>
|
||
Many Xkb functions do not actually communicate with the X server; they only
|
||
require processing in the client-side portion of the library. Furthermore, some
|
||
applications may never actually need to communicate with the server; they
|
||
simply use the Xkb library capabilities. The functions that do not communicate
|
||
with the server return either a pointer to a structure, a Bool, or a Status.
|
||
These functions check that the application has queried the Xkb library version
|
||
and return the values shown in Table 1.1 if it has not.
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
</chapter>
|