Section 1. 	Overview

This extension provides a number of new capabilities and controls for text keyboards. 

The core X protocol specifies the ways that the shift, mode_switch, control and lock 
modifiers interact to generate KeySyms and characters and 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 sup-
port for keyboards include:

o	Use of a single, uniform, four-symbol mapping for all keyboard keys makes it difficult 
to properly support a numeric keypad, keyboard overlays, PC-style break keys or 
ISO9995 standard keyboards.

o	Use of a modifier to specify a second keyboard group has a number of side-effects and 
wreaks havoc with client grabs and X toolkit translations and limits us to a single key-
board group. 

o	Poorly specified locking key behavior requires X servers to look for a few "magic" 
KeySyms to determine which keys should lock when pressed. This leads to a variety of 
incompatibilities between X servers with no way for clients to detect the differences 
between various implementations.

o	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.

o	The 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.

o	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.

This extension makes it possible to clearly and explicitly specify most aspects of key-
board behavior on a per-key basis. It adds the notion of a numeric 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, this extension pro-
vides descriptions and symbolic names for many aspects of keyboard appearance and 
behavior.

The X Keyboard Extension also includes a number of keyboard controls designed to 
make keyboards more accessible to people with movement impairments.

Section 2. Description

The X Keyboard Extension essentially replaces the core protocol definition of a key-
board. This section describes the new capabilities of the extension and the effect of the 
extension on core protocol requests, events and errors. Each subsection first describes 
some aspect of the core protocol support for keyboards and then describes the new 
extension behavior which replaces or extends it. 

Keyboard State

The core protocol description of keyboard state consists of eight modifiers. Whenever 
any key which affects some modifier is physically or logically depressed, that modifier 
is set in the keyboard state. The protocol implies that certain modifier keys lock (i.e. 
affect modifier state after they have been physically released) but does not explicitly 
discuss locking keys or their behavior. The current modifier state is reported to clients 
in a number of core protocol events and can be determined using the QueryPointer 
request.

The XKB extension adds the notion of a numeric keyboard group to the keyboard 
state. Keyboard group is used in combination with the eight core protocol modifiers to 
determine how a key event affects the server or clients. A keyboard may support at 
most eight keyboard groups.

This extension adds explicit support for locking and latching modifiers and group 
state. Locked modifiers and group apply to all future key events until they are explic-
itly changed. Latched modifiers apply only to the next key that does not change key-
board state.

The core protocol's interpretation of keyboard modifiers does not include support for 
multiple groups and might vary substantially from XKB. To make old clients behave 
reasonably, this extension includes a mechanism to map XKB modifier and group 
state into a "compatibility" state which is reported only to XKB-unaware clients. See 
the section titled "Alternate Symbols" below for a more complete description of this 
mapping.

The current effective keyboard group is reported to XKB-aware clients in the reserved 
bits in the state field of several core protocol events. The effective keyboard group is 
not directly reported to non-XKB clients, but it might affect the compatibility state 
reported to such clients in core protocol events.

The XKB description of keyboard state includes:

o	The locked modifiers and group

o	The latched modifiers and group

o	The base modifiers and group (for which keys are physically or logically down)

o	The effective modifiers and group (the cumulative effect of the base, locked and 
latched modifier and group states, see the section below titled "Other Keyboard Con-
trols" for a more complete discussion).

o	The compatibility state; this is the state that is reported to XKB-unaware clients. 

XKB-aware clients can query the current keyboard state at any time or request imme-
diate notification of a change in any of these components.

XKB includes two masks which are applied to the effective modifier state reported in 
core protocol events. In other words, the effective modifier state reported by the 
KBGetState request might include modifiers that are not set in the state as reported 
in core protocol events. The section below titled "Other Keyboard Controls" describes 
both of these masks in more detail.

Virtual Modifiers

The core protocol specifies the interpretation of the Shift, Lock and Control modifiers; 
the interpretation of the other five varies, usually depending on the keysyms bound to 
them. To avoid "hard-wired" definitions of these five modifiers in the various struc-
tures which describe an XKB keyboard, XKB supports sixteen "virtual" modifiers.

A virtual modifier has a name and at most one real modifier associated with it. You 
can use a virtual modifier to describe any aspect of keyboard behavior; whenever the 
value of a virtual modifier changes, XKB recalculates the corresponding real modifi-
ers for all keyboard data structures that use the changed virtual modifier.

Unless we explicitly specify "real" or "virtual" in this document, all references to 
modifiers or modifier masks refer to both real and virtual modifiers. For example, 
most of the modifier masks used in XKB data structures consist of an eight-bit real 
modifier mask and a sixteen-bit virtual modifier mask; we refer to such fields as mod-
ifier masks.

Keyboard Client Map

The core protocol keyboard mapping consists of a two-dimensional array of KeySyms, 
one row per key. A keyboard mapping may have up to 256 columns.

The core protocol specifies a set of rules for determining which of the first four col-
umns of a keyboard mapping should be used based on the state of the Shift modifier, 
the Lock modifier, and the real modifier (if any) assigned to the Mode_switch key. 
Before release 6, this mapping was the same for all keys on the keyboard; R6 added 
some support for numeric keypad keys.

An XKB keyboard client map tells clients how to map key events to KeySyms for any 
keyboard state. A client map consists of an array with one key symbol map per key-
code and alist of up to 255 key types. 

A key symbol map specifies the symbols associated with the key, the type of the key 
and the effect of keyboard group on the key. The symbols associated with a key can be 
thought of as a two-dimensional array whose height is determined by the groupWidth 
of the key type and whose width is determined by the number of groups associated 
with the key. The columns in this array are called groups and the rows are called shift 
levels.

Given the current real modifier state, a key type returns an shift level and a mask of 
unused real modifiers. It contains a mask which specifies the modifiers that affect keys 
of this type and a groupWidth which reports the largest shift level the key type can 
return. The map reports the shift level to be used for each significant combination of 
modifiers.

Modifiers that are used to select a shift level are normally consumed and are not used 
to determine further event processing. A key type contains an optional preserve field 
that indicates which of the significant modifiers should not be consumed by the shift 
level selection process.

Modifiers that are set and are not consumed by the symbol selection process may be 
used to determine additional transformations to be applied to the selected symbol. The 
X Keyboard Extension specifies the behavior of the Lock and Control modifiers, but 
interpretation of other modifiers is application-dependent.

Keyboard Server Map

The core protocol defines a modifier mapping, which consists of one list of keycodes 
per modifier. Each list specifies the keys that affect the corresponding modifier. When 
a key is logically down, any modifiers associated with the key by the modifier map-
ping are set. As defined by the core X protocol, keyboard state at any point in time is 
essentially the union of all modifiers that are affected by one of the keys that are logi-
cally pressed.

The core protocol implies that some modifier keys logically lock when pressed, but 
does not describe their behavior. It does not specify any rules by which a client or 
server can determine or control which keys should lock and does not explain how 
locking keys should be implemented.

An XKB keyboard server map describes the way the server handles events and 
includes mechanisms to clearly and explicitly specify for each key:

o	Whether the key locks or is a member of a radio group (key behavior).

o	The possible effects of pressing the key on the server (key actions).

The X server uses key behavior to determine whether to process or filter out any given 
key event. Key behavior can be used to simulate (or indicate) keys that physically lock 
or belong to a radio group. Some key behaviors are "permanent" which means they 
describe a "hard-wired" (usually physical) characteristic rather than a programmable 
XKB behavior. The server silently ignores attempts to change permanent behaviors.

Key behaviors and key event processing are described in detail in section 3, below.

Once the server has decided to process a key event, it applies server actions to deter-
mine the effects of the key on the internal state of the server. An action also consists of 
an operator and some optional data. XKB supports actions which:

o	change base, latched or locked modifiers or group

o	move the core pointer or simulate core pointer button events

o	change some aspects of keyboard behavior

o	terminate or suspend the server

o	send a message to XKB-aware clients

Each key has an optional array of actions. If defined, it parallels the array of symbols 
associated with the key (i.e. it has one action per symbol associated with the key). For 
KeyPress events, the server looks up the action to be applied from this list using the 
key symbol mapping associated with the event key.

Server 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 KeyPress 
event determines the further actions, if any, that are applied to the corresponding Key-
Release event or to events that occur while the key is held down.

The virtual modifiers field of the server map reports the real modifiers which corre-
spond to each of the sixteen virtual modifiers. Legal values for an entry in the virtual 
modifiers field include the index of any real modifier (range 0..7) or the constant 
NoModifier.

Many characteristics of a key can be determined automatically by applying symbol 
interpretations (described in more detail in the section titled "Compatibility Map" 
below). The server map includes an explicit components map which can force the 
server to retain assigned values for any or all of these components. The explicit com-
ponents map has one entry per keyboard key; each entry has the following boolean 
fields:

explicitKeyType			If true, disables automatic determination of key type.

explicitInterpret	ation	If true, symbol interpretations are not compared against or applied to
		this key; effectively disables virtual modifier calculation and 
		automatic determination of key actions, autorepeat and behavior.

explicitAutorepeat		If true, disables automatic determination of autorepeat for this key.

explicitBehavior		If true, disables automatic determination of behavior for this key.

Other Keyboard Controls

The core protocol provides a limited ability to control keyboard bells, autorepeat 
behavior, and LEDs. XKB extends this support and provides new controls over other 
aspects of key behavior.

The core protocol provides requests to control the pitch, volume and duration of the 
keyboard bell and a request to explicitly sound the bell. The audible bell control 
allows clients to disable core protocol and input extension bell requests. Extension 
requests also allow clients to attach an optional window and symbolic name to a bell 
request or to receive an event when the keyboard bell is rung.

The core protocol provides a request which can explicitly light or extinguish up to 
thirty-two keyboard LEDs but it does not interpret them in any way. XKB provides an 
indicator map which specifies the effect of keyboard controls or of the base, latched or 
locked modifier and keyboard group state on the keyboard indicators. The indicator 
map prevent explicit field contols the effect of core protocol LED requests; if prevent 
explicit is set for some indicator, its state can not be changed using the core protocol; 
attempts to do so are ignored.

The core protocol allows control over whether or not the entire keyboard or individual 
keys should autorepeat when held down. XKB adds the ability to control the rate at 
which repeating keys generate events. 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 gen-
erated repeat events in milliseconds.

If the auto-autorepeat control is set, XKB determines the autorepeat behavior of each 
key automatically using the symbol compatibility map (see "Effects of Core Protocol 
Requests on XKB" below). To control automatic autorepeat determination on a per-
key basis, use explicit components (see "Keyboard Server Map" above).

The keyboard group info control specifies the current number of keyboard groups and 
whether out-of-range groups are wrapped or truncated back into range. The number of 
keyboard groups is automatically updated to reflect changes in the key symbol map.

Keyboard keys normally generate KeyPress and KeyRelease events immediately 
when a key changes state, though the server might ignore some of these events or syn-
thesize others based on the behavior and action of the event in question. In addition to 
per-key behavior, XKB includes some global controls over the default key behavior. 

These global key behaviors were originally part of a separate extension called 
AccessX. AccessX was designed to make keyboards more accessible to people with 
movement impairments and has been merged with the more general X Keyboard 
Extension to minimize the number of extensions in the world. See "AccessX: Key-
board Enhancements to the X Server for People with Movement Impairments" by Will 
Walker and Mark Novak for a good rationale for and discussion of these features.

o	The slow keys control requires the user to hold a key for a specified period of time 
before the key is accepted. The slow keys delay is specified in milliseconds.

o	The bounce keys control debounces the keyboard by ignoring key press events which 
occur within a given time period after a release of the same key. The debounce delay is 
specified in milliseconds.

o	The sticky keys control changes the set modifiers and set groups actions to make all 
keyboard modifiers keys latch when pressed. XKB already provides the ability to make 
individual modifiers keys latch, but directly modifying the keyboard layout to make all 
modifier keys latch is both expensive and irreversible, so XKB supports a shortcut to 
provide this necessary capability.

o	The mouse keys control enables any key actions that control the core pointer device. 
When mouse keys are not enabled, such key behaviors just generate key press and 
release events normally. The mouse key default button specifies the default button to be 
used by actions that generate core pointer button events. 

o	The mouse keys accceleration control enables repeated events when a key which 
moves the core pointer is held down. The mouse keys delay, interval, steps to maximum 
acceleration, maximum acceleration and curve values control the rate at which the 
pointer accelerates when the user holds a mouse key. All times are specified in millisec-
onds.

o	The AccessXTimeout control automatically disables some keyboard controls if the 
keyboard and pointer remain idle for too long. The accessX timeout mask specifies the 
controls to be disabled automatically and the accessX timeout specifies the length of 
time in seconds the keyboard must be idle in order to automatically disable them.

o	The AccessXKeys control enables or disables special, standard key sequences which 
activate many of the AccessX features.

o	The AccessXFeedback control enables or disables special, standard sequences of 
keyboard bells to indicate activation or deactivation of the AccessX features or to indi-
cate acceptance of a key when slow keys are active.

All of these controls may be explicitly enabled or disabled using the KBSetControls 
request or the set controls key action. If AccessXKeys is enabled many of these con-
trols can also be turned on or off from the keyboard by entering special standard key 
sequences.

The core protocol does not provide any way to exclude certain modifiers from grab 
calculations, so locking modifiers often have unanticipated and unfortunate side-
effects. XKB provides two masks which can help avoid some of these problems.

Modifiers specified in the server internal modifiers mask are not reported in any core 
protocol events, are not used to determine grabs and are not used to calculate compati-
bility state for XKB-unaware clients. Server internal modifiers normally affect only 
the action applied when a key is pressed.

The locked state of the modifiers specified in the ignore locks mask is not reported in 
most core protocol events, and is not used to activate grabs. The only core protocol 
events which include the locked state of the modifiers in the ignore locks mask are 
KeyPress and KeyRelease events that do not activate a passive grab. The compati-
bility state reported to XKB-unaware clients for any given core protocol event is com-
puted from the modifier state that XKB-aware clients would see for that same event; 
e.g. the compatibility state reported to XKB-unaware clients in non-grab KeyPress 
and KeyRelease takes the locked state of all modifiers into account, but the compati-
bility state reported in all other core protocol events and requests might not.

Compatibility Map

In addition to providing a number of new requests, this extension replaces or extends 
existing core protocol requests and events. Some aspects of the this extension, such as 
the ability to lock any key or modifier, are visible even to clients that are unaware of 
the XKB extension. Other capabilities, such as control of keysym selection on a per-
key basis, are available only to XKB-aware clients. 

Though they do not have access to some advanced extension capabilities, the XKB 
extension includes compatibility mechanisms to ensure that non-XKB clients behave 
as expected and operate at least as well with an XKB-capable server as they do with-
out.

There are two significant areas in which XKB state and mapping differences might be 
visible to XKB-unaware clients:

o	The core protocol uses a modifier to choose between two keyboard groups, while this 
extension provides explicit support for multiple groups. 

o	The order of the symbols associated with any given key by XKB might not match the 
ordering demanded by the core protocol.

To minimize problems that might result from these differences, this extension includes 
ways to specify the correspondence between core protocol and XKB modifiers and 
symbols.

A keyboard description includes one modifier compatibility map per real or virtual 
modifier (twenty-four in all). Each such map specifies one or more groups and real 
modifiers that map to the corresponding compatibility modifier. Applying each of the 
modifier compatibility maps in turn to some modifier state and group yields a new 
KEYMASK suitable for XKB-unaware clients. If the group or any of the real modifi-
ers specified by one of the modifier compatibility maps are set in the source modifier 
state, the modifier which corresponds to the compatibility map is set in the resulting 
compatibility state.

Whenever some client changes the keyboard mapping using core protocol requests, 
the X server generates a corresponding XKB-specific description of the keyboard 
map. First, It chooses key types from a canonical list of key types by examining the 
symbols associated with each changed key and computes the number of groups for 
each key using the key type and the number of symbols assigned to the key by the core 
protocol. Next, it examines the symbols and modifier mapping for each changed key 
and assigns server actions where appropriate. Finally, it updates other XKB compati-
bility structures that should change to reflect the changes requested by the XKB-
unaware client.

Use explicit components (see "Keyboard Server Map") to disable one or more of these 
steps for specific keyboard keys.

Most 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 rede-
fined by the user. Clients or users that want behavior that cannot be described using 
this mapping should use XKB functions directly.

Keyboard Description

The core protocol does not provide any information to clients other than that actually 
used to interpret events. This makes it difficult to write a client which presents the key-
board to a user in an easy-to-understand way. Such applications have to examine the 
vendor string and keycodes to determine the type of keyboard connected to the server 
and have to examine keysyms and modifier mappings to determine the effects of most 
modifiers (the Shift, Lock and Control modifiers are defined by the core protocol 
but no semantics are implied for any other modifiers).

This extension provides such applications with symbolic names for most components 
of the keyboard extension and a description of the physical layout of the keyboard.

The keycodes name describes the range and meaning of the keycodes returned by the 
keyboard in question; the geometry name describes the physical location, size and 
shape of the various keys on the keyboard. As an example to distinguish between these 
two names, consider function keys on PC-compatible keyboards. Function keys are 
sometimes above the main keyboard and sometimes to the left of the main keyboard, 
but the same keycode is used for the key that is logically F1 regardless of physical 
position. Thus, all PC-compatible keyboards have the same keycodes name but might 
different geometry names.

Note	Keyboard type is intended to be a very general description of the keycodes returned by 
a keyboard; A single keyboard type might cover keyboards with differing numbers of 
keys provided that the keys that all keys have the same semantics when present. For 
example, 101 and 102 key PC keyboards might use the same name. Applications can 
use the keyboard keycode range or geometry to determine which subset of the named 
keyboard type is in use.

The symbols name and list of character sets identify and describe the symbols bound 
to the keys. The symbols name is a human or application-readable description of the 
intended locale or usage of the keyboard with these symbols. The list of character sets 
identifies the all of the character sets from which one or more symbols are defined. For 
example, a keyboard with both Cyrillic and Latin-1 symbols might have a symbols 
name of "ru" (a standard code for the Russian language/Russia locale) and list the 
character sets "iso8859-1" and "iso8859-5."

The semantics name is a symbolic description of the overall behavior of the keyboard. 
For example, the semantics name might indicate that a keyboard supports shift-can-
cels-caps behavior, uses arrow keys to control the core pointer or functions compatibly 
with some other system (such as a PC). The semantics name provides additional infor-
mation for the user or for keyboard layout programs and is not otherwise interpreted 
by the X Keyboard Extension.

The physical symbols and physical geometry names are similar to the normal symbols 
and geometry names but are intended to describe the actual physical appearance of the 
keyboard connected to the X server (i.e. before any remapping is applied). Layout pro-
grams can use these names to determine and restore "factory defaults" for the key-
board. X servers are allowed (but not required) to ignore attempts to set these names if 
they can determine that the actual keyboard has not changed or that the new names are 
incorrect. Servers are also allowed to change these names automatically if the initial 
keyboard is detectably replaced by a new, different keyboard.

XKB provides symbolic names for each of the eight keyboard modifiers and thirty-
two keyboard indicators.

XKB allows keyboard layout designers or editors to assign names to key types and to 
each of the levels in a key type. For example, the second position on an alphabetic key 
might be called the "Shift" level while the second position on a numeric keypad key 
might be called the "Numeric" level.

Each key has a four character symbolic name which keyboard layout or description 
applications can use to identify similar keys on physically different keyboards. For 
example, some workstation vendors use keyboards that look similar to PC keyboards 
but which return radically different keycodes. Use of symbolic names allows us to 
share one symbol map for keyboards that report either set of keycodes.

XKB supports names for up to 255 radio groups on a given keyboard. These names are 
provided as a convenience; the server does not verify that named radio groups actually 
have any members or that non-empty groups actually have names.

Alternate Symbols

This extension provides a limited ability to choose keyboard layout on a per-applica-
tion basis, which can be extremely useful in multilingual environments. Applications 
can request alternate symbol maps, which override the key symbol maps for some or 
all of the keys on the keyboard.

An alternate symbol set only changes the way a client interprets key events; neither 
key action nor behavior are affected.

XKB Events and Detailed Event Masks

The XKB extension provides events which report changes in any aspect of the XKB 
keyboard state, mappings or controls and which report additional information about 
some key events. Most events can be caused by changes in any of a number of compo-
nents or for any of a number of reasons, so each type of event has a details mask which 
allows clients to request a subset of the possible causes for a particular event. 

For example, the XKB keyboard mapping contains many components, but most cli-
ents are only concerned about changes to the components that directly affect the way 
they interpret key events: key types and key symbol maps. Such clients can select 
XkbMapNotify events with XkbKeyTypesMask|XkbKeySymsMask details and 
XKB will only report changes in those two map components to that client.

The description of the KBSelectEvents request contains a complete list of XKB 
event types and details for each type.

Section 3. Request and Key Event Processing

Key Event Processing in the Client

The state field of key events reported to XKB-aware clients contains the effective key-
board modifier state and group. The effective modifier state is reported in the low 
eight bits of the state field for compatibility with the core protocol. The effective group 
is reported in bits 13-15 of the state field, which are reserved by the core protocol.

The key symbol map associated with the key reported in a KeyPress or KeyRelease 
event is used to determine the symbol generated by the event. Determine the group 
used to look up a symbol as follows:

if ( effectiveGroup < nGroups)
	group = effectiveGroup
else if ( groupsWrap )
	group = effectiveGroup % nGroups
else	group = nGroups - 1

where:

% = integer modulus
effectiveGroup is taken from the keyboard state as reported in the event
nGroups and groupsWrap are from the key symbol map of the event key

The offset of the desired symbol within the group is determined by the key type and 
the effective modifier state, so the index of the symbol associated with an event is:

index = ( group  typegroupWidth ) + typemap( effectiveMods & typemask )

where:

& = bitwise AND

The state reported in the key event may specify additional transformations to be 
applied to the symbol before it is used. The preserve field of the key type specifies 
which of the modifiers that were used to compute the symbol offset should be taken 
into account for additional transformations:

consume = typemask & ~typepreserve( effectiveMods & typemask );
transform = ( effectiveMods & ~consume )

where:

~ 	= bitwise invert

This extension specifies the transformations to be applied when the Control or Lock 
modifiers are set in the remaining modifiers:

Modifier

Transformation

Control

Report the control character associated with the symbol. This exten-
sion defines the control characters associated with the ASCII alpha-
betic characters (both upper and lower case) and the KeySyms 
atsign, left_bracket, backslash, right_bracket, asci-
icircum and underbar (see Appendix B). Applications are free to 
associate control characters with any symbols that are not specified 
by this extension.

Lock

Capitalize the symbol either according to capitalization rules appro-
priate to the application locale or using the capitalization rules 
defined by this extension (see Appendix B).

Interpretation of other modifiers is application dependent.

Key Event Processing in the Server

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

o	If a key is pressed while the bounce keys control is enabled, the extension generates an 
event only if the key is active. When a key is released, the server deactivates the key 
and starts a bounce keys timer with an interval specified by the debounce delay.

If the bounce keys timer expires or if some other key is pressed before the timer 
expires, the server reactivates the corresponding key and deactivates the timer. Neither 
expiration nor deactivation of a bounce keys timer causes an event.

o	If the slow keys control is enabled, the extension sets a slow keys timer with an interval 
specified by the slow keys delay, but does not process the key event immediately. The 
corresponding release deactivates the timer and causes a KBSlowKeyNotify event.

If the slow keys timer expires, the server generates a key press for the corresponding 
key, sends a KBSlowKeyNotify and deactivates the timer.

o	If the repeat keys control for the keyboard is enabled, the extension processes key press 
events normally, but it also initiates an autorepeat timer with an interval specified by 
the autorepeat delay if per-key autorepeat is enabled for the event key. The correspond-
ing key release deactivates the timer. 

If the autorepeat timer expires, the server generates a key release and a key press for the 
corresponding key and reschedules the timer according to the autorepeat interval.

Timer-generated events report the sequence number, time and position at which the 
timer expired. The repeat keys, slow keys and bounce keys controls are not applied to 
timer initiated events, but per-key behavior and key actions are handled normally. 

Once a timer expires or the server decides to process an event based on the global key 
controls, it checks the per-key behavior of the corresponding key. XKB currently 
defines five key behaviors:

Behavior

Effect

KB_Default 

Press and release events are processed normally.

KB_Lock
	permanent: BOOL

If permanent is True, this behavior indicates a key that locks 
physically or in some software layer which is not under the con-
trol of XKB. Otherwise, XKB simulates a locking key as follows:

If a key is logically up (i.e. the corresponding bit of the core key 
map is cleared) when it is pressed, the key press is processed nor-
mally and the corresponding release is ignored. If the key is logi-
cally down when pressed, the key press is ignored but the 
corresponding release is processed normally. 

KB_RadioGroup
	permanent: BOOL
	index: CARD8

If permanent is True, this behavior indicates a key that behaves 
as a member of a radio group physically or in a software layer 
that is not under the control of XKB. Otherwise, XKB simulates 
radio group behavior as follows:

If another member of the radio group specified by index is logi-
cally down when a key is pressed, the server synthesizes a key 
release for the member that is logically down and then processes 
the new key press event normally. 

If the key itself is logically down when pressed, the key press 
event is ignored, but the release is processed normally.

All other key release events are ignored.

Next, the server determines the server action associated with any events allowed or 
generated by the per-key behavior. For key press events, the server chooses an action 
from the list of actions associated with the key. The action associated with key release 
events is determined solely by the action initiated by the corresponding key press.

If the list of actions associated with any key is length zero, the server applies 
SA_NoAction for that key regardless of the keyboard modifier or group state. Other-
wise, the server uses the action at the same offset as the symbol associated with the 
event. See "Key Event Processing in the Client" for an detailed explanation of choos-
ing a symbol for an event.

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 simulta-
neously if the keys which invoke the actions are both logically down at the same time, 
regardless of the order in which they are pressed.

Some actions take an argument of type XKBMASK, which consists of the useMod-
MapMods flag, a core protocol KEYMASK and a 16-bit VMODMASK which speci-
fies one or more virtual modifiers. If useModMapMods is True, the XKBMASK 
affects any modifiers associated with the key by the core protocol modifier mask, oth-
erwise it affects the modifiers specified by the KEYMASK and any real modifiers 
bound to the virtual modifiers specified by the VMODMASK. For example, if virtual 
modifier 1 is bound to Mod3, an XKBMASK which specifies the real modifier "Shift" 
and virtual modifier 1 affects both Shift and Mod3.

Version 0.29 of the X Keyboard Extension supports the following actions:

Action

Effect

SA_NoAction 

o	No direct effect, though SA_NoAction events may change the 
effect of other server actions (see below).

SA_SetMods
	clearLocks: BOOL	
	mods: XKBMASK

o	For key press events, sets the base modifiers specified in mods.

o	Key release clears the base modifiers in mods, provided that no 
other key which affects the same modifiers is logically down.

o	If no keys were operated simultaneously with the modifier shift 
key and clearLocks is set, key release also clears the locked state 
of any modifiers specified in mods.

SA_LatchMods
	clearLocks: BOOL
	latchToLock: BOOL
	mods: XKBMASK

o	Key press and key release events have the same effect as for 
SA_SetMods; if no keys were operated simultaneously with the 
latching modifier key, key release events have the following addi-
tional effects:

o	If clearLocks is set and takes effect, any modifiers that are 
unlocked have no further effect.

o	If latchToLock is set, the key release locks and unlatches any 
remaining mods that are already latched. Any such modifiers 
have no further effect.

o	Finally, key release latches any mods that were not used by 
clearLocks or latchToLock.

SA_LockMods
	mods: XKBMASK

o	For key press events, sets the base and locked state of any modifi-
ers specified in mods.

o	For key release events, clears the base modifiers specified in 
mods, provided that no other key which affects the same modifi-
ers is down. If the modifiers specified in mods were locked 
before the corresponding key press occurred, key release unlocks 
them.

SA_SetGroup
	absolute: BOOL
	clearLocks: BOOL
	group: INT8

o	If absolute is set, key press events change the base keyboard 
group to group; otherwise, they add group to the base keyboard 
group. In either case, the result is wrapped or truncated back into 
range depending on the value of the groupsWrap flag for the key-
board. 

o	If an SA_ISOLock key is pressed while this key is held down, 
key release has no effect, otherwise it cancels the effects of the 
corresponding press.

o	If no keys were operated simultaneously with the group shift key 
clearLocks is set, release also sets the locked keyboard group to 
0. 

SA_LatchGroup
	absolute: BOOL
	clearLocks: BOOL
	latchToLock: BOOL
	group: INT8

o	Key press and release events have the same effect as an SA_Set-
Group action; if no keys were operated simultaneously with the 
latching group key and clearLocks was not set or had no effect, 
key release has the following additional effects:

o	If latchToLock is set and the latched keyboard group is non-zero, 
the key release adds the delta applied by the corresponding key 
press to the locked keyboard group and subtracts it from the 
latched keyboard group.

o	Otherwise, key release adds the key press delta to the latched 
keyboard group.

SA_LockGroup

	absolute: BOOL
		group: INT8

o	If absolute is set, key press sets the locked keyboard group to 
group. Otherwise, key press adds group to the locked keyboard 
group. 

o	Key release has no effect.

SA_AccelPtr
	dx, dy: INT16

o	If MouseKeys are disabled, behaves like SA_NoAction.

o	Otherwise, key press generates a core pointer MotionNotify 
event instead of the usual KeyPress. The coordinates of the gen-
erated event are determined by adding dx and dy to the current 
core pointer position.

o	If the MouseKeysAccel control is enabled, key press also ini-
tiates the mouse keys timer for this key; every time this timer 
expires, the cursor moves again. The distance the cursor moves in 
these subsequent events is determined by the mouse keys acceler-
ation.

o	Key release disables the mouse keys timer if set but has no other 
effect and is ignored (does not generate an event of any type).

SA_MovePtr
	dx, dy: INT16

o	If MouseKeys are not enabled, this action behaves like SA_No-
Action.

o	Otherwise, key press and release behave like the SA_MovePtr 
action but do not affect the mouse keys timer.

SA_PtrBtn
		button: CARD8

o	If MouseKeys are not enabled, this action behaves like SA_No-
Action.

o	If the mouse button specified for this action is logically down, the 
key press and corresponding release are ignored and have no 
effect.

o	Otherwise, key press generates a core pointer ButtonPress 
event instead of the usual KeyPress. If button has the value 
SA_UseDfltBtn, the event is generated for the current default 
core button. Otherwise, the event is generated for the button spec-
ified by button.

o	Key release generates a core pointer ButtonRelease which 
matches the event generated by the corresponding key press. Key 
release does not generate a KeyRelease event.

SA_ClickPtrBtn
	count: CARD8
	button: CARD8

o	Behaves like SA_NoAction if MouseKeys are disabled.

o	If the mouse button specified for this action is logically down, the 
key press and corresponding release are ignored and have no 
effect.

o	Otherwise, key press generates count pairs of ButtonPress and 
ButtonRelease events instead of the usual KeyPress event. 
All events are for the button specified by button as interpreted by 
the SA_ClickPtrBtn action.

o	Key release has no effect and is ignored.

SA_LockPtrBtn
	button: CARD8

o	If MouseKeys are disabled, behaves like SA_NoAction.

o	Otherwise, if the button specified by button is not locked, key 
press causes a ButtonPress instead of a KeyPress and locks 
the button. If the button is already locked, key press is ignored 
and has no effect.

o	If the corresponding key press was ignored, key release generates 
a ButtonRelease event instead of a KeyRelease event and 
unlocks the specified button. If the corresponding key press 
locked a button, key release is ignored and has no effect.

SA_SetPtrDflt
	affect: CARD8
	flags: CARD8
	value: INT8

o	If MouseKeys are disabled, behaves like SA_NoAction.

o	Otherwise, both key press and key release are ignored, but key 
press changes the pointer value specified by which to value.

o	If affect is SA_AffectDfltBtn, this action changes the current 
default pointer button. If SA_DfltBtnAbsolute is set in flags, 
value specifies the default pointer button used by the various 
pointer actions, otherwise value specifies an amount to be added 
to the default button.

o	This action can cause a KBControlsNotify event.

SA_SetControls

	controls: CARD32

o	Key press enables any controls that are specified in controls and 
not already enabled at the time of the key press. Key release dis-
ables any controls that were enabled by the corresponding key 
press. This action can cause KBControlsNotify events.

SA_LockControls

	controls: CARD32

o	Key press locks and enables any controls that are specified in 
controls and not already locked at the time of the key press. Key 
release unlocks and disables any controls that are specified in 
controls and were not enabled at the time of the corresponding 
key press. This action can cause a KBControlsNotify event.

SA_ISOLock
	dfltIsGroup: BOOL
	clearLocks: BOOL
	latchToLock: BOOL
	noAffectMods: BOOL
	noAffectGroup:BOOL
	noAffectPtr: BOOL
	noAffectCtrls: BOOL
	mods: XKBMASK
	absolute: BOOL
	group: INT8

o	If dfltIsGroup is True, key press sets the base group specified by 
absolute and group. Otherwise, key press sets the base modifiers 
specified in mods. 

o	Key release clears the base modifiers or group that were set by the 
key press; it may have additional effects if no other appropriate 
actions occur simultaneously with the SA_ISOLock operation.

o	If noAffectMods is False, any SA_SetMods or SA_LatchMods 
actions that occur simultaneously with the ISOLock action are 
treated as SA_LockMods instead.

o	If noAffectGroup is False, any SA_SetGroup or SA_Latch-
Group actions that occur simultaneously with this action are 
treated as SA_LockGroup instead.

o	If noAffectPtr is False, SA_PtrBtn actions that occur simulta-
neously with the SA_ISOLock action are treated as SA_LockP-
trBtn actions instead.

o	If noAffectCtrls is set, any SA_SetControls actions that occur 
simulatneously with the SA_ISOLock action are treated as 
SA_LockControls actions instead.

o	If no other actions were transformed by the SA_ISOLock action, 
key release locks the group or modifiers specified by the action 
arguments.

SA_TerminateServer 

o	Key press terminates the server. Key release is ignored.

o	This action is optional; servers are free to ignore it. If ignored, it 
behaves like SA_NoAction.

SA_SwitchScreen
	switchApps: BOOL
	absolute: BOOL
	num: INT8

o	If the server supports this action and multiple screens or displays 
(either virtual or real), this actions changes to the active screen 
indicated by num. If switchApps is False, the server should 
switch to another screen on the same display, otherwise it should 
switch to another application which shares the physical display.

o	If absolute is True, num specifies an absolute screen index to be 
used; otherwise, num specifies an offset from the current screen.

o	This action is optional; servers are free to ignore it if they do not 
support virtual screens. If ignored, it behaves like SA_NoAction, 
otherwise neither press nor release cause an event.

SA_ActionMessage
	msgPress: BOOL
	msgRelese: BOOL
	genKeyEvent: BOOL
	data: LISTofCARD8

o	Generates KBActionMessage events in place of or in addition to 
core events.

o	If msgPress is True, key press causes a KBActionMessage 
event; if msgRelease is True, key release causes an event. Any 
combination of msgPress and msgRelease is valid.

o	If genKeyEvent is True, the server also generates the correspond-
ing core protocol key press and release events, otherwise it gener-
ates only the KBActionMessage events.

If StickyKeys are enabled, all SA_SetMods and SA_SetGroup actions act like 
SA_LatchMods and SA_LatchGroup respectively. Either event behaves as if both 
the clearLocks and latchToLock arguments are True.

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 a KB_UseExtension request contain a 
compatibility state in place of the actual XKB keyboard state. See "Effects of XKB on 
Core Protocol Requests and Events" below for a description of compatibility mapping.

If an action changes any component of the keyboard state, the server sends 
KBStateNotify events to any clients that have requested them. 

Effects of Core Protocol Requests on XKB

In response to a core protocol ChangeKeyboardMapping request, the X server 
assigns a key type to each changed key from a canonical list of key types. The first 
three key types in any keyboard map are reserved for these standard key types:

Key Type Name

Standard Definition

ONE_LEVEL

Describes keys that have exactly one symbol per group. Most special 
or function keys (such as Return) are ONE_LEVEL keys. Any combi-
nation of modifiers yields level 0. Index 0 in any key symbol map 
specifies key type ONE_LEVEL.

TWO_LEVEL

Describes non-keypad keys that have exactly two symbols per group. 
Most alphanumeric keys are TWO_LEVEL keys. Yields column 1 if the 
Shift modifier is set, column 0 otherwise. Index 1 in any key symbol 
map specifies key type TWO_LEVEL.

KEYPAD

Describes numeric keypad keys with two symbols per group. Yields 
column 1 if either the Shift modifier or the default num lock modi-
fier alone are set. Yields column 0 if neither or both modifiers are set. 
Index 2 in any key symbol map specifies key type KEYPAD.

Users or applications may redefine these key types to get different default behavior (to 
make shift cancel caps lock, for example) but they must always have the specified 
number of symbols per group.

The server does not change the assigned type of any keys for which explicitKeyType is 
set in the explicit components map. If explicitKeyType is not set, the server chooses a 
key type as follows:

Before choosing a type for a key, the X server expands any alphanumeric symbol def-
initions according to the core protocol rules: If the second symbol of either group is 
NoSymbol and the first symbol of that group is an alphabetic KEYSYM for which 
both lowercase and uppercase forms are defined, the X server treats the key as if the 
first element of the group were the lowercase form of the symbol and the second ele-
ment were the uppercase form of the symbol.

If the new list of keysyms for the key has one member or the form "K1 NoSymbol K2 
NoSymbol" (after alphanumeric expansion and ignoring trailing NoSymbol entries) 
the server assigns key type ONE_LEVEL. If both symbols in the first group are numeric 
keypad keysyms, the server assigns key type KEYPAD. Otherwise, it assigns key type 
TWO_LEVEL.

After choosing a key type, the server determines the number of groups associated with 
the key and the XKB keysym list which corresponds to the standard core protocol 
interpretation of the first two keyboard groups for the chosen key type.

This extension does not define the interpretation of any keysyms in a core keyboard 
mapping beyond the first four symbols.

Unless explicitInterpretation is set in the explicit components map of a changed key, 
the X server determines autorepeat, updates virtual modifiers and assigns actions and 
behaviors to the key as specified by the keyboard's symbol compatibility map. The 
symbol compatibility map is a list of symbol interpretation structures.

Each symbol interpretation has four fields which are compared to each keysym and the 
modifier mapping on any keys that have changed. The symbol field is a KEYSYM 
which matches if it has the value NoSymbol or is identical to the symbol in question. 
The modifiers associated with the symbol are compared to the modifiers specified in 
the mods field as indicated by match. The match field can specify any of the compari-
sions: NoneOf, AnyOfOrNone, AnyOf, AllOf or Exactly. The modifiers assigned 
to the key by the core protocol modifier mapping are associated with the symbol 
unless levelOneOnly is True and the symbol in question is not the first symbol bound 
to a key, in which case an empty modifier mask is used instead.

The server compares each keysym and the modifier mapping for all changed keys to 
each symbol interpretation in turn. If all three fields match, the server applies the inter-
spretation to the key in question. A symbol interpretation applies the following fields:

Field

Type

Effect

action

XkbAction

Assigned to the key and symbol position in question.

autorepeat

BOOL

If the auto-autorepeat control is enabled, explicitAutorepeat 
is False in the explicit components map for this key and the 
symbol in question is the first symbol associated with the key, 
the autorepeat behavior of the key is changed to this value.

virtualMod

0..15 OR
NoModifier

If this field specifies a valid virtual modifier, the highest real 
modifier associated with this key by the core modifier map-
ping is bound to the specified virtual modifier. Any XKB 
structures defined in terms of the specified virtual modifier 
are updated to reflect the new binding.

lockingKey

BOOL

If True, and if explicitBehavior is False, the behavior of the 
key in question is changed to KB_Lock.

The server considers all symbol interpretations which specify an explicit keysym 
before considering any that do not. The server uses the first interpretation which 
matches the given combination of keysym and modifier mapping; other matching 
interpretations are ignored. If no elements match, the server uses SA_NoAction and 
KB_Default.

If all of the actions computed for a key are SA_NoAction, the server assigns an empty 
list of actions to the key.

If the core protocol modifier mapping is changed, the server regenerates actions for all 
keyboard keys by applying the symbol compatibility map as described above. As an 
option, actions can also be recomputed when keyboard symbols are updated using 
XKB requests.

Explicitly changing the autorepeat mode of any keyboard key using the core protocol 
ChangeKeyboardControl request sets explicitAutorepeat for that key to prevent 
automatic calculation of autorepeat behavior for that key in the future.

If the audible bell is disabled, core protocol Bell and input extension DeviceBell 
requests cause KBBellNotify events but they do not generate a sound. All non-XKB 
bell requests generate events with name and window None.

If the noExplicit field of some indicator map is True, attempts to change the state of 
that indicator using the core protocol or input extension requests are silently ignored.

Effects of XKB on Core Protocol Requests and Events

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 variations of the effective state are reported to XKB-aware clients depending 
on context:

o	The effective modifier state is the union of the base, latched and locked modifier states. 
It is reported in KBStateNotify events and in response to KBGetState requests.

o	The symbol lookup state is the effective modifier state minus the server internal modifi-
ers. It is reported to XKB-aware clients in the state field of core KeyPress and Key-
Release events that do not activate passive grabs.

o	The effective grab state is the symbol lookup state minus the intersection of the locked 
modifier state and the ignore locks modifiers. It is reported to XKB-aware clients in the 
state field of all core protocol events that report keyboard state, except KeyPress and 
KeyRelease events that do not activate passive grabs. The server uses the effective 
grab state to determine whether or not to activate passive grabs requested by an 
XKB-aware client.

o	The effective group is the sum of the base, latched and locked keyboard groups. An out 
of range effective group is wrapped or truncated into range according to the setting of 
groupsWrap for the keyboard. The effective group is reported to XKB-aware clients in 
the three reserved bits of the state field of core KeyPress and KeyRelease events.

The server reports compatibility states to any clients that have not issued a successful 
KBUseExtension 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 in the state field 
of core KeyPress and KeyRelease events that do not trigger grabs. The compatibil-
ity effective grab state is reported to non-XKB clients in the state field of all core pro-
tocol events except KeyPress and KeyRelease that do not activate passive grabs. 
The server uses the compatibility effective grab state to activate passive grabs 
requested by non-XKB clients.

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 as follows:

If the XKB keyboard description defines a single keyboard group, the generated core 
keyboard mapping has two keysyms-per-keycode, otherwise it has four. The first pair 
of symbols for each key lists the symbols in the first two positions of the first keyboard 
group. If two groups of symbols are defined for a key, the second pair contains the 
symbols in the first two positions of the second keyboard group, otherwise both have 
the value NoSymbol. If any key type has less than two levels, the second position 
within each group is reported as NoSymbol.

The generated modifier mapping for a key contains all of the modifiers affected by all 
of the actions associated with the key, remapped according to the modifier compatibil-
ity map. If any of the actions associated with a key affect the keyboard group state, any 
compatibility modifiers that can be affected by keyboard group 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 KBMapNotify to clients that have explicitly selected them and core protocol 
MappingNotify events to clients that have not. If a client selects KBMapNotify 
events, the server stops sending it MappingNotify events.

Section 4. Common Types

The request and event definitions in subsequent sections assume the common types 
defined by the core X protocol with the following changes and additions:

Name

Value

BITMASK

As in the specification of the core protocol, the types 
BITMASK and LISTofVALUE are used to allow the client to 
specify a subset of a heterogeneous collection of optional 
arguments. Unlike the core protocol, the length of a list 
element depends on context and might vary within a single 
LISTofVALUE.

CHANGEStoFOO

A type name of the form CHANGEStoFOO means a pair of 
masks which specify changes to a third mask; all three masks 
contain elements of type FOO. The first mask of a 
CHANGEStoFOO is called the effects mask, the second is 
called the values mask. The mask to be updated is called the 
destination mask. An argument of type CHANGEStoFOO is 
applied to a destination mask as follows: 

Any elements present in both the effects and values masks are 
added to the destination mask. Any elements present only in 
the effects mask are cleared from the destination mask. 
Elements that are not present in the effects mask are not 
changed in the destination map. If any elements are defined in 
the values mask but not the effects mask, the server generates 
a Match error.

The effects, values and destination masks must all be the same 
size, but depend on the type of their elements. The 
representation of the masks will typically contain more bits 
than there are defined arguments; the unused bits in all masks 
must be zero or the server generates a Value error.

KB_DEVICESPEC

8 bit unsigned integer or kbUseCoreKeyboard

KB_EVENTS

{	kbMapNotify, kbStateNotify, kbControlsNotify, 
kbIndicatorStateNotify, kbIndicatorMapNotify, 
kbNamesNotify, kbCompatMapNotify, 
kbAlternateSymsNotify, kbBellNotify, 
kbActionMessage, kbSlowKeyNotify }

KB_GROUP

{	0..7 }

KB_VIRTUALMOD

{	0..15 } or kbNoModifier

KB_INDICATOR

[ 0..31 } or kbNoIndicator

KB_GROUPINFO

{	groupsWrap: BOOL
numGroups: 0..8 }

KB_STATEMASK

KEYBUTMASK or SETofKB_GROUP

KB_MODMASK

{	mask: KEYMASK
realMods: KEYMASK
vmods: CARD16 }

KB_STATEPARTS

{	kbModifierState, kbModifierBase, kbModifierLatch, 
kbModifierLock, kbGroupState, kbGroupBase, 
kbGroupLatch, kbGroupLock, kbCompatMask }

KB_ACCESSX

{	kbRepeatKeys, kbSlowKeys, kbBounceKeys, 
kbStickyKeys, kbMouseKeys, kbMouseKeysAccel, 
kbAccessXKeys, kbAccessXTimeout, 
kbAccessXFeedback }

KB_CONTROLS

{	kbGroupsWrap, kbAudibleBell, kbAutoAutorepeat, 
kbServerInternalMods, kbIgnoreLockMods } or 
KB_ACCESSX

KB_SLOWKEYEV

{	kbSK_Press, kbSK_Accept, kbSK_Reject, 
kbSK_Release }

KB_MAPPARTS

{	kbTypes, kbKeySyms, kbKeyActions, kbKeyBehaviors, 
kbVirtualMods, kbExplicitComponents }

KB_COMPATPARTS

{	kbModCompat, kbVirtualModCompat, kbSymInterpret }

KB_NAMES

{	kbKeycodesName, kbGeometryName, kbSymbolsName, 
kbSemanticsName, kbKeyNames, kbKeyTypeNames, 
kbKTLevelNames, kbRGNames, kbIndicatorNames, 
kbPhysicalNames, kbModifierNames, 
kbVirtualModNames, kbCharSets }

KB_EXPLICIT

{	kbExplicitKeyType, kbExplicitInterpret, 
kbExplicitAutorepeat, kbExplicitBehavior }

KB_SIMATCH

{	NoneOf, AnyOfOrNone, AnyOf, AllOf, Exactly }

Section 5. Errors

The X Keyboard Extension defines a single error, Keyboard, which indicates that 
some request specified an illegal device identifier or an extension device that is not a 
member of KEYCLASS. Any request with an argument of type KB_DEVICESPEC 
can cause Keyboard errors if an illegal device is specified.

Section 6. Requests

E	KBUseExtension

wantedMajor, wantedMinor:	 CARD16

	
supported: BOOL
serverMajor, serverMinor: CARD16

I	

This request enables XKB extension capabilities for the client that issues the request; 
the wantedMajor and wantedMinor fields specify the extension version in use by the 
requesting client. The supported field is True if the server supports a compatible ver-
sion, False otherwise. The serverMajor and serverMinor fields return the actual ver-
sion supported by the server.

Until a client explicitly requests the XKB extension, an XKB capable server reports 
"compatibility state" in core protocol events and requests. Once a client asks for XKB 
extension semantics by issuing this request, the server reportss the extended XKB key-
board state in core protocol events and requests.

Clients must issue a KBUseExtension request before using any other extension 
requests.

E	KBSelectEvents

deviceSpec:	KB_DEVICESPEC
affectMap, map: CHANGEStoKB_MAPPARTS
affectWhich: SETofKB_EVENTS
clear: SETofKB_EVENTS
selectAll: SETofKB_EVENTS
masks: LISTofVALUE

Errors: Keyboard, Value

I	

This request updates the event masks of the keyboard indicated by deviceSpec for this 
client. The event mask for map components that are set in affectMap are set to the cor-
responding value from the map field. The affectWhich field specifies additional XKB 
event masks to be changed, clear specifies which of those event masks should be 
cleared and selectAll specifies those for which all possible details should be selected. 
The masks field contains changes to the details of any event masks that are specified in 
affectWhich but which do not appear in either of clear or selectAll.

The server sends a BadMatch error if any event types are present in clear or selectAll 
but not in affectWhich. 

Each entry in masks consists of an "affects" mask and a "values" mask whose size and 
legal contents are determined by the type of event for which they specify details. This 
table lists the type and size in bytes of the details masks for all XKB events:

Event Type

Size

Details Type

KBStateNotify

2

CHANGEStoKB_STATEPARTS

KBControlsNotify

4

CHANGEStoKB_CONTROLS

KBIndicatorNotify

4

CHANGEStoINDICATOR

KBIndicatorNotify

4

CHANGEStoINDICATOR

KBNamesNotify

2

CHANGEStoKB_NAMES

KBCompatMapNotify

1

CHANGEStoKB_COMPATMAP

KBAlternateSymNotify

1

CHANGEStoBOOL

KBBellNotify

1

CHANGEStoBOOL

KBActionMessage

1

CHANGEStoBOOL

KBSlowKeyNotify

1

CHANGEStoKB_SLOWKEYEV

For each entry in masks, the affects mask specifies which of the details are to be 
changed and the values mask specifies new values for the changed fields.

E	KBSendEvent

destination: WINDOW or PointerWindow or InputFocus
propagate: BOOL
synthesizeClick: BOOL
event-mask: SETofEVENT
event: <normal-event-format>

Errors: Value, Window

I	

The core SendEvent request does not interpret the events it sends; the KBSendEvent 
request modifies the state field of core protocol and input extension events that report 
state and optionally synthesizes a key click. The state field of any such request is 
assumed to be an XKB keyboard state, including a keyboard group specification. If the 
event is sent to an XKB-aware client, the state field is not changed; if the event is to be 
sent to a non-XKB client, the server applies the modifier compatibility mapping to the 
event state and group before sending the event.

The server causes an audible key click if all of the following conditions are met:

o	the synthesizeClick field is True

o	key click is enabled for the keyboard in question

o	the event is of type KeyPress or DeviceKeyPress

o	the server is able to generate a synthetic audible key click

If a server is unable to synthesize key clicks, it is free to ignore the synthesizeClick 
field.

Although it does modify the keyboard state as appropriate, the server does not apply 
keyboard controls, behavior or key actions to sent key events.

E	KBBell

deviceSpec: KB_DEVICESPEC
bellClass, bellID: CARD8
percent: INT8
override: BOOL
name: STRING8
window: WINDOW

Errors: Keyboard, Value

I	

If audible bells are enabled or override is True, this request sounds the bell specified 
by bellClass and bellID on the device specified by deviceSpec at the volume specified 
by percent. This request causes a KBBellNotify event which contains all of the 
information about the requested bell, including the otherwise uninterpreted symbolic 
name specified by name. KBBellNotify events are generated whether or not the bell 
was actually rung.

KBBellNotify events generated in response to core protocol or X input extension 
bell requests always report the empty string as their name and None as their window.

The bellClass, bellID, and percent fields are interpreted as for the X input extension 
DeviceBell request. The name must be a valid atom or None; window must be a 
valid window ID or None. If any are illegal, this request reports a Value error.

E	KBGetState

deviceSpec: KB_DEVICESPEC

	
deviceID: CARD8
mods, baseMods, latchedMods, lockedMods: KEYMASK
group, baseGroup, latchedGroup, lockedGroup: KB_GROUP
compatState: KEYMASK

Errors: Keyboard

I	

This request returns a detailed description of the current state of the keyboard speci-
fied by deviceSpec.

The deviceID return value contains the input extension identifier for the specified 
device, or 0 if the server does not support the input extension.

The baseMods return value reports the modifiers that are set because one or more 
modifier keys are logically down. The latchedMods and lockedMods return values 
report the modifiers that are latched or locked respectively. The mods return value 
reports the effective modifier mask which results from the current combination of 
base, latched and locked modifiers.

The baseGroup return value reports the group state selected by group shift keys that 
are logically down. The latchedGroup and lockedGroup return values detail the effects 
of latching or locking group shift keys and KBLatchLockState requests. The group 
return value reports the effective keyboard group which results from the current com-
bination of base, latched and locked group values.

The compatState return value reports the compatibility state that results from applying 
the compatibility modifier mapping to the effective keyboard group and modifier state.

E	KBLatchLockState

deviceSpec: KB_DEVICESPEC
affectModLocks, modLocks: CHANGEStoKEYMASK
affectGroupLock: BOOL
groupLock: KB_GROUP
affectModLatches,modLatches: CHANGEStoKEYMASK
affectGroupLatch: KB_GROUP
groupLatch: INT8

Errors: Keyboard, Value

I	

This request locks or latches keyboard modifiers and group state for the device speci-
fied by deviceSpec. 

The affectModLocks and modLocks masks are applied to the locked modifiers. If lock-
Group is True, the locked keyboard group is set to the group specified by groupLock.

The affectModLatches and modLatches change masks are applied to the latched state 
of the keyboard modifiers. If latchGroup is True, the latched keyboard group is set to 
the group specified by groupLatch.

If either group specification exceeds the maximum number of groups permitted for the 
specified keyboard, they are wrapped or truncated back into range as specified by the 
global groupsWrap flag. No error results from an out-of-range group specification.

After changing the locked and latched modifiers and groups as specified, the X server 
recalculates the effective and compatibility keyboard state and generates KBStateNo-
tify events as appropriate if any state components have changed. Changing the key-
board state might also change indicators which can cause KBIndicatorNotify 
events.

E	KBGetControls

deviceSpec: KB_DEVICESPEC

	
deviceID: CARD8
numGroups: CARD8
internalMods, ignoreLockMods: KB_MODMASK
enabledControls: SETofKB_CONTROLS
repeatDelay, repeatInterval: CARD16
slowKeysDelay,debounceDelay: CARD16
mouseKeysDelay, mouseKeysTimeToMax, mouseKeysInterval: CARD16
mouseKeysMaxSpeed, mouseKeysCurve: CARD16
mouseKeysDfltBtn: BUTTON
accessXTimeout: CARD16
accessXTimeoutMask: KB_ACCESSX

Errors: Keyboard

I	

This request returns the status of all controls for the keyboard specified by deviceSpec. 

On return, the deviceID specifies the identifier of the requested device or zero if the 
server does not support the input extension.

The numGroups return value reports the current number of groups defined for the key-
board. 

The internalMods and ignoreLockMods masks report the current value of the corre-
sponding special modifier masks. Like all elements of type KB_MODMASK, each 
contains a mask of real modifiers (of type KEYMASK), a mask of virtual modifiers 
(of type SETofVIRTUALMOD) and the effective set of modifiers which results from 
applying the current virtual modifier definitions to the virtual modifier mask and add-
ing the result tp the real modfier mask.

The enabledControls mask reports the global controls that are set. The repeatDelay, 
repeatInterval, slowKeysDelay and debounceDelay fields report the current values of 
the for the autorepeat delay, autorepeat interval, slow keys delay and bounce keys tim-
eout, respectively. All of these times are reported in milliseconds.

If mouse keys are active, pressing and holding a key which cases an SA_AccelPtr 
action causes core pointer events as follows:

The first motion event moves the pointer according to the deltas specified by the the 
activated action and is generated immediately. The mouseKeysDelay specifies the time 
in milliseconds between the first artificial pointer event and the second; the mouseKey-
sInterval specifies the time between all subsequent artificial pointer events until the 
key is released. The mouseKeysTimeToMax specifies the total number of repeated 
events before the pointer is travelling at its maximum speed (determined by multiply-
ing the mouseKeysMaxSpeed by the deltas specified by the SA_AccelPtr action). 
The mouseKeysCurve determines the rate at which the pointer delta goes from mini-
mum to maximum speed. The initial event always moves the pointer the minimum 
possible distance; after mouseKeysTimeToMax events, all events move the pointer the 
maximum distance. The delta for intermediate event n is:

If the the action delta is non-zero, the resulting delta must also be non-zero. If the 
action delta is positive, the result delta is rounded up, otherwise it is rounded down. 

This definition of mouse keys curve allows you to vary the mouse response: a curve of 
zero approximates a linear increase from minimum to maximum acceleration; increas-
ing the curve value causes longer periods of minimum or low acceleration followed by 
a rapid increase to maximum acceleration (behaving more like an absolute threshhold 
as curve increases).

The mouseKeysDfltBtn return value reports the pointer button for which events are 
synthesized by the mouse keys server actions by default.

The accessXTimeout return value reports the length of time, in seconds, that the key-
board must remain idle before the the server disables any controls specified in 
accessXMask. An accessXTimeout of 0 or empty accessXMask indicates that AccessX 
controls are not automatically deactivated.

E	KBSetControls

deviceSpec: KB_DEVICESPEC
affectInternalRealMods, internalRealMods: CHANGEStoKEYMASK
affectInternalVirtualMods, internalVirtualMods: CHANGEStoVIRTUALMOD
affectIgnoreLockRealMods, ignoreLockRealMods: CHANGEStoKEYMASK
affectIgnoreLockVirtualMods,ignoreLockVirtualMods: CHANGEStoVIRTUALMOD
affectEnabled, enabled: CHANGEStoKB_ACCESSX
changeControls: SETofKB_CONTROLS
repeatDelay, repeatInterval: CARD16
slowKeysDelay: CARD16
debounceDelay: CARD16
mouseKeysDelay, mouseKeysInterval: CARD16
mouseKeysMaxSpeed, mouseKeysTimeToMax, mouseKeysCurve: CARD16
mouseKeysDfltBtn: BUTTON
accessXTimeout: CARD16
accessXTimeoutMask: KB_ACCESSXMASK

Errors: Keyboard, Value

I	

This request changes keyboard controls for the keyboard specified by deviceSpec.

Controls specified in both affectEnabled and enabled are turned on; controls specfied 
in affectEnabled alone are turned off. Controls not specified in either are not changed. 
The server generates a Match error if any controls specified in enabled are not also 
present in affectEnabled.

Both the affectInternalRealMods and internalRealMods change masks and the 
affectInternalVirtualMods and internalVirtualMods change masks are applied to the 
internal modifiers of the keyboard. If either mask changes, the server recomputes the 
effective internal modifier mask.

The affectIgnoreLockRealMods, ignoreLockRealMods, affectIgnoreLockVirtualMods 
and ignoreLockVirtualMods change masks are applied to the ignore locks modifiers of 
the keyboard. If either mask changes, the server recomputes the effective ignore locks 
mask.

The changeControls field specifies which of the other request fields should be used to 
change the values of the corresponding keyboard controls. This table lists the controls 
that can be included in changeControls and the fields they affect:

Control

Fields

RepeatKeys

repeatDelay, repeatInterval

SlowKeys

slowKeysDelay

BounceKeys

debounceDelay

MouseKeys

mouseKeysDfltBtn

MouseKeysAccel

mouseKeysDelay, mouseKeysInterval, mouseKeysMaxSpeed, 
mouseKeysTimeToMax, mouseKeysCurve

AccessXTimeout

accessXTimeout, accessXTimeoutMask

This request can cause KBControlsNotify events.

E	KBGetMap

deviceSpec: KB_DEVICESPEC
full, partial: SETofKB_MAPPARTS
firstType, nTypes: CARD8
firstKeySym, nKeySyms: KEYCODE
firstKeyAction, nKeyActions: KEYCODE
firstKeyBehavior, nKeyBehaviors: KEYCODE
virtualMods: SETofVIRTUALMOD
firstKeyExplicit, nKeyExplicit: KEYCODE

	
deviceID: CARD8
minKeyCode, maxKeyCode: KEYCODE
totalKeyTypes: CARD8
valueMask: BITMASK
valueList: LISTofVALUE
Errors: Keyboard, Value, Match, Alloc

I	

This request returns the indicated components of the server and client maps of the key-
board specified by deviceSpec. The full mask specifies the map components to be 
returned in full; the partial mask specifies the components for which some subset of 
the legal elements are to be returned. The server returns a Match error if any compo-
nent is specified in both full and partial.

If some counted map component is specified in partial, the corresponding firstElement 
and nElements fields must specify legal elements:

Partial Value

Minimum First

Maximum Number

kbTypes

0

nKeyTypes-firstKeyType

kbKeySymMaps

minKeyCode

maxKeyCode-firstKeySymMap+1

kbKeyActions

minKeyCode

maxKeyCode-firstKeyAction+1

kbKeyBehaviors

minKeyCode

maxKeyCode-firstKeyBehavior+1

kbExplicitComponents

minKeyCode

maxKeyCode=firstKeyExplicit+1

The nKeyTypes, minKeyCode and maxKeyCode values are taken from the keyboard 
description, the firstElement values are taken from the request. Requesting part of a 
component and specifying elements outside of these legal ranges causes a Value 
error. The firstElement and nElements fields of any component not specified in partial 
are ignored.

The first and length specifications for any component specified in the full mask are 
taken to be the minimum and maximum legal values, respectively. For example, if the 
full mask contains KBKeySymMaps, this request returns maxKeyCode-minKey-
Code+1 key symbol mappings starting from element minKeyCode.

The virtualMods field specifies the virtual modifiers for which bindings should be 
returned.

On successful return, the deviceID field returns the input extension identifier of the 
specified device or zero if the server does not support the input extension. The min-
KeyCode and maxKeyCode return values report the minimum and maximum legal 
keycodes for the specified device.

The valueMask and valueList fields specify the client components for which some ele-
ments are being returned.

Component

Type

kbTypes

LISTofKB_KEYTYPE

kbKeySymMaps

LISTofKB_KEYSYMMAP

kbKeyActions

LISTofLISTofKB_ACTION

kbKeyBehaviors

LISTofKB_BEHAVIOR_VALUE
where
KB_BEHAVIOR_VALUE		{	key: KEYCODE,
			behavior: KB_BEHAVIOR }

kbVirtualMods

LISTofKB_VMOD_VALUE
where:
KB_VMOD_VALUE		{	vmod: KB_VIRTUALMOD,
			mod: KB_MODIFIER }

kbExplicitComponents

LISTofKB_EXPLICIT_VALUE
where
KB_EXPLICIT_VALUE		{	key: KEYCODE,
			explicit: SETofKB_EXPLICIT }

The lists of key types, symbols maps and actions return all elements in the requested 
range. The listsof key behaviors, virtual mods and explicit components report only 
those elements in the requested range that have "unusual" values. The "usual" keyb 
behavior has type KB_Default. Virtual modifiers are usually not bound to a modifi-
ers and a keys usually have no explicit components.

The totalKeyTypes return value reports the total number of key types defined for the 
keyboard in question.

E	KBSetMap

deviceSpec: KB_DEVICESPEC
resize: { kbKeyTypes }
virtualMods: SETofKB_VIRTUALMOD
valueMask: KB_MAPMASK
valueList: LISTofVALUE

Errors: Keyboard, Value, Match, Alloc

I	

This request changes the indicated parts of the keyboard specified by deviceSpec. The 
effect of a key release is independent of the keyboard mapping at the time of the 
release, so this request succeeds regardless of the logical state of the modifier keys.

The valueMask and valueList fields specify the keyboard map components to be 
changed: The values and types are the same as for kbGetMap. Each element of val-
ueList replaces a subset of one of the components of the keyboard map. The indices of 
all elements of kbKeySymMaps, kbKeyActions, kbKeyBehaviors and kbEx-
plicitComponents to be changed must be in the range of legal keycodes for the 
device in question or a Value error results.

If kbKeyTypes is set in the resize field, the server resizes the list of key types so that 
the last key type specified by this request is the last element in the list. An attempt to 
enlarge the list of key types causes a Value error unless the appropriate bit of the 
resize field is set.

The index of the first changed key type must be less than or equal to the unmodified 
length of the list of key types or a Value error results. The keyboard map that would 
result from applying this request must contain only legal values and must be internally 
consistent, or an error results.

For each result key type:

o	Group width must be greater than zero or a Value error results.

o	All map elements must be less than the group width or a Match error results.

o	All elements of the preserve map must include only modifiers that also in the mask of 
the key type, or a Match error results.

o	If the key type name is ONE_LEVEL, group width must be one (else a Match error).

o	If the key type name is TWO_LEVEL or KEYPAD, group width must be two or a 
Match error results.

For each key in the result key symbol map:

o	The key type index must specify a legal result key type or a Match error results.

o	The number of groups must be in the range 0..8 or a Value error results.

o	The number of symbols must equal the number of groups times the groupWidth of the 
result key type or a Match error results.

For each key in the result key actions:

o	The key must have no actions or the number of actions must equal the number of sym-
bols assigned to the key or a Match error results.

o	All actions assigned to a key must be legal or a Value error results. All private actions 
are legal; servers should treat any unknown private actions as SA_NoAction.

The specified behavior of each resulting key behavior must be legal or a Value error 
results. All private behaviors are legal; servers should treat any unknown private 
behavior as KB_Default.

Each resulting virtual modifier must be bound to a legal real modifier or have the 
value kbNoModifier or a Value error results.

All of the unused bits of any resulting set of explicit components for a key must be 
zero or a Value error results.

If the resulting keyboard map is legal, the server updates the keyboard map. Changes 
to some keyboard components have indirect effects on others:

If the group width of an existing key type is changed, the list of symbols associated 
with any keys of the changed type is resized accordingly. If the list increases in size, 
any unspecified new symbols are initialized to NoSymbol.

If the list of actions associated with a key is not empty, changing the key type of the 
key resizes the list. Unspecified new actions are usually calculated by applying any 
keyboard symbol interpretations to the corresponding symbols. If the explicit compo-
nents map of some key whose type has changed size contains kbExplicitInter-
pret, the new actions are initialized to SA_NoAction instead.

The number of groups global to the keyboard is always equal to the largest number of 
groups specified by any of the key symbol maps. Changing the number of groups in 
one or more key symbol maps may change the number of groups global to the key-
board.

Changing a key behavior from KB_Lock to some other behavior causes a synthetic 
KeyRelease event if the key is logically but not physically down at the time of the 
change.

Symbolic names for newly created key types or levels within a key type are initialized 
to None.

This request sends a kbMapNotify event which reflects both explicit and indirect 
map changes to any interested clients. If any symbolic names are changed, it sends a 
kbNamesNotify reflecting the changes to any interested clients. XKB-unaware cli-
ents are notified of keyboard changes via core protocol MappingNotify events.

Artificial KeyPress and KeyRelease events caused by changing key behavior may 
cause KeyPress, KeyRelease, DeviceKeyPress, DeviceKeyRelease, 
kbStateNotify or kbIndicatorNotify events.

E	KBGetCompatMap

deviceSpec: KB_DEVICESPEC
getAllSI: BOOL
firstSI, nSI: CARD16
mods: KEYMASK
vmods: SETofVIRTUALMOD

	
deviceID: CARD8
totalSI: CARD16
siRtrn: LISTofKB_SYMINTERPRET
modsRtrn: LISTofKB_MODCOMPATMAP
vmodsRtrn: LISTofMODCOMPATMAP

where:
KB_SYMINTERPRET:	[	levelOneOnly: BOOL,
		match: KB_SIMATCH,
		mods: KEYMASK,
		sym: KEYSYM,
		action: KB_ACTION,
		virtualMod: KB_VIRTUALMOD,
		autorepeat: BOOL,
		locking: BOOL ]
KB_MODCOMPATMAP:	[	mods: KEYMASK,
		groups: SETofKB_GROUP ]
		

Errors: Keyboard, Match, Alloc

I	

This request returns the listed compatibility map components for the keyboard speci-
fied by deviceSpec. 

If getAllSI is False, firstSI and nSI specify the subset of the symbol interpretations to 
be returned; nSI must be greater than 0 and all of the elements specified by firstSI and 
nSI must be defined or a Value error results. If getAllSI is True, the server ignores 
firstSI and nSI and returns all of the symbol interpretations defined for the keyboard.

The mods mask specifies the modifiers for which compatibility maps are to be 
returned. If any modifier is set in mods, the corresponding modifier compatibility map 
is returned.

The vmods mask specifies the virtual modifiers for which compatibility maps are to be 
returned. This request returns modifier compatibility maps for any virtual modifiers 
specified in vmods.

On return, deviceID reports the input extension identifier of the keyboard device or 0 if 
the server does not support the input extension. The totalSI return value reports the 
total number of symbol interpretations defined for the keyboard, even if the request 
returns only a subset of them.

The symsRtrn, modsRtrn and vmodsRtrn return values contain the definitions of 
the requested symbol interpretations and modifier compatibility maps. The modsRtrn 
and vmodsRtrn fields report only "unusual" modifier compatibility maps.

The usual modifier compatibility map for a real modifier matches itself only; it does 
not match any groups or any other modifiers. The usual modifier compatibility map 
for a virtual modifier matches no groups or modifiers.

E	KBSetCompatMap

deviceSpec: KB_DEVICESPEC
recomputeXKBActions: BOOL
truncateSI: BOOL
si: LISTofKB_SYMINTERPRET
mods: LISTofKB_MODCOMPATMAP
vmods: LISTofKB_MODCOMPATMAP

where:
KB_SYMINTERPRET:	<as specified for KBGetCompatMap>
KB_MODCOMPATMAP:	<as specified for KBGetCompatMap>

Errors: Keyboard, Match, Value, Alloc

I	

This request changes a specified subset of the compatibility map of the keyboard indi-
cated by deviceSpec. The si, mods and vmods fields contain new definitions for subsets 
of the symbol interpretatations, real and virtual modifier compatibility mappings.

The index of the first symbol interpretation changed by this request must be less than 
or equal to the unchanged length of the existing list or a Value error results. All 
changed symbol interpretations must specify legal actions or a Value error results.

If the index of the last symbol interpretation changed by this request is greater than or 
equal to the former length of the list the list of symbol interpretations is increased in 
size automatically. Otherwise, if truncateSyms is True, the server truncates its list of 
symbol interpretations after the last element changed by this request..

If the recomputeXKBActions field is True, the server regenerates the XKB keyboard 
map by applying the new symbol interpretations to the XKB key symbol map.

This request causes kbCompatNotify events. If recomputeActions is specified, this 
request can also cause kbMapNotify or MappingNotify events.

E	KBGetIndicatorState

deviceSpec: KB_DEVICESPEC

	
state: SETofKB_INDICATOR

Errors: Keyboard

I	

This request reports the current state of all indicators for the keyboard specified by 
deviceSpec. The least-significant bit of the state return value corresponds to indicator 
0, the most significant bit to indicator 31; if a bit is set, the corresponding indicator is 
lit.

E	KBGetIndicatorMap

deviceSpec: KB_DEVICESPEC
which: SETofKB_INDICATOR

	
deviceID: CARD8
nRealIndicators:	CARD8
maps: LISTofKB_INDICATORMAP

where:

KB_INDICATORMAP:	[	noAutomatic: BOOL,
		noExplicit: BOOL,
		whichGroups: KB_IMPARTS,
		groups: SETofKB_GROUP,
		whichMods: KB_IMPARTS,
		mods: KB_MODMASK,
		ctrls: SETofKB_ACCESSX ]

Errors: Keyboard, Value

I	

This request returns a subset of the indicator maps of the keyboard specified by 
deviceSpec. The which field specifies the subset to be returned; each bit set in which 
indicates that the map for the corresponding indicator should be returned.

On a successful return, the deviceID field reports the input extension identifier of the 
keyboard or 0 if the server does not support the input extension. The first nRealIndica-
tors indicators correspond to indicators actually present on the keyboard, the rest are 
virtual indicators. Virtual indicators do not directly cause any visible or audible effect 
when they change state, but they do cause kbIndicatorNotify events.

The maps return value reports the requested indicator maps. Each indicator map speci-
fies controls, modifier and group combinations that change the state of the correspond-
ing indicator. The whichGroups and whichMods masks specifies the keyboard state 
components to be considered for groups and modifiers respectively.

If the noExplicit field of an indicator map is True, attempts to change the indicator 
state using core protocol requests are ignored. If keyboard state changes and the noAu-
tomatic field of an indicator map is False, the indicator state is determined as fol-
lows:

The groups mask specifies the groups that affect the indicator; if the bit of groups 
which corresponds to the current keyboard group specified by whichGroups is set, the 
indicator is lit. The mods mask specifies the real, virtual and effective modifiers that 
control the corresponding indicator; if any of the modifiers present in the effective 
modifier mask are also set in the keyboard state mask specified by whichMods, the 
indicator is lit. The ctrls mask specifies the keyboard controls whose enabled state 
affects the indicator; if any of the controls specified in ctrls are enabled, the indicator 
is lit. If none of mods, groups or ctrls match the current keyboard state, the indicator is 
set to the state explicitly requested by a client (if any) or is turned off if noExplicit is 
True.

The server generates a KBIndicatorNotify whenever any indicator changes state.

E	KBSetIndicatorMap

deviceSpec: KB_DEVICESPEC
which: SETofKB_INDICATOR
maps: LISTofKB_INDICATORMAP

where:

KB_INDICATORMAP:	<as specified for KBGetIndicatorMap>

Errors: Keyboard, Value

I	

This request changes a subset of the indicator map of keyboard specified by device-
Spec. The which field specifies the indicator maps to be changed; the maps field con-
tains the new definitions. The whichGroups and whichMods fields of all new indicator 
maps must specify only legal state components or a Value error results. The ctrls field 
of all new indicator maps must specify only legal controls or a Value error results.

The real and virtual modifiers specified by the mods field of any new indicator maps 
are used, but the effective mask is ignored; the server always calculates a correct effec-
tive mask based on the virtual modifier bindings in effect at the time of the request.

If successful, the new indicator maps are applied immediately and the server generates 
an kbIndicatorMapNotify event. If any indicators change state as a result of the 
new maps, the server generates kbIndicatorStateotify events as appropriate.

E	KBGetNames

deviceSpec: KB_DEVICESPEC
which: SETofKB_NAMES

	
deviceID: CARD8
present: SETofKB_NAMES
nTypeRtrn: CARD8
valueMask: BITMASK
valueList: LISTofVALUE

Errors: Keyboard, Value

I	

This request returns the symbolic names for various components of the keyboard map-
ping for the device specified by deviceSpec. The which field specifies the keyboard 
components for which names are to be returned.

The deviceID return value contains the X Input Extension device identifier of the spec-
ified device or 0 if the server does not support the input extension. The valueMask and 
valueList return values specify the components for which names are being reported.

Component

Type

kbKeycodesName 

ATOM

kbGeometryName 

ATOM

kbSymbolsName 

ATOM

kbSemanticsName

ATOM

kbKeyTypeNames 

LISTofATOM

kbKTLevelNames 

LISTofLISTofATOM

kbIndicatorNames 

LISTofATOM

kbModifierNames 

LISTofATOM

kbKeyNames

LISTofKB_KEYNAME

kbRGNames

LISTofATOM

kbVirtualModNames

LISTofATOM

kbCharSets 

LISTofATOM

kbPhysicalNames

LISTofATOM

The nKeyTypesRtrn field indicates the total number of key types defined for the key-
board. The returned names, if any, for key types and key type levels have nKeyTypes-
Rtrn elements. Each element of the list of key type level names is a list of ATOMs 
with as many elements as the corresponding key type has shift levels.

Values for most names are returned only if they are defined (i.e. are not None). The 
only exceptions are kbKTLevelNames and kbKeyNames. If any of the levels in a key 
type have a valid name, names are returned for all levels; even those whose name is 
None. Even if none of the levels in a key type have a valid name, the valueList con-
tains an entry for the key type (which consists of a length 0 list of ATOMs). If key 
names are requested and any keys have non-zero names (any of the four bytes in the 
name are non-zero), the server returns the names of all keyboard keys.

E	KBSetNames

deviceSpec: KB_DEVICESPEC

valueMask: BITMASK
valueList: LISTofVALUE

Errors: Keyboard, Atom, Value, Match, Alloc

I	

This request changes the symbolic names for the requested components of the key-
board specified by deviceSpec. All new name definitions of type ATOM must be legal 
atoms or None, or the server sends an Atom error.

The valueMask and valueList fields specify the components to be changed; value and 
type are as specified for the kbGetNames request. If kbKTLevelNames is set in val-
ueMask, the largest element in the list of key type level names must be less than the 
number of key types defined for the keyboard or a Value error results. The number of 
level names defined by each entry in levelNames must exactly match the groupWidth 
of the corresponding key type or a Match error occurs.

The first three key types for any keyboard must have the names ONE_LEVEL, 
TWO_LEVEL and KEYPAD, respectively and no other type may have one of these 
names. Attemps to assign names otherwise cause a Value error.

This request can cause kbNamesNotify events.

E	KBListAlternateSyms

deviceSpec: KB_DEVICESPEC
name: ATOM or None
charset: ATOM or None

	
deviceID: CARD8
nAlternateSyms: CARD8
altSymSets: LISTofKB_ALTSYMINFO

where:
KB_ALTSYMINFO:	[	id: CARD8,
		name: ATOM,
		charSets: LISTofATOM ]

Errors: Keyboard, Atom

I	

This request reports the names of the alternate symbol sets defined for the keyboard 
specified by deviceSpec. The name and charset fields may be combined to select alter-
nate symbols appropriate for a specific application or locale. If the name field has a 
value other than None, only alternate symbol sets whose names match are returned. If 
the charset field is not None, only alternate symbol sets whose list of character sets 
contains a matching entry are returned. If either field contains anything but None or a 
legal atom, an Atom error results. 

The deviceID reports the input extension id of the keyboard or 0 if the server does not 
support the input extension. The nAlternateSyms return value reports the number of 
alternate symbol sets that match the name and character set. If any matching alternate 
symbol sets are found, the altSymSets return value reports the id, name and complete 
list of charSets for the matching symbol sets. The id is used to read an alternate symbol 
set from the server.

E	KBGetAlternateSyms

deviceSpec: KB_DEVICESPEC
id: CARD8
firstKey, nKeys: CARD8

	
deviceID: CARD8
id: CARD8
name: ATOM
charSets: LISTofATOM
totalSyms: CARD16
altSyms: LISTofKB_KEYSYMMAP

Errors: Keyboard, Value, Alloc

I	

This request returns a description of one alternate symbol set from the keyboard speci-
fied by deviceSpec. The id field specifies the alternate symbol map to be returned and 
must specify a legal alternate symbol map or a Value error results. The firstKey and 
nKeys fields specify the subset of the alternate symbol map to be returned as a range 
of KEYCODEs; both firstKey and firstKey+nKeys-1 must be in the legal range 
of keycodes for the keyboard in question or a Value error results.

On successful return, the deviceID field reports the input extension identifier of the 
keyboard device or 0 if the server does not support the input extension. The id return 
value reports the index of the alternate symbol map being returned. The name and 
charSets return values report the symbolic name and list of supported character sets 
for the requested alternate symbol map respectively.

The altSyms return value contains the alternate symbol definitions for the requested 
keys. If any entry in altSyms defines more than one group, clients should use the key 
type, number of groups and symbols defined by the entry. Otherwise, the entry is 
ignored and clients should use the corresponding key symbol map from the default 
keyboard definition.

Note	Alternate key symbol maps are used only by clients; the key action to be applied is 
determined using the key symbol map from the default keyboard definition. Assigning 
alternate symbol maps to keys that initiate some action is not recommended.

E	KBSetAlternateSyms

deviceSpec: KB_DEVICESPEC
create: BOOL
replace: CARD8
present: { KB_ASName, KB_ASCharSets, KB_ASKeys }
name: ATOM or None
charSets: LISTofATOM
keys: LISTofKB_SETALTSYMMAP

where:
KB_SETALTSYMMAP:	[	change, defined: BOOL,
		map: KB_KEYSYMMAP ]

Errors: Keyboard, Value, Atom

I	

This request creates or changes an alternate symbol set defined for the keyboard spec-
ified by deviceSpec. If create is True, this request creates a new alternate symbol map 
with the specified definition; otherwise, it replaces the listed components of the exist-
ing alternate symbol map specified by replace. A Value error results if create is True 
and replace does not specify an existing alternate symbol map.

If KB_ASName is set in present, the name field specifies a name for the alternate sym-
bol map. If specified, name must be a valid ATOM or None or an Atom error results.

If KB_ASCharSets is set in present, the charSets field specifies a list of supported 
character sets for the alternate symbol set. An Atom error results if any element of 
charSets is not a valid ATOM or None. If create is False, this request replaces the 
previous list of supported character sets.

If KB_ASKeys is set in present, keys specifies new definitions for a range of keys in 
the alternate symbol set. If the change field of any element of keys is True, the corre-
sponding key symbol map from the alternate symbol set is changed to reflect the val-
ues specified by defined and map.

E	KBGetGeometry

deviceSpec: KB_DEVICESPEC

	
supported: BOOL
deviceID: CARD8
minKeyCode, maxKeyCode: CARD8
name: ATOM
<UNDER CONSTRUCTION>
Errors: Keyboard

I	

This request returns a description of the physical layout of the keyboard specified by 
deviceSpec. The deviceID field reports the input extension device ID or 0 if the server 
does not support the input extension. The name field reports the symbolic name for the 
keyboard geometry (identical to the geometry name reported by the KBGetNames 
request). The minKeyCode and maxKeyCode fields report the range of legal keycodes 
supported by the device.

If supported is False, the server does not have a description of the keyboard layout 
and returns only the device id, symbolic name and range of keycodes.

E	KBSetGeometry

deviceSpec: KB_DEVICESPEC
name: ATOM
<UNDER CONSTRUCTION>
Errors: Keyboard, Atom, Value

I	

This request changes the reported description of the geometry for the keyboard speci-
fied by deviceSpec. The name field must specify a valid ATOM or have the value 
None or an Atom error results. 

Section 7. Events

E	KBStateNotify

time: TIMESTAMP
deviceID: CARD8
mods, baseMods, latchedMods, lockedMods: KEYMASK
compatState: KEYMASK
group, baseGroup, latchedGroup, lockedGroup: CARD8
keycode: CARD8
eventType: CARD8
requestMajor, requestMinor: CARD8
changed: KB_STATEPARTMASK

I	

This event is generated whenever any component of a keyboard state changes. The 
deviceID specifies the keyboard for which state changed and the changed mask speci-
fies the components that have changed. The mods, baseMods, latchedMods and 
lockedMods fields report the current state of all modifier components of the keyboard 
state. The group, baseGroup, latchedGroup, and lockedGroup report the current val-
ues of all group components of the keyboard state. The compatState field reports the 
current value of the effective compatibility state, which is computed by applying the 
keyboard modifier mapping to the XKB effective state and group.

If the keyboard state changed because due to a key event, the keycode field reports the 
key that changed and the eventType field reports the type of the event that caused the 
state change.

If the keyboard state changed due to a request, the keycode field is 0 and the request-
Major and requestMinor fields report the request that caused the state change.

KBStateNotify events are reported only to clients that specifically request them. 
Using the KBSelectEvents request, clients can express interest in changes in spe-
cific state components.

E	KBMapNotify

time: TIMESTAMP
deviceID: CARD8
changed, resize: SETofKB_MAPPARTS
firstType, nTypes: CARD8
firstKeySym, nKeySyms: KEYCODE
firstKeyAction, nKeyActions: KEYCODE
firstKeyBehavior, nKeyBehaviors: KEYCODE
firstKeyExplicit, nKeyExplicit: KEYCODE
virtualMods: SETofKB_VIRTUALMOD

I	

This event is generated whenever some aspect of the keyboard map is changed by an 
XKB or core protocol request. The deviceID specifies the keyboard for which some 
component changed and the present mask specifies the changed components.

Each firstElement and nElements pair specifies the elements that have changed in the 
corresponding keyboard component. If the last element of any resizable map compo-
nent is one of the changed element, the corresponding bit is set in the resize mask of 
this event.

The virtualMods return value reports virtual modifiers with changed bindings.

By default, KBMapNotify events are reported to all clients that have issued a KBUse-
Extension request whenever the key types or key symbol maps changed. Changes in 
other map components are reported only to clients that explicitly request them.

E	KBControlsNotify

time: TIMESTAMP
deviceID: CARD8
changedCtrls: SETofKB_CONTROLS
enabledCtrls, enabledCtrlChanges: SETofKB_ACCESSX

I	

This event is generated whenever any of the keyboard controls are changed by an 
XKB or core protocol request, by the AccessX key sequences or by a key action. The 
deviceID field reports the keyboard for which some control changed. The changedC-
trls field reports controls for which some configuration value changed (e.g. if autore-
peat delay and interval are change, changedCtrls include kbRepeatKeys). The 
enabledCtrlChanges field reports all controls that were turned on or off and enabledC-
trls reports the current state of all controls.

This event is not reported by default; clients may express interest in changes to indi-
vidual controls using the KBSelectEvents request.

E	KBIndicatorStateNotify

time: TIMESTAMP
deviceID: CARD8
stateChanged, state: SETofKB_INDICATOR
mapChanged: SETofKB_INDICATOR

I	

This event is generated whenever any physical or virtual indicator changes state. The 
deviceID field specifies the device on which the change occurred.

The stateChanged field lists any indicators whose state have changed; the state field 
reports the current state of all thirty-two keyboard indicators. If any indicator maps 
have also changed, the mapChanged field reports them.

This event is not reported by default. Clients may express interest in changes in the 
state of individual indicators using the KBSelectEvents request.

E	KBIndicatorMapNotify

time: TIMESTAMP
deviceID: CARD8
stateChanged, state: SETofKB_INDICATOR
mapChanged: SETofKB_INDICATOR

I	

This event is generated whenever any some client changes the mapping of one or more 
indicators. The deviceID field specifies the device on which the change occurred.

The mapChanged field lists any indicators whose map has changed. The state field 
reports the current state of all keyboard indicators.

If any indicators have changed state, the stateChanged field reports them.

This event is not reported by default. Clients may express interest in changes in the 
mapping of individual indicators using the KBSelectEvents request.



E	KBBellNotify

time: TIMESTAMP
deviceID: CARD8
bellClass, bellID: CARD8
percent: CARD8
pitch: CARD16
duration: CARD16
name: ATOM
window: WINDOW

I	

This event is generated when some client issues a Bell, DeviceBell, or KBBell 
request. The deviceID field reports the keyboard for which a bell was requested the 
bellClass and bellID fields specify the input extension class and identifier of the feed-
back for which the bell was requested. If the reporting server does not support the 
input extension, both bellClass and bellID are 0.

The percent, pitch and duration fields report the volume, tone and duration requested 
for the bell as specified by the core protocol and input extension.

If the client used the KBBell request, the name field contains a symbolic name for the 
bell and the window field indicates the window for which the bell was generated. 
Either field has the value None if the client used a core protocol or input extension 
request or if the client did not supply a name or window.

This event is reported only to clients that specifically request it. Whether or not this 
event is reported is independent of audible bell keyboard control; KBBellNotify 
events can be reported even if an audible bell is also sounded.

E	KBSlowKeyNotify

time: TIMESTAMP
deviceID: CARD8
slowKeyState: SETofKB_SLOWKEYEV
keycode: KEYCODE
delay: CARD16

I	

This event is generated whenever a key changes state or the slow keys timer expires 
while the slow keys control is enabled. The deviceID specifies the keyboard on which 
the event occurred. The keycode specifies the key for which the event occurred and the 
delay field reports the current slow keys delay for the keyboard in question. The type 
field describes the event that occurred and has one of the following values:

Value

Meaning

kbSK_Press

The user pressed the key specified by keycode.

kbSK_Accept

The slow keys timer expired and the key was accepted

kbSK_Reject

The user released the key before the timer expired.

kbSK_Release

The user released the key after the timer expired.

This event is reported only to clients that specifically request it. Clients can request 
notification of any combination of press, acceptance, rejection and release using the 
KBSelectEvents request.

E	KBNamesNotify

time: TIMESTAMP
deviceID: CARD8
changed: KB_NAMESMASK
firstType, nTypes: CARD8
firstLevelName, nLevelNames: CARD8
firstRadioGroup, nRadioGroups: CARD8
changedMods: KEYMASK
changedVirtualMods: SETofKB_VIRTUALMOD
changedIndicators: SETofKB_INDICATOR
firstCharSet, nCharSets: CARD8

I	

This event is generated whenever the symbolic names for any components of the key-
board specified by deviceID change. Symbolic names can change when:

o	Some client explicitly changes them using KBSetNames.

o	The list of key types is resized 

o	The group width of some key type is changed

The changed mask lists the components for which some elements have changed. The 
various firstElement and nElements fields specify the subset of the corresponding 
components for which names were changed. If the name of the last element of any 
resizable component was changed, the corresponding bit of the resize mask is set.

This request is not reported by default. Clients can request notification of changes to 
the name of individual keyboard components with the KBSelectEvents request.

E	KBCompatMapNotify

time: TIMESTAMP
deviceID: CARD8
changedMods: KEYMASK
changedVMods: SETofKB_VIRTUALMOD
firstSI, nSI: CARD16
nTotalSI: CARD16

I	

This event is generated whenever some client changes the compatibility map of the 
keyboard specified by deviceID using the KBSetCompatMap request. The changed-
Mods mask reports any changed compatibility maps for real modifiers; changedV-
Mods reports changed maps for virtual modifiers. The firstSI and nSI fields report a 
range of changed symbol interpretations. The nTotalSI field reports the total number 
of symbol interpretations defined for the keyboard.

This request is not reported by default. Clients can request notification of changes to 
any compatibility map component using KBSelectEvents.

E	KBAlternateSymsNotify

time: TIMESTAMP
deviceID: CARD8
setDeleted: BOOL
newSet: BOOL
altSymsID: CARD8
firstKey, nKeys: CARD8

I	

This event is generated whenever some client creates, destroys or changes an alternate 
symbol set for the keyboard specified by deviceID. If the setDeleted field is True, the 
set specified by altSymsID was removed by some client. Otherwise, the firstKey and 
nKeys fields specify the range of keys that were changed in the alternate symbol set. If 
newSet is True, the set was created and all keys outside of the range specified by first-
Key and nKeys are taken from the default keyboard layout.

E	KBActionMessage

time: TIMESTAMP
deviceID: CARD8
keycode: KEYCODE
press: BOOL
keyEventFollows: BOOL
message: LISTofCARD8

I	

This event can be generated when a key event activates an SA_ActionMessage 
action; the exact circumstances under which an action causes an event depend on the 
arguments to the action and the arguments to the action. See the definition of the 
SA_ActionMessage on page 16 for more details.

The deviceID field reports the keyboard from which the event was generated and the 
keycode field reports the key that caused the event. If this event was generated due to a 
key press, the press field is True. 

If keyEventFollows is True, the server also generated the core protocol key or input 
extension device key event which the key transition that caused this event; if 
keyEventFollows is False, the SA_ActionMessage suppressed the corresponding 
key or device key event. Unsuppressed key events are sent according to the standard 
core protocol or input extension focus rules, so there is no guarantee that a client 
which receives a KBActionMessage will also receive the corresponding key event. 
The XKB extension guarantees only that action message events will precede the corre-
sponding key events and that the two events will have identical time stamps and 
sequence numbers.

The message field contains up to six bytes of data reported by the SA_ActionMes-
sage; XKB does not interpret the message in any way.

Appendix A. Protocol Encoding

Not ready yet.

Appendix B. Default Symbol Transformations

Control Modifier

This table lists the decimal value of the standard control characters that correspond to 
some keysyms for ASCII characters. Control characters for symbols not listed in this 
table are application-specific.

Keysyms

Value

Keysyms

Value

Keysyms

Value

Keysyms

Value

atsign

0

h, H

8

p, P

16

x, X

24

a, A

1

i, I

9

q, Q

17

y, Y

25

b, B

2

j, J

10

r, R

18

z, Z

26

c, C

3

k, K

11

s, S

19

left_bracket

27

d, D

4

l, L

12

t, T

20

backslash

28

e, E

5

m, M

13

u, U

21

right_bracket

29

f, F

6

n, N

14

v, V

22

asciicircum

30

g, G

8

o, O

15

w, W

23

underbar

31

Locale-Insensitive Capitalization

List the default capitalization rules, basically codify the table in Xlib today. Necessary 
so the C locale isn't too stupid.

Appendix C. Canonical Key Types

Describe ONE_LEVEL, TWO_LEVEL and KEYPAD key types.

Appendix D. New KeySyms

Byte

Byte

Code

Character

Name

ISO LOCK

ISO LATCHING LEVEL TWO SHIFT

ISO LEVEL THREE SHIFT

ISO LATCHING LEVEL THREE SHIFT

ISO LEVEL THREE SHIFT LOCK

ISO GROUP SHIFT

ISO GROUP SHIFT LOCK

ISO LATCHING GROUP SHIFT

ISO NEXT GROUP

ISO PREVIOUS GROUP

ISO FIRST GROUP

ISO LAST GROUP

MOUSE LEFT

MOUSE RIGHT

MOUSE UP

MOUSE DOWN

DEFAULT MOUSE BUTTON

MOUSE BUTTON ONE

MOUSE BUTTON TWO

MOUSE BUTTON THREE

MOUSE BUTTON FOUR

MOUSE BUTTON FIVE

DEFAULT MOUSE BUTTON DOUBLE CLICK

MOUSE BUTTON ONE DOUBLE CLICK

MOUSE BUTTON TWO DOUBLE CLICK

MOUSE BUTTON THREE DOUBLE CLICK

MOUSE BUTTON FOUR DOUBLE CLICK

MOUSE BUTTON FIVE DOUBLE CLICK

DRAG DEFAULT MOUSE BUTTON

DRAG MOUSE BUTTON ONE

DRAG MOUSE BUTTON TWO

DRAG MOUSE BUTTON THREE

DRAG MOUSE BUTTON FOUR

DRAG MOUSE BUTTON FIVE

PREVIOUS SCREEN

NEXT SCREEN

FIRST SCREEN

LAST SCREEN

TERMINATE SERVER

LEFT TAB

MOVE LINE UP

MOVE LINE DOWN

PARTIAL LINE UP

PARTIAL LINE DOWN

PARTIAL SPACE LEFT

PARTIAL SPACE RIGHT

SET MARGIN LEFT

SET MARGIN RIGHT

RELEASE MARGIN LEFT

RELEASE MARGIN RIGHT

RELEASE MARGIN LEFT AND RIGHT

FAST CURSOR LEFT

FAST CURSOR RIGHT

FAST CURSOR UP

FAST CURSOR DOWN

CONTINUOUS UNDERLINE

DISCONTINUOUS UNDERLINE

EMPHASIZE

CENTER OBJECT

ISO_ENTER

DEAD GRAVE ACCENT

DEAD ACUTE ACCENT

DEAD CIRCUMFLEX

DEAD TILDE

DEAD MACRON

DEAD BREVE

DEAD ABOVEDOT

DEAD DIAERESIS

DEAD ABOVERING

DEAD DOUBLE ACUTE ACCENT

DEAD CARON

DEAD CEDILLA

DEAD OGONEK

DEAD IOTA

DEAD VOICED SOUND

DEAD SEMI VOICED SOUND

