This document uses the syntactic conventions, common types, and errors defined in sections two through four of the specification of the X Window System Protocol. This document assumes familiarity with the fundamental concepts of X, especially those related to the way that X handles keyboards. Readers who are not familiar with the meaning or use of keycodes, keysyms or modifiers should consult (at least) the first five chapters of the protocol specification of the X Window System before continuing.

With the core protocol, there is no way to tell whether a modifier is set due to a lock or because the user is actually holding down a key; this can make for a clumsy user-interface as locked modifiers or group state interfere with accelerators and translations.

XKB adds explicit support for locking and latching modifiers and groups. Locked modifiers or groups apply to all future key events until they are explicitly changed. Latched modifiers or groups apply only to the next key event that does not change keyboard state.

The fundamental components of XKB keyboard state include:

The latched and locked state of modifiers and groups can be changed in response to keyboard activity or under application control using the XkbLatchLockState request. The base modifier, base group and pointer button states always reflect the logical state of the keyboard and pointer and change only in response to keyboard or pointer activity.

In addition to the fundamental state components, XKB keeps track of and reports a number of state components which are derived from the fundamental components but stored and reported separately to make it easier to track changes in the keyboard state. These derived components are updated automatically whenever any of the fundamental components change but cannot be changed directly.

The first pair of derived state components control the way that passive grabs are activated and the way that modifiers are reported in core protocol events that report state. The server uses the ServerInternalModifiers , IgnoreLocksModifiers and IgnoreGroupLock controls, described in Server Internal Modifiers and Ignore Locks Behavior, to derive these two states as follows:

The core protocol interpretation of keyboard modifiers does not include direct support for multiple groups, so XKB reports the effective keyboard group to XKB-aware clients using some of the reserved bits in the state field of some core protocol events, as described in Computing A State Field from an XKB State.

This modified state field would not be interpreted correctly by XKB-unaware clients, so XKB provides a group compatibility mapping (see Group Compatibility Map) which remaps the keyboard group into a core modifier mask that has similar effects, when possible. XKB maintains three compatibility state components that are used to make non-XKB clients work as well as possible:

Compatibility states are essentially the corresponding XKB state, but with keyboard group possibly encoded as one or more modifiers; Group Compatibility Map describes the group compatibility map, which specifies the modifier(s) that correspond to each keyboard group.

The compatibility state reported to XKB-unaware clients for any given core protocol event is computed from the modifier state that XKB-capable clients would see for that same event. For example, if the ignore group locks control is set and group 2 is locked, the modifier bound to Mode_switch is not reported in any event except (Device)KeyPress and (Device)KeyRelease events that do not trigger a passive grab.

XKB-aware clients can query the keyboard state at any time or request immediate notification of a change to any of the fundamental or derived components of the keyboard state.

Use an XKB modifier definition to specify the modifiers affected by any XKB control or data structure. An XKB modifier definition consists of a set of real modifiers, a set of virtual modifiers, and an effective mask. The mask is derived from the real and virtual modifiers and cannot be explicitly changed — it contains all of the real modifiers specified in the definition plus any real modifiers that are bound to the virtual modifiers specified in the definition. For example, this modifier definition specifies the numeric lock modifier if the Num_Lock keysym is not bound to any real modifier:

{ real_mods= None, virtual_mods= NumLock, mask= None }

If we assign Mod2 to the Num_Lock key, the definition changes to:

{ real_mods= None, virtual_mods= NumLock, mask= Mod2 }

Using this kind of modifier definition makes it easy to specify the desired behavior in such a way that XKB can automatically update all of the data structures that make up a keymap to reflect user or application specified changes in any one aspect of the keymap.

The use of modifier definitions also makes it possible to unambiguously specify the reason that a modifier is of interest. On a system for which the Alt and Meta keysyms are bound to the same modifier, the following definitions behave identically:

{ real_mods= None, virtual_mods= Alt, mask= Mod1 }
{ real_mods= None, virtual_mods= Meta, mask= Mod1 }

If we rebind one of the modifiers, the modifier definitions automatically reflect the change:

{ real_mods= None, virtual_mods= Alt, mask= Mod1 }
{ real_mods= None, virtual_mods= Meta, mask= Mod4 }

Without the level of indirection provided by virtual modifier maps and modifier definitions, we would have no way to tell which of the two definitions is concerned with Alt and which is concerned with Meta.

if ( state matches { Shift } ) Do OneThing;
if ( state matches { Shift+NumLock } ) Do Another;

XKB maintains a virtual modifier mapping , which lists the virtual modifiers associated with each key. The real modifiers bound to a virtual modifier always include all of the modifiers bound to any of the keys that specify that virtual modifier in their virtual modifier mapping.

For example, if Mod3 is bound to the Num_Lock key by the core protocol modifier mapping, and the NumLock virtual modifier is bound to they Num_Lock key by the virtual modifier mapping, Mod3 is added to the set of modifiers associated with the NumLock virtual modifier.

The virtual modifier mapping is normally updated automatically whenever actions are assigned to keys (see Changing the Keyboard Mapping Using the Core Protocol for details) and few applications should need to change the virtual modifier mapping explicitly.

The core protocol only allows control over whether or not the entire keyboard or individual keys should autorepeat when held down. The RepeatKeys control extends this capability by adding control over the delay until a key begins to repeat and the rate at which it repeats. RepeatKeys is also coupled with the core autorepeat control; changes to one are always reflected in the other.

The RepeatKeys control has two parameters. The autorepeat delay specifies the delay between the initial press of an autorepeating key and the first generated repeat event in milliseconds. The autorepeat interval specifies the delay between all subsequent generated repeat events in milliseconds.

Press -> Release -> Press -> Release -> Press -> Release

Press-> Press -> Press -> Release

Some users often bump keys accidentally while moving their hand or typing stick toward the key they want. Usually, the keys that are bumped accidentally are hit only for a very short period of time. The SlowKeys control helps filter these accidental bumps by telling the server to wait a specified period, called the SlowKeys acceptance delay , before delivering key events. If the key is released before this period elapses, no key events are generated. The user can then bump any number of keys on their way to the one they want without generating unwanted characters. Once they have reached the key they want, they can then hold it long enough for SlowKeys to accept it.

The SlowKeys control has one parameter; the slow keys delay specifies the length of time, in milliseconds, that a key must be held down before it is accepted.

When SlowKeys are active, the X Keyboard Extension reports the initial press, acceptance, rejection or release of any key to interested clients using AccessXNotify events. The AccessXNotify event is described in more detail in Events.

Some people with physical impairments accidentally "bounce" on a key when they press it. That is, they press it once, then accidentally press it again immediately. The BounceKeys control temporarily disables a key after it has been pressed, effectively "debouncing" the keyboard.

The BounceKeys has a single parameter. The BounceKeys delay specifies the period of time, in milliseconds, that the key is disabled after it is pressed.

When BounceKeys are active, the server reports the acceptance or rejection of any key to interested clients by sending an AccessXNotify event. The AccessXNotify event is described in more detail in Events.

Some people find it difficult or impossible to press two keys at once. The StickyKeys control makes it easier for them to type by changing the behavior of the modifier keys. When StickyKeys are enabled, a modifier is latched when the user presses it just once, so the user can first press a modifier, release it, then press another key. For example, to get an exclamation point (!) on a PC-style keyboard, the user can press the Shift key, release it, then press the 1 key.

By default, StickyKeys also allows users to lock modifier keys without requiring special locking keys. The user can press a modifier twice in a row to lock it, and then unlock it by pressing it one more time.

Modifiers are automatically unlatched when the user presses a non-modifier key. For instance, to enter the sequence Shift + Ctrl + Z the user could press and release the Shift key to latch the Shift modifier, then press and release the Ctrl key to latch the Control modifier — the Ctrl key is a modifier key, so pressing it does not unlatch the Shift modifier, but leaves both the Shift and Control modifiers latched, instead. When the user presses the Z key, it will be as though the user pressed Shift + Ctrl + Z simultaneously. The Z key is not a modifier key, so the Shift and Control modifiers are unlatched after the event is generated.

A locked a modifier remains in effect until the user unlocks it. For example, to enter the sequence ("XKB") on a PC-style keyboard with a typical US/ASCII layout, the user could press and release the Shift key twice to lock the Shift modifier. Then, when the user presses the 9 , ‘ , x , k , b , ‘ , and 0 keys in sequence, it will generate ("XKB"). To unlock the Shift modifier, the user can press and release the Shift key.

Two option flags modify the behavior of the StickyKeys control:

The MouseKeys control lets a user control all the mouse functions from the keyboard. When MouseKeys are enabled, all keys with MouseKeys actions bound to them generate core pointer events instead of normal key press and release events.

The MouseKeys control has a single parameter, the mouse keys default button , which specifies the core pointer button to be used by mouse keys actions that do not explicitly specify a button.

If the MouseKeysAccel control is enabled, the effect of a pointer motion action changes as a key is held down. The mouse keys delay specifies the amount of time between the initial key press and the first repeated motion event. The mouse keys interval specifies the amount of time between repeated mouse keys events. The steps to maximum acceleration field specifies the total number of events before the key is travelling at maximum speed. The maximum acceleration field specifies the maximum acceleration. The curve parameter controls the ramp used to reach maximum acceleration.

When MouseKeys are active and a SA_MovePtr key action (see Key Actions) is activated, a pointer motion event is generated immediately. If MouseKeysAccel is enabled and if acceleration is enabled for the key in question, a second event is generated after mouse keys delay milliseconds, and additional events are generated every mouse keys interval milliseconds for as long as the key is held down.

If AccessXKeys is enabled many controls can also be turned on or off from the keyboard by entering the following standard key sequences:

Some of these key sequences optionally generate audible feedback of the change in state, as described in The AccessXFeedback Control, or cause XkbAccessXNotify events as described in Events.

In environments where computers are shared, features such as SlowKeys present a problem: if SlowKeys is on, the keyboard can appear to be unresponsive because keys have no effect unless they are held for a certain period of time. To help address this problem, XKB provides an AccessXTimeout control to automatically change the value of any global controls or AccessX options if the keyboard is idle for a specified period of time.

The AccessXTimeout control has a number of parameters which affect the duration of the timeout and the features changed when the timeout expires.

The AccessX Timeout field specifies the number of seconds the keyboard must be idle before the global controls and AccessX options are modified. The AccessX Options Mask field specifies which values in the AccessX Options field are to be changed, and the AccessX Options Values field specifies the new values for those options. The AccessX Controls Mask field specifies which controls are to be changed in the global set of enabled controls , and the AccessX Controls Values field specifies the new values for those controls.

If AccessXFeedback is enabled, special beep-codes indicate changes in keyboard controls (or some key events when SlowKeys or StickyKeys are active). Many beep codes sound as multiple tones, but XKB reports a single XkbBellNotify event for the entire sequence of tones.

All feedback tones are governed by the AudibleBell control. Individual feedback tones can be explicitly enabled or disabled using the accessX options mask or set to deactivate after an idle period using the accessX timeout options mask . XKB defines the following feedback tones:

Implementations that cannot generate continuous tones may generate multiple beeps instead of falling and rising tones; for example, they can generate a high-pitched beep followed by a low-pitched beep instead of a continuous falling tone.

If the physical keyboard bell is not very capable, attempts to simulate a continuous tone with multiple bells can sound horrible. Set the DumbBellFB AccessX option to inform the server that the keyboard bell is not very capable and that XKB should use only simple bell combinations. Keyboard capabilities vary wildly, so the sounds generated for the individual bells when the DumbBellFB option is set are implementation specific.

A keyboard overlay allows some subset of the keyboard to report alternate keycodes when the overlay is enabled. For example a keyboard overlay can be used to simulate a numeric or editing keypad on keyboard that does not actually have one by generating alternate of keycodes for some keys when the overlay is enabled. This technique is very common on portable computers and embedded systems with small keyboards.

XKB includes direct support for two keyboard overlays, using the Overlay1 and Overlay2 controls. When Overlay1 is enabled, all of the keys that are members of the first keyboard overlay generate an alternate keycode. When Overlay2 is enabled, all of the keys that are members of the second keyboard overlay generate an alternate keycode.

To specify the overlay to which a key belongs and the alternate keycode it should generate when that overlay is enabled, assign it either the KB_Overlay1 or KB_Overlay2 key behaviors, as described in Key Behavior.

All of the controls described above, along with the AudibleBell control (described in Disabling Server Generated Bells) and the IgnoreGroupLock control (described in Server Internal Modifiers and Ignore Locks Behavior) comprise the boolean controls . In addition to any parameters listed in the descriptions of the individual controls, the boolean controls can be individually enabled or disabled by changing the value of the EnabledControls control.

The following non-boolean controls are always active and cannot be changed using the EnabledControls control or specified in any context that accepts only boolean controls: GroupsWrap (Computing Effective Modifier and Group), EnabledControls , InternalMods (Server Internal Modifiers and Ignore Locks Behavior), and IgnoreLockMods (Server Internal Modifiers and Ignore Locks Behavior) and PerKeyRepeat (The RepeatKeys Control)

The auto-reset controls are a per-client value which consist of two masks that can contain any of the boolean controls (see "Boolean" Controls and The EnabledControls Control). Whenever the client exits for any reason, any boolean controls specified in the auto-reset mask are set to the corresponding value from the auto-reset values mask. This makes it possible for clients to "clean up after themselves" automatically, even if abnormally terminated.

For example, a client that replace the keyboard bell with some other audible cue might want to turn off the AudibleBell control (Disabling Server Generated Bells) to prevent the server from also generating a sound and thus avoid cacophony. If the client were to exit without resetting the AudibleBell control, the user would be left without any feedback at all. Setting AudibleBell in both the auto-reset mask and auto-reset values guarantees that the audible bell will be turned back on when the client exits.

When the X Keyboard Extension receives a key event, it first checks the global key controls to decide whether to process the event immediately or at all. The global key controls which might affect the event, in descending order of priority, are:

Key events are processed by each global control in turn: if the BounceKeys control accepts a key event, SlowKeys considers it. Once SlowKeys allows or synthesizes an event, the RepeatKeys control acts on it.

Once an event is accepted by all of the controls or generated by a timer, the server checks the per-key behavior of the corresponding key. This extension currently defines the following key behaviors:

The X server uses key behavior to determine whether to process or filter out any given key event; key behavior is independent of keyboard modifier or group state (each key has exactly one behavior.

Key behaviors can be used to simulate any of these types of keys or to indicate an unmodifiable physical, electrical or software driver characteristic of a key. An optional permanent flag can modify any of the supported behaviors and indicates that behavior describes an unalterable physical, electrical or software aspect of the keyboard. Permanent behaviors cannot be changed or set by the XkbSetMap request. The permanent flag indicates a characteristic of the underlying system that XKB cannot affect, so XKB treats all permanent behaviors as if they were KB_Default and does not filter key events described in the table above.

Once the server has applied the global controls and per-key behavior and has decided to process a key event, it applies key actions to determine the effects of the key on the internal state of the server. A key action consists of an operator and some optional data. XKB supports actions which:

Each key has an optional list of actions. If present, this list parallels the list of symbols associated with the key (i.e. it has one action per symbol associated with the key). For key press events, the server looks up the action to be applied from this list using the key symbol mapping associated with the event key, just as a client looks up symbols as described in Determining the KeySym Associated with a Key Event; if the event key does not have any actions, the server uses the SA_NoAction event for that key regardless of modifier or group state.

Key actions have essentially two halves; the effects on the server when the key is pressed and the effects when the key is released. The action applied for a key press event determines the further actions, if any, that are applied to the corresponding release event or to events that occur while the key is held down. Clients can change the actions associated with a key while the key is down without changing the action applied next time the key is released; subsequent press-release pairs will use the newly bound key action.

Most actions directly change the state of the keyboard or server; some actions also modify other actions that occur simultaneously with them. Two actions occur simultaneously if the keys which invoke the actions are both logically down at the same time, regardless of the order in which they are pressed or delay between the activation of one and the other.

Most actions which affect keyboard modifier state accept a modifier definition (see Virtual Modifiers) named mods and a boolean flag name useModMap among their arguments. These two fields combine to specify the modifiers affected by the action as follows: If useModMap is True , the action sets any modifiers bound by the modifier mapping to the key that initiated the action; otherwise, the action sets the modifiers specified by mods . For brevity in the text of the following definitions, we refer to this combination of useModMap and mods as the "action modifiers."

The X Keyboard Extension supports the following actions:

If StickyKeys are enabled, all SA_SetMods and SA_SetGroup actions act like SA_LatchMods and SA_LatchGroup respectively. If the LatchToLock AccessX option is set, either action behaves as if both the SA_ClearLocks and SA_LatchToLock flags are set.

Actions which cause an event from another key or from a button on another device immediately generate the specified event. These actions do not consider the behavior or actions (if any) that are bound to the key or button to which the event is redirected.

Core events generated by server actions contain the keyboard state that was in effect at the time the key event occurred; the reported state does not reflect any changes in state that occur as a result of the actions bound to the key event that caused them.

Events sent to clients that have not issued an XkbUseExtension request contain a compatibility state in place of the actual XKB keyboard state. See Effects of XKB on Core Protocol Events for a description of this compatibility mapping.

The window and client that receive core protocol and input extension key or button events are determined using the focus policy, window hierarchy and passive grabs as specified by the core protocol and the input extension, with the following changes:

The following section explains the intent of the XKB interactions with core protocol grabs and the reason that the per-client flags are needed.

XKB associates a two-dimensional array of symbols with each key. Symbols are addressed by keyboard group (see Keyboard State) and shift level, where level is defined as in the ISO9995 standard:

Note that shift level is derived from the modifier state, but not necessarily in the same way for all keys. For example, the Shift modifier selects shift level 2 on most keys, but for keypad keys the modifier bound to Num_Lock (i.e. the NumLock virtual modifier) also selects shift level 2.gray symbols on a key

We use the notation G n L n to specify the position of a symbol on a key or in memory:

The gray characters indicate symbols that are implied or expected but are not actually engraved on the key.

To look up the symbol associated with an XKB key event, we need to know the group and shift level that correspond to the event.

Group is reported in bits 13-14 of the state field of the key event, as described in Computing A State Field from an XKB State. The keyboard group reported in the event might be out-of-range for any particular key because the number of groups can vary from key to key. The XKB description of each key contains a group info field which is interpreted identically to the global groups wrap control (see Computing Effective Modifier and Group) and which specifies the interpretation of groups that are out-of-range for that key.

Once we have determined the group to be used for the event, we have to determine the shift level. The description of a key includes a key type for each group of symbols bound to the key. Given the modifiers from the key event, this key type yields a shift level and a set of "leftover" modifiers, as described in Key Types below.

Finally, we can use the effective group and the shift level returned by the type of that group to look up a symbol in a two-dimensional array of symbols associated with the key.

type "ALPHABETIC" {
	modifiers = Shift+Lock;
	map[Shift]= Level2;
	map[Lock]= Level2;
	map[Shift+Lock]= Level2;
};

type "ALPHABETIC" {
	modifiers= Shift;
	map[Shift]= Level2;
};

type "ALPHABETIC" {
	modifiers = Shift+Lock;
	map[Shift] = Level2;
	preserve[Lock]= Lock;
};

Any modifiers that were not used to look up the keysym, or which were explicitly preserved, might indicate further transformations to be performed on the keysym or the character string that is derived from it. For example, If the Lock modifier is set, the symbol and corresponding string should be capitalized according to the locale-sensitive capitalization rules specified by the system. If the Control modifier is set, the keysym is not affected, but the corresponding character should be converted to a control character as described in Default Symbol Transformations.

This extension specifies the transformations to be applied when the Control or Lock modifiers are active but were not used to determine the keysym to be used:

Interpretation of other modifiers is application dependent.

XKB specifies the behavior of Lock and Control , but interpretation of other modifiers is left to the application.

Consider a simple, if unlikely, keyboard with the following keys (gray characters indicate symbols that are implied or expected but are not actually engraved on the key):

The core protocol represents this keyboard as a simple array with one row per key and four columns (the widest key, key 10, determines the width of the entire array).

The row to be used for a given key event is determined by keycode; the column to be used is determined by the symbols bound to the key, the state of the Shift and Lock Modifiers and the state of the modifiers bound to the Num_Lock and Mode_switch keys as specified by the core protocol.

The XKB description of this keyboard consists of six key symbol maps, each of which specifies the types and symbols associated with each keyboard group for one key:

The keycode reported in a key event determines the row to be used for that event; the effective keyboard group determines the list of symbols and key type to be used. The key type determines which symbol is chosen from the list.

Determining the KeySym Associated with a Key Event details the procedure to map from a key event to a symbol and/or a string.

XKB provides only two pieces of information about the indicators as a group.

The physical indicators mask reports which of the 32 logical keyboard indicators supported by the core protocol and XKB corresponds to some actual indicator on the keyboard itself. Because the physical indicators mask describes a physical characteristic of the keyboard, it cannot be directly changed under program control. It is possible, however, for the set of physical indicators to be change if a new keyboard is attached or if a completely new keyboard description is loaded by the XkbGetKeyboardByName request (see Using the Server’s Database of Keyboard Components).

The indicator state mask reports the current state of the 32 logical keyboard indicators. This field and the core protocol indicator state (as reported by the led-mask field of the core protocol GetKeyboardControl request) are always identical.

Each of the thirty-two keyboard indicators has a symbolic name, of type ATOM. The XkbGetNames request reports the symbolic names for all keyboard components, including the indicators. Use the XkbSetNames request to change symbolic names. Both requests are described in Querying and Changing Symbolic Names.

Clients can ask to receive XkbBellNotify event when a bell is requested by a client or generated by the server. Bells can be sounded due to core protocol Bell requests, X Input Extension DeviceBell requests, X Keyboard Extension XkbBell requests or for reasons internal to the server such as the XKB AccessXFeedback control.

Bell events caused by the XkbBell request or by the AccessXFeedback control include an optional window and symbolic name for the bell. If present, the window makes it possible to provide some kind of visual indication of which window caused the sound. The symbolic name can report some information about the reason the bell was generated and makes it possible to generate a distinct sound for each type of bell.

The global AudibleBell boolean control for a keyboard indicates whether bells sent to that device should normally cause the server to generate a sound. Applications which provide "sound effects" for the various named bells will typically disable the server generation of bells to avoid burying the user in sounds.

When the AudibleBell control is active, all bells caused by core protocol Bell and X Input Extension DeviceBell requests cause the server to generate a sound, as do all bells generated by the XKB AccessXFeedback control. Bells requested via the X kbBell request normally cause a server-generated sound, but clients can ask the server not to sound the default keyboard bell.

When the AudibleBell control is disabled, the server generates a sound only for bells that are generated using the XkbBell request and which specify forced delivery of the bell.

The XkbBell request allows clients to specify a symbolic name which is reported in the bell events they cause. Bells generated by the AccessXFeedback control of this extension also include a symbolic name, but all kinds of feedback cause a single event even if they sound multiple tones.

The X server is permitted to use symbolic bell names (when present) to generate sounds other than simple tones, but it is not required to do so.

Aside from those used by the XKB AccessXFeedback control (see The AccessXFeedback Control), this extension does not specify bell names or their interpretation.

Under some circumstances, some kind of quiet audio feedback is useful, but a normal keyboard bell is not. For example, a quiet "launch effect" can be helpful to let the user know that an application has been started, but a loud bell would simply be annoying.

To simplify generation of these kinds of effects, the XkbBell request allows clients to specify "event only" bells. The X server never generates a normal keyboard bell for "event only" bells, regardless of the setting of the global AudibleBell control.

If the X server generates different sounds depending bell name, it is permitted to generate a sound even for "event only" bells. This field is intended simply to weed out "normal" keyboard bells.

Occasionally, it is useful to force the server to generate a sound. For example, a client could "filter" server bells, generating sound effects for some but sounding the normal server bell for others. Such a client needs a way to tell the server that the requested bell should be generated regardless of the setting of the AudibleBell control.

To simplify this process, clients which call the XkbBell request can specify that a bell is forced. A forced bell always causes a server generated sound and never causes a XkbBellNotify event. Because forced bells do not cause bell notify events, they have no associated symbolic name or event window.

An outline is a list of one or more points which describes a single closed-polygon, as follows:

All points in an outline are specified relative to the origin of the enclosing shape. Points in an outline may have negative values for the X and Y coordinate.

One outline (usually the first) is the primary outline; a keyboard display application can generate a simpler but still accurate keyboard image by displaying only the primary outlines for each shape. Non-rectangular keys must include a rectangular approximation as one of the outlines associated with the shape; the approximation is not normally displayed but can be used by very simple keyboard display applications to generate a recognizable but degraded image of the keyboard.

Each section has its own coordinate system — if a section is rotated, the coordinates of any components within the section are interpreted relative to the edges that were on the top and left before rotation. The components that make up a section include:

Doodads can be global to the keyboard or part of a section. Doodads have symbolic names of arbitrary length. The only doodad name whose interpretation is specified by XKB is "Edges", which describes the outline of the entire keyboard, if present.

All doodads report their origin in fields named left and top . XKB supports five kinds of doodads:

Consider the following example keyboard:

This keyboard has six sections: The left and right function sections (at the very top) each have one horizontal row with eight keys. The left and right alphanumeric sections (the large sections in the middle) each have six vertical rows, with four or five keys in each row. The left and right editing sections each have three vertical rows with one to three keys per row; the left editing section is rotated 20° clockwise about its origin while the right editing section is rotated 20° counterclockwise.

This keyboard has four global doodads: Three small, round indicators and a rectangular logo. The program which generated this image did not recognize the logo, so it displays an outline with an appropriate shape in its place.

This keyboard has seven shapes: All of the keys in the two function sections use the "FKEY" shape. Most of the keys in the alphanumeric sections, as well as four of the keys in each of the editing sections use the "NORM" shape. The keys in the first column of the left alphanumeric section and the last column of the right alphanumeric section all use the "WIDE" shape. Two keys in each of the editing sections use the "TALL" shape. The "LED" shape describes the three small, round indicators between the function and alphabetic sections. The "LOGO" shape describes the keyboard logo, and the "EDGE" shape describes the outline of the keyboard as a whole.

The keyboard itself is white, as are all of the keys except for the eight keys that make up the home row, which use the "grey20" color. It isn’t really visible in this picture, but the three indicators have an "on" color of "green" and are "green30" when they are turned off. The keys in the alphanumeric and editing sections all have a (vertical) gap of 0.5mm; the keys in the two function sections have a (horizontal) gap of 3mm.

Many of the keys in the right alphanumeric section, and the rightmost key in the right editing section are drawn with two names in this image. Those are overlay keys; the bottom key name is the normal name while the overlay name is printed at the top. For example, the right editing section has a single overlay key entry, which specifies an under name of <SPCE> and an over name of <KP0> , which indicates that the key in question is usually the shift key, but can behave like the 0 key on the numeric keypad when an overlay is active.

As described in Keyboard State, the current keyboard group is reported to XKB-aware clients in bits 13-14 of the state field of many core protocol events. XKB-unaware clients cannot interpret those bits, but they might use a keyboard modifier to implement support for a single keyboard group. To ensure that pre-XKB clients continue to work when XKB is present, XKB makes it possible to map an XKB state field, which includes both keyboard group and modifier state into a pre-XKB state field which contains only modifiers.

A keyboard description includes one group compatibility map per keyboard group (four in all). Each such map is a modifier definition (i.e. specifies both real and virtual modifiers) which specifies the modifiers to be set in the compatibility states when the corresponding keyboard group is active. Here are a few examples to illustrate the application of the group compatibility map:

Note that non-XKB clients (i.e. clients that are linked with a version of the X library that does not support XKB) cannot detect the fact that Group4 is active in this example because the group compatibility map for Group4 does not specify any modifiers.

An XKB keyboard description includes a lot of information that is not present in the core protocol description of a keyboard. Whenever a client remaps the keyboard using core protocol requests, XKB examines the map to determine likely default values for the components that cannot be specified using the core protocol.

Some aspects of this automatic mapping are configurable, and make it fairly easy to take advantage of many XKB features using existing tools like xmodmap , but much of the process of mapping a core keyboard description into an XKB description is designed to preserve compatible behavior for pre-XKB clients and cannot be redefined by the user. Clients or users that want behavior that cannot be described using this mapping should use XKB functions directly.

G1L1, G1L2, G2L1, G2L2, G1L3, G2L3, G3L1, G3L2, G3L3, G4L1, G4L2, and G4L3

G1L1, (G1L2), G2L1, G2L2, G3L1, G3L2, G3L3

After applying server actions which modify the base, latched or locked modifier or group state of the keyboard, the X server recomputes the effective group and state. Several components of the keyboard state are reported to XKB-aware clients depending on context (see Keyboard State for a detailed description of each of the keyboard state components):

The server reports compatibility states to any clients that have not issued a successful XkbUseExtension request. The server computes the compatibility symbol lookup state and the compatibility effective grab state by applying the compatibility modifier map to the corresponding computed XKB states.

The compatibility symbol lookup state is reported to non-XKB clients whenever an XKB-aware client would receive the XKB lookup state. The compatibility grab state is reported to XKB-unaware clients whenever an XKB client would receive the XKB grab state.

If the GrabsUseXKBState per-client option is not set, even XKB-aware clients receive the compatibility grab state in events that trigger or terminate passive grabs. If this flag is not set, XKB clients also receive the compatibility grab or lookup state whenever any keyboard grab is active.

If the LookupStateWhenGrabbed per-client option is set, clients receive either the XKB or compatibility lookup state when the keyboard is grabbed, otherwise they receive either the XKB or compatibility grab state. All non-XKB clients receive the compatibility form of the appropriate state component; the form that is sent to an XKB-aware client depends on the setting of the GrabsUseXKBState option for that client.

Whenever a client updates the keyboard mapping using a core protocol request, the server saves the requested core protocol keyboard mapping and reports it to any clients that issue GetKeyboardMapping or GetModifierMapping requests. Whenever a client updates the keyboard mapping using XKB requests, the server discards the affected portion of the stored core keyboard description and regenerates it based on the XKB description of the keyboard.

The symbols associated with the XKB keyboard description appear in the order:

G1L1 G1L2 G2L1 G2L2 G1L3-n G2L3-n G3L* G4L*

If the type associated with Group1 is width one, the second symbol is NoSymbol ; if the type associated with Group2 is width one, the fourth symbol is NoSymbol .

If a key has only one group but the keyboard has several, the symbols for Group1 are repeated for each group. For example, given a keyboard with three groups and a key with one group that contains the symbols { a A }, the core protocol description would contain the six symbols: { a A a A a A }. As a slightly more complicated example, an XKB key which had a single width three group with the symbols { a b c } would show up in the generated core protocol keyboard description with the symbols { a b a b c c a b c } for a keyboard with three groups.

The generated modifier mapping for a key contains all of the modifiers affected by all of the actions associated with the key plus all of the modifiers associated with any virtual modifiers bound to the key by the virtual modifier mapping. If any of the actions associated with a key affect any component of the keyboard group, any modifiers specified in any entry of the group compatibility map (see Group Compatibility Map) are reported in the modifier mask. The SA_ISOLock action can theoretically affect any modifier, but the modifier map of an SA_ISOLock key contains only the modifiers or group state that it sets by default.

The server notifies interested clients of keyboard map changes in one of two ways. It sends XkbMapNotify to clients that have explicitly selected them and core protocol MappingNotify events to clients that have not. Once a client requests XkbMapNotify events, the server stops sending it MappingNotify events to inform it of keyboard changes.

XKB normally assumes that events sent to clients using the core protocol SendEvent request contain a core protocol state, if applicable. If the client which will receive the event is not XKB-capable, XKB attempts to convert the core state to an XKB state as follows: if any of the modifiers bound to Group2 in the group compatibility map are set in the event state, XKB clears them in the resulting event but sets the effective group in the event state to Group2 .

If the PCF_SendEventUsesXKBState per-client flag is set at the time of the SendEvent request, XKB instead assumes that the event reported in the event is an XKB state. If the receiving client is not XKB-aware, the extension converts the XKB state (which contains the effective state in bits 13-14) to a core state by applying the group compatibility map just as it would for actual key events.

Component and keymap names have the form " class ( member )" where class describes a subset of the available components for a particular type and the optional member identifies a specific component from that subset. For example, the name "atlantis(acme)" might specify the symbols used for the atlantis national keyboard layout by the vendor "acme." Each class has an optional default member — references which specify a class but not a member refer to the default member of the class, if one exists.

The class and member names are both specified using characters from the Latin-1 character set. XKB implementations must accept all alphanumeric characters, minus (‘-’) and underscore (‘_’) in class or member names, and must not accept parentheses, plus, vertical bar, percent sign, asterisk, question mark or white space. The use of other characters is implementation-dependent.

Some of the elements in the server database contain describe only a piece of the corresponding keyboard component. These partial components should be combined with other components of the same type to be useful.

For example, a partial symbols map might describe the differences between a common ASCII keyboard and some national layout. Such a partial map is not useful on its own because it does not include those symbols that are the same on both the ASCII and national layouts (such as function keys). On the other hand, this partial map can configure any ASCII keyboard to use a national layout.

Two components can be combined in two ways:

Applications can use a component expression to combine multiple components of some time into a complete description of some aspect of the keyboard. A component expression is a string which lists the components to be combined separated by operators which specify the rules for combining them. A complete description is assembled from the listed components, left to right, as follows:

For example, the component expression "+de" specifies that the default element of the "de" map should be applied to the current keyboard mapping, overriding any existing definitions.

A slightly more involved example: the expression "acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping for the ASCII keyboard supplied by the "acme" vendor. The new definition begins with the symbols for the default ASCII keyboard for Acme, overrides them with any keys that are defined for the default German keyboard layout and then applies the definitions from the iso9995-3 to any undefined keys or groups of keys (part three of the iso9995 standard defines a common set of bindings for the secondary group, but allows national layouts to override those definitions where necessary).

Each component has a set of flags that provide some additional hints about that component. XKB provides these hints for clients that present the keyboard database to users and specifies their interpretation only loosely. Clients can use these hints to constrain the list of components or to control the way that components are presented to the user.

Hints for a component are reported with its name. The least significant byte of the hints field has the same meaning for all five types of keyboard components, and can contain any combination of the following values:

The interpretation of the most significant byte of the hints field is dependent on the type of component. The hints defined for each kind of component are listed in the section below that describes that kind of component.

The five types of components stored in the server database of keyboard components correspond to the symbols , geometry , keycodes , compat and types symbolic names associated with a keyboard.

The keycodes component of a keyboard mapping specifies the range and interpretation of the raw keycodes reported by the device. It sets the keycodes symbolic name, the minimum and maximum legal keycodes for the keyboard, and the symbolic name for each key. The keycodes component might also contain aliases for some keys, symbolic names for some indicators, and a description of which indicators are physically present.

The special keycodes component named "computed" indicates that XKB should assign unused keycodes to any unknown keys referenced by name by any of the other components. The computed keycodes component is useful primarily when browsing keymaps because it makes it possible to use the symbols and geometry components without having to find a set of keycodes that includes keycode definitions for all of the keys listed in the two components.

XKB defines no hints that are specific to the keycodes component.

The X server also reports a set of fully specified keymaps. The keymaps specified in this list are usually assembled from the components stored in the rest of the database and typically represent the most commonly used keymaps for a particular system.

XKB defines no hints that are specific to complete keymaps.

All XKB requests and events include a device identifier which can refer to an input extension KeyClass device, if the implementation allows XKB to control extension devices. If the implementation does not support XKB manipulation of extension devices, the device identifier is ignored but it must be either 0 or UseCoreKbd .

Implementations which do not support the use of XKB functions with extension keyboards must not set the XkbXI_Keyboards flag. Attempts to use XKB features on an extension keyboard with an implementation that does not support this feature yield a Keyboard error.

The XKB extension optionally allows clients to assign any key action (see Key Actions) to core pointer or input extension device buttons. This makes it possible to control the keyboard or generate keyboard key events from extension devices or from the core pointer.

XKB implementations are required to support actions for the buttons of the core pointer device, but support for actions on extension devices is optional. Implementations which do not support button actions for extension devices must not set the XkbXI_ButtonActions flag.

Attempts to query or assign button actions with an implementation that does not support this feature report failure in the request reply and might cause the server to send an XkbExtensionDeviceNotify event to the client which issued the request that failed. Such requests never cause an error condition.

The XKB extension allows applications to assign indicator maps to the indicators of non-keyboard extension devices. If supported, maps can be assigned to all extension device indicators, whether they are part of a keyboard feedback or part of an indicator feedback.

Implementations which do not support indicator maps for extension devices must not set the XkbXI_IndicatorMaps flag.

Attempts to query or assign indicator maps with an implementation that does not support this feature report failure in the request reply and might cause the server to send an XkbExtensionDeviceNotify event to the client which issued the request that failed. Such requests never cause an error condition.

If this feature is supported, the maps for the default indicators on the core keyboard device are visible both as extension indicators and as the core indicators. Changes made with XkbSetDeviceInfo are visible via XkbGetIndicatorMap and changes made with XkbSetIndicatorMap are visible via XkbGetDeviceInfo .

The XKB extension allows applications to assign symbolic names to the indicators of non-keyboard extension devices. If supported, symbolic names can be assigned to all extension device indicators, whether they are part of a keyboard feedback or part of an indicator feedback.

Implementations which do not support indicator maps for extension devices must not set the XkbXI_IndicatorMaps flag.

Attempts to query or assign indicator names with an implementation that does not support this feature report failure in the request reply and might cause the server to send an XkbExtensionDeviceNotify event to the client which issued the request that failed. Such requests never cause an error condition.

If this feature is supported, the names for the default indicators on the core keyboard device are visible both as extension indicators and as the core indicators. Changes made with XkbSetDeviceInfo are visible via XkbGetNames and changes made with XkbSetNames are visible via XkbGetDeviceInfo .

If a client attempts to use any other XKB request except XkbUseExtension before the extension is properly initialized, XKB reports an Access error and ignores the request. XKB is properly initialized once XkbUseExtension reports that the client has asked for a supported or compatible version of the extension.

The following types are used in the request and event definitions in subsequent sections:

These types are used by the XkbGetGeometry and XkbSetGeometry requests:

These types are used by XkbGetDeviceInfo and XkbSetDeviceInfo :

This section lists all of the requests supported by the X Keyboard Extension, separated into categories of related requests.

This request enables XKB extension capabilities for the client that issues the request; the indicates that one or more of the other request fields should be appl be applied, as follows , firstKeySym,t">KB_KTSETMAPENTRYs"> GBN specified in Value error res/em> , butr the client that issues the request; the indicates that one or more of the other request fields should be applied, as follows , a locked group exceeds ay must be non-zero, or a Valueipan> array specifies the repeat behavior of the individua/td> a locked gro XkbMouseKeysrNonem> Value error res/em> , are set in changrable>