diff options
Diffstat (limited to 'libX11/specs/XKB/ch01.xml')
| -rw-r--r-- | libX11/specs/XKB/ch01.xml | 404 |
1 files changed, 404 insertions, 0 deletions
diff --git a/libX11/specs/XKB/ch01.xml b/libX11/specs/XKB/ch01.xml new file mode 100644 index 000000000..5079a411a --- /dev/null +++ b/libX11/specs/XKB/ch01.xml @@ -0,0 +1,404 @@ +<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> |