The X Keyboard Extension provides capabilities that are lacking or are cumbersome in the core X protocol. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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.