421 lines
14 KiB
XML
421 lines
14 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='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
|
||
<symbol>Shift</symbol>,
|
||
<symbol>Control</symbol>, and
|
||
<symbol>Lock</symbol>
|
||
modifiers and the modifiers bound to the
|
||
<keysym>Mode_switch</keysym> or
|
||
<keysym>Num_Lock</keysym>
|
||
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
|
||
<quote>magic</quote> 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
|
||
<quote>cancel</quote> 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>
|
||
<link linkend="figure1.1">Figure 1.1</link> shows the overall structure of the Xkb extension:
|
||
</para>
|
||
|
||
<figure id='figure1.1'>
|
||
<title>Overall Xkb Structure</title>
|
||
<mediaobject>
|
||
<imageobject>
|
||
<imagedata format="SVG" fileref="XKBlib-1.svg"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
|
||
<para id="keyboard_description">
|
||
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
|
||
<firstterm>keyboard description</firstterm>
|
||
<indexterm significance="preferred" zone="keyboard_description">
|
||
<primary>keyboard description</primary></indexterm>
|
||
that includes the keyboard state and configuration (mapping). By
|
||
<quote>keyboard</quote> 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 <link linkend="figure1.1">Figure 1.1</link>.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><link linkend="Xkb_Client_Keyboard_Mapping">Client Map</link></term>
|
||
<listitem>
|
||
<para>
|
||
The key mapping information needed to convert arbitrary keycodes to symbols.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><link linkend="Xkb_Server_Keyboard_Mapping">Server Map</link></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><link linkend="Keyboard_Controls">Controls</link></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><link linkend="Indicators">Indicators</link></term>
|
||
<listitem>
|
||
<para>
|
||
The mapping of behavior to indicators.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><link linkend="Keyboard_Geometry">Geometry</link></term>
|
||
<listitem>
|
||
<para>
|
||
A complete description of the physical keyboard layout, sufficient to draw a
|
||
representation of the keyboard.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><link linkend="Symbolic_Names">Names</link></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><link linkend="The_Xkb_Compatibility_Map">Compatibility Map</link></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 <link linkend="Notation_and_Terminology">section 14.1</link> for a complete
|
||
description of groups and levels.
|
||
</para>
|
||
|
||
|
||
</sect2>
|
||
<sect2 id='Radio_Groups'>
|
||
<title>Radio Groups</title>
|
||
|
||
<para>
|
||
<indexterm significance="preferred" zone="Radio_Groups">
|
||
<primary>radio group</primary></indexterm>
|
||
<indexterm significance="preferred" zone="Radio_Groups">
|
||
<primary>group</primary><secondary>radio</secondary></indexterm>
|
||
A <firstterm>radio group</firstterm>
|
||
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
|
||
<symbol>XkbKB_RadioGroup</symbol>
|
||
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,
|
||
<errorname>BadKeyboard</errorname>,
|
||
to the core protocol error set. See <link linkend="Protocol_Errors">section 2.6</link> for a discussion of the
|
||
<errorname>BadKeyboard</errorname>
|
||
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>
|
||
<indexterm zone="Error_Indications"><primary>errors</primary></indexterm>
|
||
|
||
<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 <link linkend="table1.1">Table 1.1</link>.
|
||
Because of this test,
|
||
<errorname>BadAccess</errorname>
|
||
and
|
||
<errorname>BadMatch</errorname>
|
||
(due to incompatible versions) protocol errors should normally not be
|
||
generated.
|
||
</para>
|
||
|
||
<table id='table1.1' frame='topbot'>
|
||
<!-- <caption>Function Error Returns Due to Extension Problems</caption> -->
|
||
<title>Function Error Returns Due to Extension Problems</title>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
<colspec colname='c1' colwidth='1.0*'/>
|
||
<colspec colname='c2' colwidth='1.0*'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Functions return type</entry>
|
||
<entry>Return value</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry>pointer to a structure</entry>
|
||
<entry><symbol>NULL</symbol></entry>
|
||
</row>
|
||
<row>
|
||
<entry>Bool</entry>
|
||
<entry><symbol>False</symbol></entry>
|
||
</row>
|
||
<row>
|
||
<entry>Status</entry>
|
||
<entry><errorname>BadAccess</errorname></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 <link linkend="table1.1">Table 1.1</link>
|
||
if it has not.
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
</chapter>
|