From 16b53769eba7d5d8249a217aa29287d72b7713c2 Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 14 Sep 2011 14:23:18 +0200 Subject: libX11 git update 14 sep 2011 --- libX11/specs/XKB/ch01.xml | 404 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 404 insertions(+) create mode 100644 libX11/specs/XKB/ch01.xml (limited to 'libX11/specs/XKB/ch01.xml') 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 @@ + +Overview + + +The X Keyboard Extension provides capabilities that are lacking or are +cumbersome in the core X protocol. + + + +Core X Protocol Support for Keyboards + + +The core X protocol specifies the ways that the +Shift, +Control, and +Lock +modifiers and the modifiers bound to the +Mode_switch or +Num_Lock +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: + + + + + +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. + + + + +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. + + + + +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. + + + + +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. + + + + +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. + + + + +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. + + + + + + +Xkb Keyboard Extension Support for Keyboards + + +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. + + + +In addition, the X Keyboard Extension includes additional keyboard controls +designed to make keyboards more accessible to people with movement impairments. + + + + + +Xkb Extension Components + + +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. + + + + +Figure 1.1 shows the overall structure of the Xkb extension: + + + + + + + Overall Xkb Structure + + + + +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 +keyboard description + 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. + + + + +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. + + + + + Client Map + + +The key mapping information needed to convert arbitrary keycodes to symbols. + + + + + Server Map + + +The key mapping information categorizing keys by functionality (which keys are +modifiers, how keys behave, and so on). + + + + + Controls + + +Client configurable quantities effecting how the keyboard behaves, such as +repeat behavior and modifications for people with movement impairments. + + + + + Indicators + + +The mapping of behavior to indicators. + + + + + Geometry + + +A complete description of the physical keyboard layout, sufficient to draw a +representation of the keyboard. + + + + + Names + + +A mapping of names to various aspects of the keyboard such as individual +virtual modifiers, indicators, and bells. + + + + + Compatibility Map + + +The definition of how to map core protocol keyboard state to Xkb keyboard state. + + + + + + +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. + + + +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. + + + +Groups and Shift Levels + + +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. + + + + + +Radio Groups + + +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 +XkbKB_RadioGroup + behavior and the radio group index. + + + + + + +Client Types + + +This specification differentiates between three different classes of client +applications: + + + + + +Xkb-aware applications + + +These applications make specific use of Xkb functionality and APIs not present +in the core protocol. + + + + +Xkb-capable applications + + +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. + + + + +Xkb-unaware applications + + +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. + + + + + + + +Compatibility With the Core Protocol + + +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. + + + + + +Additional Protocol Errors + + +The Xkb extension adds a single protocol error, +BadKeyboard +, to the core protocol error set. See section 2.6 for a discussion of the + +BadKeyboard + protocol error. + + + + + +Extension Library Functions + + +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. +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. + + + + + +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. + + + +The Xkb extension adds library interfaces to allow a client application to +directly manipulate the new capabilities. + + + + +Error Indications + + +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, +BadAccess + and +BadMatch + (due to incompatible versions) protocol errors should normally not be +generated. + + + + +Function Error Returns Due to Extension Problems + + + + + + Functions return type + Return value + + + + + pointer to a structure + NULL + + + Bool + False + + + Status + BadAccess + + + +
+ + +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. + + + + -- cgit v1.2.3