The X Keyboard Extension: Protocol Specification

The effective modifiers and group report the cumulative effects of the base, latched and locked modifiers and group respectively, and cannot be directly changed. Note that the effective modifiers and effective group are computed differently.

The effective modifiers are simply the bitwise union of the base, latched and locked modifiers.

The effective group is the arithmetic sum of the base, latched and locked groups. The locked and effective keyboard group must fall in the range Group1 - Group4 , so they are adjusted into range as specified by the global GroupsWrap control as follows:

The base and latched keyboard groups are unrestricted eight-bit integer values and are not affected by the GroupsWrap control.

Many events report the keyboard state in a single state field. Using XKB, a state field combines modifiers, group and the pointer button state into a single sixteen bit value as follows:

It is possible to assemble a state field from any of the components of the XKB keyboard state. For example, the effective keyboard state would be assembled as described above using the effective keyboard group, the effective keyboard modifiers and the pointer button state.

The core protocol does not provide any way to exclude certain modifiers from client events, so there is no way to set up a modifier which affects only the server.

The modifiers specified in the mask of the InternalMods control are not reported in any core protocol events, are not used to determine grabs and are not used to calculate compatibility state for XKB-unaware clients. Server internal modifiers affect only the action applied when a key is pressed.

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 another mask which can help avoid some of these problems.

The locked state of the modifiers specified in mask of the IgnoreLockMods control is not reported in most core protocol events and is not used to activate grabs. The only core events which include the locked state of the modifiers in the ignore locks mask are key press and release events that do not activate a passive grab and which do not occur while a grab is active. If the IgnoreGroupLock control is set, the locked state of the keyboard group is not considered when activating passive grabs.

Without XKB, the passive grab set by a translation (e.g. Alt<KeyPress>space ) does not trigger if any modifiers other than those specified by the translation are set, with the result that many user interface components do not react when either Num Lock or when the secondary keyboard group are active. The ignore locks mask and the ignore group locks control make it possible to avoid this behavior without exhaustively grabbing every possible modifier combination.

Some XKB structures ignore modifier definitions in which the virtual modifiers are unbound. Consider this example:

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

If the NumLock virtual modifier is not bound to any real modifiers, these effective masks for these two cases are identical (i.e. they contain only Shift ). When it is essential to distinguish between OneThing and Another, XKB considers only those modifier definitions for which all virtual modifiers are bound.

When RepeatKeys are active, the PerKeyRepeat control specifies whether or not individual keys should autorepeat when held down. XKB provides the PerKeyRepeat for convenience only, and it always parallels the auto-repeats field of the core protocol GetKeyboardControl request — changes to one are always reflected in the other.

The X server usually generates both press and release events whenever an autorepeating key is held down. If an XKB-aware client enables the DetectableAutorepeat per-client option for a keyboard, the server sends that client a key release event only when the key is physically released. For example, holding down a key to generate three characters without detectable autorepeat yields:

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

If detectable autorepeat is enabled, the client instead receives:

Press-> Press -> Press -> Release

Note that only clients that request detectable autorepeat are affected; other clients continue to receive both press and release events for autorepeating keys. Also note that support for detectable autorepeat is optional; servers are not required to support detectable autorepeat, but they must correctly report whether or not it is supported.

See Querying and Changing Per-Client Flags describes the XkbPerClientFlags request, which reports or changes values for all of the per-client flags, and which lists the per-client flags that are supported.

If the SA_MovePtr action specifies relative motion, events are generated as follows: The initial event always moves the cursor the distance specified in the action; after steps to maximum acceleration events have been generated, all subsequent events move the pointer the distance specified in the action times the maximum acceleration. Events after the first but before maximum acceleration has been achieved are accelerated according to the formula:

Where action_delta is the offset specified by the mouse keys action, max_accel and steps_to_max are parameters to the MouseKeysAccel ctrl, and the curveFactor is computed using the MouseKeysAccel curve parameter as follows:

With the result that a curve of 0 causes the distance moved to increase linearly from action_delta to

, and the minimum legal curve of - 1000 causes all events after the first move at max_accel . A negative curve causes an initial sharp increase in acceleration which tapers off, while a positive curve yields a slower initial increase in acceleration followed by a sharp increase as the number of pointer events generated by the action approaches steps_to_max .

If an SA_MovePtr action specifies an absolute position for one of the coordinates but still allows acceleration, all repeated events contain any absolute coordinates specified in the action.

XKB provides the separate lookup and grab states to help work around some difficulties with the way the core protocol specifies passive grabs. Unfortunately, many clients work around those problems differently, and the way that XKB handles grabs and reports keyboard state can sometimes interact with those client workarounds in unexpected and unpleasant ways.

To provide more reasonable behavior for clients that are aware of XKB without causing problems for clients that are unaware of XKB, this extension provides two per-client flags that specify the way that XKB and the core protocol should interact.

The state used to trigger a passive grab is controlled by the setting of the GrabsUseXKBState per-client flag at the time the grab is registered. Changing this flag does not affect existing passive grabs.

Each entry of a key type’s map field specifies the shift level that corresponds to some XKB modifier definition; any combination of modifiers that is not explicitly listed somewhere in the map yields shift level one. Map entries which specify unbound virtual modifiers (see See Inactive Modifier Definitions) are not considered; each entry contains an automatically-updated active field which indicates whether or not it should be used.

Each key type includes a few fields that are derived from the contents of the map and which report some commonly used values so they don’t have to be constantly recalculated. The numLevels field contains the highest shift level reported by any of its map entries; XKB uses numLevels to insure that the array of symbols bound to a key is large enough (the number of levels reported by a key type is also referred to as its width). The modifiers field reports all real modifiers considered by any of the map entries for the type. Both modifiers and numLevels are updated automatically by XKB and neither can be changed explicitly.

Any modifiers specified in modifiers are normally consumed (see See Transforming the KeySym Associated with a Key Event), which means that they are not considered during any of the later stages of event processing. For those rare occasions that a modifier should be considered despite having been used to look up a symbol, key types include an optional preserve field. If a preserve list is present, each entry corresponds to one of the key type’s map entries and lists the modifiers that should not be consumed if the matching map entry is used to determine shift level.

For example, the following key type implements caps lock as defined by the core protocol (using the second symbol bound to the key):

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

The problem with this kind of definition is that we could assign completely unrelated symbols to the two shift levels, and "Caps Lock" would choose the second symbol. Another definition for alphabetic keys uses system routines to capitalize the keysym:

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

When caps lock is applied using this definition, we take the symbol from shift level one and capitalize it using system-specific capitalization rules. If shift and caps lock are both set, we take the symbol from shift level two and try to capitalize it, which usually has no effect.

The following key type implements shift-cancels-caps lock behavior for alphabetic keys:

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

Consider the four possible states that can affect alphabetic keys: no modifiers, shift alone, caps lock alone or shift and caps lock together. The map contains no explicit entry for None (no modifiers), so if no modifiers are set, any group with this type returns the first keysym. The map entry for Shift reports Level2 , so any group with this type returns the second symbol when Shift is set. There is no map entry for Lock alone, but the type specifies that the Lock modifier should be preserved in this case, so Lock alone returns the first symbol in the group but first applies the capitalization transformation, yielding the capital form of the symbol. In the final case, there is no map entry for Shift+Lock , so it returns the first symbol in the group; there is no preserve entry, so the Lock modifier is consumed and the symbol is not capitalized.

The key symbol map for a key contains all of the information that a client needs to process events generated by that key. Each key symbol mapping reports:

It is legal for a key to have zero groups, in which case it also has zero symbols and all events from that key yield NoSymbol . The array of key types is of fixed width and is large enough to hold key types for the maximum legal number of groups ( MaxKbdGroups , currently four); if a key has fewer than MaxKbdGroups groups, the extra key types are reported but ignored. The groupsWidth field cannot be explicitly changed; it is updated automatically whenever the symbols or set of types bound to a key are changed.

If, when looking up a symbol, the effective keyboard group is out-of-range for the key, the groupInfo field of the key symbol map specifies the rules for determining the corresponding legal group as follows:

The client map contains an array of key symbol mappings, with one entry for each key between the minimum and maximum legal keycodes, inclusive. All keycodes which fall in that range have key symbol mappings, whether or not any key actually yields that code.

XKB also provides an indicator map for each of the thirty-two keyboard indicators; an indicator map specifies:

If IM_NoAutomatic is set in the flags field of an indicator map, that indicator never changes in response to changes in keyboard state or controls, regardless of the values for the other fields of the indicator map. If IM_NoAutomatic is not set in flags , the other fields of the indicator map specify the automatic changes to the indicator in response to changes in the keyboard state or controls.

The which_groups and the groups fields of an indicator map determine how the keyboard group state affects the corresponding indicator. The which_groups field controls the interpretation of groups and may contain any one of the following values:

The which_mods and mods fields of an indicator map determine how the state of the keyboard modifiers affect the corresponding indicator. The mods field is an XKB modifier definition, as described in See Modifier Definitions, which can specify both real and virtual modifiers. The mods field takes effect even if some or all of the virtual indicators specified in mods are unbound.

The which_mods field can specify one or more components of the XKB keyboard state. The corresponding indicator is lit whenever any of the real modifiers specified in the mask field of the mods modifier definition are also set in any of the current keyboard state components specified by the which_mods . The which_mods field may have any combination of the following values:

The controls field specifies a subset of the boolean keyboard controls (see See "Boolean" Controls and The EnabledControls Control). The indicator is lit whenever any of the boolean controls specified in controls are enabled.

An indicator is lit whenever any of the conditions specified by its indicator map are met, unless overridden by the IM_NoAutomatic flag (described above) or an explicit indicator change (described below).

The fact that the state field of an event might look different when XKB is present can cause problems with passive grabs. Existing clients specify the modifiers they wish to grab using the rules defined by the core protocol, which use a normal modifier to indicate keyboard group. If we used an XKB state field, the high bits of the state field would be non-zero whenever the keyboard was in any group other than Group1 , and none of the passive grabs set by clients could ever be triggered.

To avoid this behavior, the X server normally uses the compatibility grab state to decide whether or not to activate a passive grab, even for XKB-aware clients. The group compatibility map attempts to encode the keyboard group in one or more modifiers of the compatibility state, so existing clients continue to work exactly the way they do today. By default, there is no way to directly specify a keyboard group in a Grabbed or GrabButton request, but groups can be specified indirectly by correctly adjusting the group compatibility map.

Clients that wish to specify an XKB keyboard state, including a separate keyboard group, can set the GrabsUseXKBState per-client flag which indicates that all subsequent key and button grabs from the requesting clients are specified using an XKB state.

Whether the XKB or core state should be used to trigger a grab is determined by the setting of the GrabsUseXKBState flag for the requesting client at the time the key or button is grabbed. There is no way to change the state to be used for a grab that is already registered or for grabs that are set by some other client.

This automatic remapping might accidentally replace definitions that were explicitly requested by an application, so the XKB keyboard description defines a set of explicit components for each key; any components that are listed in the explicit components for a key are not changed by the automatic keyboard mapping. The explicit components field for a key can contain any combination of the following values:

The first step in applying the changes specified by a core protocol ChangeKeyboardMapping request to the XKB description of a keyboard is to determine the number of groups that are defined for the key and the width of each group. The XKB extension does not change key types in response to core protocol SetModifierMapping requests, but it does choose key actions as described in See Assigning Actions To Keys.

Determining the number of symbols required for each group is straightforward. If the key type for some group is not protected by the corresponding ExplicitKeyType component, that group has two symbols. If any of the explicit components for the key include ExplicitKeyType3 or ExplicitKeyType4 , the width of the key type currently assigned to that group determines the number of symbols required for the group in the core protocol keyboard description. The explicit type components for Group1 and Group2 behave similarly, but for compatibility reasons the first two groups must have at least two symbols in the core protocol symbol mapping. Even if an explicit type assigned to either of the first two keyboard groups has fewer than two symbols, XKB requires two symbols for it in the core keyboard description.

If the core protocol request contains fewer symbols than XKB needs, XKB adds trailing NoSymbol keysyms to the request to pad it to the required length. If the core protocol request includes more symbols than it needs, XKB truncates the list of keysyms to the appropriate length.

Finally, XKB divides the symbols from the (possibly padded or truncated) list of symbols specified by the core protocol request among the four keyboard groups. In most cases, the symbols for each group are taken from the core protocol definition in sequence (i.e. the first pair of symbols is assigned to Group1 , the second pair of symbols is assigned to Group2 , and so forth). If either Group1 or Group2 has an explicitly defined key type with a width other than two, it gets a little more complicated.

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

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

Once the symbols specified by ChangeKeyboardMapping have been assigned to the four keyboard groups for a key, the X server assigns a key type to each group on the key from a canonical list of key types. The first four key types in any keyboard map are reserved for these standard key types:

Users or applications may change 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.

Before assigning key types to groups, the X server expands any alphanumeric symbol definitions as follows:

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 element were the uppercase form of the symbol. For the purposes of this expansion, XKB ignores the locale and uses the capitalization rules defined in dflttrns.htm#17949.

For each keyboard group that does not have an explicit type definition, XKB chooses a key type from the canonical key types. If the second symbol assigned to a group is NoSymbol (after alphabetic expansion), the server assigns key type ONE_LEVEL . If the group contains the lowercase and uppercase forms of a single glyph (after alphanumeric expansion), the server assigns key type ALPHABETIC . If either of the symbols in a group is a numeric keypad keysym ( KP_* ), the server assigns key type KEYPAD . Otherwise, it assigns key type TWO_LEVEL .

Finally, XKB determines the number of groups of symbols that are actually defined for the key. Trailing empty groups (i.e. groups that have NoSymbol in all symbol positions) are ignored.

There are two last special cases for compatibility with the core protocol: If, after trailing empty groups are excluded, all of the groups of symbols bound to the key have identical type and symbol bindings, XKB assigns only one group to the key. If Group2 is empty and either of Group3 or Group4 are not, and if neither Group1 nor Group2 have explicit key types, XKB copies the symbols and key type from Group1 into Group2 .

Once symbols have been divided into groups and key types chosen for the keys affected by a ChangeKeyboardMapping request, XKB examines the symbols and modifier mapping for each changed key and assigns server actions where appropriate. XKB also automatically assigns server actions to changed keys if the client issues a core protocol SetModifierMapping request, and does so optionally in response to XkbSetMap and XkbSetCompatMap requests.

The compatibility map includes a list of symbol interpretations , which XKB compares to each symbol associated with any changed keys in turn, unless the ExplicitInterp component is set for a key. Setting the ExplicitInterp component prevents the application of symbol interpretations to that key.

If the modifiers and keysym specified in a symbol interpretation match the modifier mapping and a symbol bound to a changed key that is not protected by ExplicitInterp , the server applies the symbol interpretation to the symbol position. 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.

XKB uses four of the fields of a symbol interpretation to decide if it matches one of the symbols bound to some changed key:

Applying a symbol interpretation can affect several aspects of the XKB definition of the key symbol mapping to which it is applied:

If no interpretations match a given symbol or key, the server uses: SA_NoAction , autorepeat enabled, non-locking key. with no virtual modifiers.

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

If the core protocol modifier mapping is changed, the server regenerates actions for the affected keys. The XkbSetMap and XkbSetCompatMap requests can also cause actions for some or all keyboard keys to be recomputed.

Changes to the symbols or modifier mapping can affect the bindings of virtual modifiers. If any virtual modifiers change, XKB updates all of its data structures to reflect the change. Applying virtual modifier changes to the keyboard mapping night result in changes to types, the group compatibility map, indicator maps, internal modifiers or ignore locks modifiers.

The types component of a keyboard mapping specifies the key types that can be associated with the various keyboard keys. It affects the types symbolic name and the list of types associated with the keyboard (see See Key Types). The types component of a keyboard mapping can also optionally contain real modifier bindings and symbolic names for one or more virtual modifiers.

The special types component named "canonical" always contains the types and definitions listed in types.htm#24591 of this document.

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

The compatibility map component of a keyboard mapping primarily specifies the rules used to assign actions to keysyms. It affects the compat symbolic name, the symbol compatibility map and the group compatibility map. The compat component might also specify maps for some indicators and the real modifier bindings and symbolic names of some virtual modifiers.

XKB defines no hints that are specific to the compatibility map component.

The symbols component of a keyboard mapping specifies primarily the symbols bound to each keyboard key. It affects the symbols symbolic name, a key symbol mapping for each key, they keyboard modifier mapping, and the symbolic names for the keyboard symbol groups. Optionally, the symbols component can contain explicit actions and behaviors for some keys, or the real modifier bindings and symbolic names for some virtual modifiers.

XKB defines the following additional hints for the symbols component:

These hints only apply to partial symbols components; full symbols components are assumed to specify all of the pieces listed above.

The geometry component of a keyboard mapping specifies primarily the geometry of the keyboard. It contains the geometry symbolic name and the keyboard geometry description. The geometry component might also contain aliases for some keys or symbolic names for some indicators and might affect the set of indicators that are physically present. Key aliases defined in the geometry component of a keyboard mapping override those defined in the keycodes component.

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

In addition to all of the errors defined by the core protocol, 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 an appropriate. Unless otherwise noted, any request with an argument of type KB_DEVICESPEC can cause Keyboard errors if an illegal or inappropriate device is specified.

When the extension reports a Keyboard error, the most significant byte of the resource_id is a further refinement of the error cause, as defined in the table below. The least significant byte contains the device, class, or feedback id as indicated:

With the exception of Alloc or Implementation errors, which might result in an inconsistent internal state, no XKB request that reports an error condition has any effect. Unless otherwise stated, requests which update some aspect of the keyboard description will not apply only part of a request — if part of a request fails, the whole thing is ignored.

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 version, False otherwise. The serverMajor and serverMinor fields return the actual version supported by the server.

Until a client explicitly and successfully requests the XKB extension, an XKB capable server reports compatibility state in all core protocol events and requests. Once a client asks for XKB extension semantics by issuing this request, the server reports the extended XKB keyboard state in some core protocol events and requests, as described in the overview section of this specification.

Clients should issue an XkbUseExtension request before using any other extension requests.

This request updates the event masks of the keyboard indicated by deviceSpec for this client. If deviceSpec specifies an illegal device, a Keyboard error results.

The affectMap and map fields specify changes to the event details mask for the XkbMapNotify event. If any map components are set in map but not in affectMap , a Match error results. Otherwise, any map components that are set in affectMap are set or cleared in the map notify details mask, depending on the value of the corresponding field in map .

The affectWhich , clear , and selectAll fields specify changes to any other event details masks. If any event types are set in both clear and selectAll , a Match error results; if any event types are specified in either clear or selectAll but not in affectWhich , a Match error results. Otherwise, the detail masks for any event types specified in the affectWhich field of this request are changed as follows:

Each entry of the details list specifies changes to the event details mask for a single type of event, and consists of an affects mask and a values mask. All details that are specified in affects are set to the corresponding value from values ; if any details are listed in values but not in affects , a Match error results.

The details list contains entries only for those event types, if any, that are listed in the affectWhich mask and not in either clear or selectAll . When present, the items of the details list appear in the following order:

Detail masks for event types that are not specified in affectWhich are not changed.

If any components are specified in a client’s event masks, the X server sends the client an appropriate event whenever any of those components change state. Unless explicitly modified, all event detail masks are empty. See Events describes all XKB events and the conditions under which the server generates them.

This request generates audible bells and/or XkbBellNotify events for the bell specified by the bellClass and bellID on the device specified by deviceSpec at the specified pitch , duration and volume ( percent ). If deviceSpec specifies a device that does not have a bell or keyboard feedback, a Keyboard error results.

If both forceSound and eventOnly are set, this request yields a Match error. Otherwise, if forceSound is True , this request always generates a sound and never generates an event; if eventOnly is True , it causes an event but no sound. If neither forceSound nor eventOnly are True , this request always generates an event; if the keyboard’s global AudibleBell control is enabled, it also generates a sound.

Any bell event generated by this request contains all of the information about the bell that was requested, including the symbolic name specified by name and the event window specified by window. The name and window are not directly interpreted by XKB, but they must have the value None or specify a legal Atom or Window, respectively. XkbBellNotify events generated in response to core protocol or X input extension bell requests always report None as their name .

The bellClass , bellID , and percent fields are interpreted as for the X input extension DeviceBell request. If pitch and duration are zero, the server uses the corresponding values for that bell from the core protocol or input extension, otherwise pitch and duration are interpreted as for the core protocol ChangeKeyboardControl request; if they do not include legal values, a Value error results. The window field must specify a legal Window or have the value None , or a Value error results. The name field must specify a legal Atom or have the value None , or an Atom error results. If an error occurs, this request has no other effect (i.e. does not cause a sound or generate an event).

The pitch , volume , and duration are suggested values for the bell, but XKB does not require the server to honor them.

This request returns a detailed description of the current state of the keyboard specified 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 XkbLatchLockState requests. The group return value reports the effective keyboard group which results from the current combination of base, latched and locked group values.

The lookupMods return value reports the lookup modifiers, which consist of the current effective modifiers minus any server internal modifiers. The grabMods return value reports the grab modifiers, which consist of the lookup modifiers minus any members of the ignore locks mask that are not either latched or logically depressed. See Keyboard State describes the lookup modifiers and grab modifiers in more detail.

The ptrBtnState return value reports the current logical state of up to five buttons on the core pointer device.

The compatState return value reports the compatibility state that corresponds to the effective keyboard group and modifier state. The compatLookupMods and compatGrabMods return values report the core protocol compatibility states that correspond to the XKB lookup and grab state. All of the compatibility states are computed by applying the group compatibility mapping to the corresponding XKB modifier and group states, as described in See Group Compatibility Map.

This request locks or latches keyboard modifiers and group state for the device specified by deviceSpec . If deviceSpec specifies an illegal or non-keyboard device, a Keyboard error occurs.

The locked state of any modifier specified in the affectModLocks mask is set to the corresponding value from modLocks . If lockGroup is True , the locked keyboard group is set to the group specified by groupLock . If any modifiers are set in modLocks but not affectModLocks , a Match error occurs.

The latched state of any modifier specified in the affectModLatches mask is set to the corresponding value from modLatches . If latchGroup is True , the latched keyboard group is set to the group specified by groupLatch . if any modifiers are set in modLatches but not in affectModLatches , a Match error occurs.

If the locked group exceeds the maximum number of groups permitted for the specified keyboard, it is wrapped or truncated back into range as specified by the global GroupsWrap control. 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 XkbStateNotify events as appropriate if any state components have changed. Changing the keyboard state might also turn indicators on or off which can cause XkbIndicatorStateNotify events as well.

If any errors occur, this request has no effect.

This request returns the current values and status of all controls for the keyboard specified by deviceSpec . If deviceSpec specifies an illegal device a Keyboard error results. 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, and groupsWrap reports the treatment of out-of-range groups, as described in See Key Symbol Map. The internalMods and ignoreLockMods return values report the current values of the server internal and ignore locks modifiers as described in See Keyboard State. Both are modifier definitions (See Modifier Definitions) which report the real modifiers, virtual modifiers, and the resulting combination of real modifiers that are bound to the corresponding control.

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 timeout, respectively. The mouseKeysDelay , mouseKeysInterval , mouseKeysTimeToMax and mouseKeysMaxSpeed and mouseKeysCurve return values report the current acceleration applied to mouse keys, as described in See The MouseKeysAccel Control. All times are reported in milliseconds.

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

The accessXOptions return value reports the current settings of the various AccessX options flags which govern the behavior of the StickyKeys control and of AccessX feedback.

The accessXTimeout return value reports the length of time, in seconds, that the keyboard must remain idle before AccessX controls are automatically changed; an accessXTimeout of 0 indicates that AccessX controls are not automatically changed. The accessXTimeoutMask specifies the boolean controls to be changed if the AccessX timeout expires; the accessXTimeoutValues field specifies new values for all of the controls in the timeout mask. The accessXTimeoutOptionsMask field specifies the AccessX options to be changed when the AccessX timeout expires; the accessXTimeoutOptionValues return value reports the values to which they will be set.

The enabledControls return value reports the current state of all of the global boolean controls.

The perKeyRepeat array consists of one bit per key and reports the current autorepeat behavior of each keyboard key; if a bit is set in perKeyRepeat , the corresponding key repeats if it is held down while global keyboard autorepeat is enabled. This array parallels the core protocol and input extension keyboard controls, if the autorepeat behavior of a key is changed via the core protocol or input extension, those changes are automatically reflected in the perKeyRepeat array.

This request sets the keyboard controls indicated in changeControls for the keyboard specified by deviceSpec . Each bit that is set in changeControls indicates that one or more of the other request fields should be applied, as follows:

If any other bits are set in changeControls , a Value error results. If any of the bits listed above are not set in changeControls , the corresponding fields must have the value 0 , or a Match error results.

If applied, repeatDelay and repeatInterval change the autorepeat characteristics of the keyboard, as described in See The RepeatKeys Control. If specified, repeatDelay and repeatInterval must both be non-zero or a Value error results.

If applied, the slowKeysDelay field specifies a new delay for the SlowKeys control, as defined in See The SlowKeys Control. If specified, slowKeysDelay must be non-zero, or a Value error results.

If applied, the debounceDelay field specifies a new delay for the BounceKeys control, as described in See The BounceKeys Control. If present, the debounceDelay must be non-zero or a Value error results.

If applied, the mouseKeysDfltBtn field specifies the core pointer button for which events are generated whenever a SA_PtrBtn or SA_LockPtrBtn key action is activated. If present, mouseKeysDfltBtn must specify a legal button for the core pointer device, or a Value error results. See Key Actions describes the SA_PtrBtn and SA_LockPtrBtn actions in more detail.

If applied, the mouseKeysDelay , mouseKeysInterval , mouseKeysTimeToMax , mouseKeysMaxSpeed and mouseKeysCurve fields change the rate at which the pointer moves when a key which generates a SA_MovePtr action is held down. See The MouseKeysAccel Control describes these MouseKeysAccel parameters in more detail. If defined, the mouseKeysDelay , mouseKeysInterval , mouseKeysTimeToMax and mouseKeysMaxSpeed values must all be greater than zero, or a Value error results. The mouseKeysCurve value must be greater than -1000 or a Value error results.

If applied, the accessXOptions field sets the AccessX options, which are described in detail in See The AccessXKeys Control. If either one of XkbStickyKeysMask and XkbAccessXFeedbackMask are set in changeControls and XkbAccessXKeysMask is not, only a subset of the AccessX options are changed, as described in the table above; if both are set or if the AccessXKeys bit is set in changeControls , all of the AccessX options are updated. Any bit in accessXOptions whose interpretation is undefined must be zero, or a Value error results.

If applied, the accessXTimeout , accessXTimeoutMask , accessXTimeoutValues , accessXTimeoutOptionsMask and accessXTimeoutOptionsValues fields change the behavior of the AccessX Timeout control, as described in See The AccessXTimeout Control. The accessXTimeout must be greater than zero, or a Value error results. The accessXTimeoutMask or accessXTimeoutValues fields must specify only legal boolean controls, or a Value error results. The accessXTimeoutOptionsMask and accessXTimeoutOptionsValues fields must contain only legal AccessX options or a Value error results. If any bits are set in either values field but not in the corresponding mask, a Match error results.

If present, the groupsWrap field specifies the treatment of out-of-range keyboard groups, as described in See Key Symbol Map. If the groupsWrap field does not specify a legal treatment for out-of-range groups, a Value error results.

If present, the affectInternalRealMods field specifies the set of real modifiers to be changed in the internal modifier definition and the internalRealMods field specifies new values for those modifiers. The affectInternalVirtualMods and internalVirtualMods fields update the virtual modifier component of the modifier definition that describes the internal modifiers in the same way. If any bits are set in either values field but not in the corresponding mask field, a Match error results.

If present, the affectIgnoreLockRealMods field specifies the set of real modifiers to be changed in the ignore locks modifier definition and the ignoreLockRealMods field specifies new values for those modifiers. The affectIgnoreLockVirtualMods and ignoreLockVirtualMods fields update the virtual modifier component of the ignore locks modifier definition in the same way. If any bits are set in either values field but not in the corresponding mask field, a Match error results.

If present, the perKeyRepeat array specifies the repeat behavior of the individual keyboard keys. The corresponding core protocol or input extension per-key autorepeat information is updated to reflect any changes specified in perKeyRepeat . If the bits that correspond to any out-of-range keys are set in perKeyRepeat , a Value error results.

If present, the affectEnabledControls and enabledControls field enable and disable global boolean controls. Any controls set in both fields are enabled; any controls that are set in affectEnabledControls but not in enabledControls are disabled. Controls that are not set in either field are not affected. If any controls are specified in enabledControls but not in affectEnabledControls , a Match error results. If either field contains anything except boolean controls, a Value error results.

This request returns the indicated components of the server and client maps of the keyboard 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 component is specified in both full and partial , or a Value error if any undefined bits are set in either full or partial .

Each bit in the partial mask controls the interpretation of one or more of the other request fields, as follows:

If any of these keyboard map components are specified in partial , the corresponding values must specify a valid subset of the requested components or this request reports a Value error. If a keyboard map component is not specified in partial , the corresponding fields must contain zeroes, or a Match error results.

If any error is generated, the request aborts and does not report any values.

On successful return, the deviceID field reports the X input extension device ID of the keyboard for which information is being returned, or 0 if the server does not support the X input extension. The minKeyCode and maxKeyCode return values report the minimum and maximum keycodes that are legal for the keyboard in question.

The present return value lists all of the keyboard map components contained in the reply. The bits in present affect the interpretation of the other return values as follows:

If XkbKeyTypesMask is set in present :

If XkbKeySymsMask is set in present :

If XkbKeyActionsMask is set in present :

If XkbKeyBehaviorsMask is set in present :

If XkbExplicitComponentsMask is set in present :

If XkbModifierMapMask is set in present :

If XkbVirtualModMapMask is set in present :

If XkbVirtualModsMask is set in present :

If any of these bits are not set in present , the corresponding numeric fields all have the value zero, and the corresponding lists are all of length zero.

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

The present field specifies the keyboard map components contained to be changed. The bits in present affect the interpretation of the other fields as follows:

If XkbKeyTypesMask is set in present , firstType and nTypes specify a subset of the key types bound to the keyboard to be changed or created. The index of the first key type to be changed must be less than or equal to the unmodified length of the list of key types or a Value error results.

If XkbKeyTypesMask is set in present and SetMapResizeTypes is set in flags , the server resizes the list of key types bound to the keyboard so that the last key type specified by this request is the last element in the list. If the list of key types is shrunk, any existing key definitions that use key types that eliminated are automatically assigned key types from the list of canonical key types as described in See Assigning Types To Groups of Symbols for a Key. The list of key types bound to a keyboard must always include the four canonical types and cannot have more than XkbMaxTypesPerKey (32) types; any attempt to reduce the number of types bound to a keyboard below four or above XkbMaxTypesPerKey causes a Value error. Symbolic names for newly created key types or levels within a key type are initialized to None .

If XkbKeyTypesMask is set in present , the types list has nTypes entries of type KB_KEYTYPE.Each key type specified in types must be valid or a Value error results. To be valid a key type definition must meet the following criteria:

Each key type in types must also be internally consistent, or a Match error results. To be internally consistent, a key type definition must meet the following criteria:

If XkbKeySymsMask is set in present , firstKeySym and nKeySyms specify a subset of the keyboard keys to which new symbols are to be assigned and totalSyms specifies the total number of symbols to be assigned to those keys. If any of the keys specified by firstKeySym and nKeySyms are not legal, a Match error results. The syms list has nKeySyms elements of type KB_KEYSYMMAP. Each key in the resulting key symbol map must be valid and internally consistent or a Value error results. To be valid and internally consistent, a key symbol map must meet the following criteria:

If XkbKeyActionsMask is set in present , firstKeyAction and nKeyActions specify a subset of the keyboard keys to which new actions are to be assigned and totalActions specifies the total number of actions to be assigned to those keys. If any of the keys specified by firstKeyAction and nKeyActions are not legal, a Match error results. The count field of the actions return value has nKeyActions elements of type CARD8; each element of count specifies the number of actions bound to the corresponding key. The actions list in the actions field has totalActions elements of type KB_ACTION. These actions are assigned to each target key in turn, as specified by count . The list of actions assigned to each key must either be empty or have exactly as many actions as the key has symbols, or a Match error results.

If XkbKeyBehaviorsMask is set in present , firstKeyBehavior and nKeyBehaviors specify a subset of the keyboard keys to which new behaviors are to be assigned, and totalKeyBehaviors specifies the total number of keys in that range to be assigned non-default behavior. If any of the keys specified by firstKeyBehavior and nKeyBehaviors are not legal, a Match error results. The behaviors list has totalKeyBehaviors elements of type KB_BEHAVIOR; each entry of behaviors specifies a key in the specified range and a new behavior for that key; any key that falls in the range specified by firstBehavior and nBehaviors for which no behavior is specified in behaviors is assigned the default behavior, KB_Default . The new behaviors must be legal, or a Value error results. To be legal, the behavior specified in the XkbSetMap request must:

Key behaviors that are not recognized by the server are accepted but ignored. Attempts to replace a "permanent" behavior are silently ignored; the behavior is not replaced, but not error is generated and any other components specified in the XkbSetMap request are updated, as appropriate.

If XkbVirtualModsMask is set in present , virtualMods is a mask which specifies the virtual modifiers to be rebound. The vmods list specifies the real modifiers that are bound to each of the virtual modifiers specified in virtualMods , starting from the lowest numbered virtual modifier and progressing upward. Any virtual modifier that is not specified in virtualMods has no corresponding entry in vmods , so the vmods list has one entry for each bit that is set in virtualMods .

If XkbExplicitComponentsMask is set in present , firstKeyExplicit and nKeyExplicit specify a subset of the keyboard keys to which new explicit components are to be assigned, and totalKeyExplicit specifies the total number of keys in that range that have at least one explicit component. The explicit list has totalKeyExplicit elements of type KB_KEYEXPLICIT; each entry of explicit specifies a key in the specified range and a new set of explicit components for that key. Any key that falls in the range specified by firstKeyExplicit and nKeyExplicit that is not assigned some value in explicit has no explicit components.

If XkbModifierMapMask is set in present , firstModMapKey and nModMapKeys specify a subset of the keyboard keys for which new modifier mappings are to be assigned, and totalModMapKeys specifies the total number of keys in that range to which at least one modifier is bound. The modmap list has totalModMapKeys elements of type KB_KEYMODMAP; each entry of modmap specifies a key in the specified range and a new set of modifiers to be associated with that key. Any key that falls in the range specified by firstModMapKey and nModMapKeys that is not assigned some value in modmap has no associated modifiers.

If the modifier map is changed by the XkbSetMap request, any changes are also reflected in the core protocol modifier mapping. Changes to the core protocol modifier mapping are reported to XKB-unaware clients via MappingNotify events and can be retrieved with the core protocol GetModifierMapping request.

If XkbVirtualModMapMask is set in present , firstVModMapKey and nVModMapKeys specify a subset of the keyboard keys for which new modifier mappings are to be assigned, and totalVModMapKeys specifies the total number of keys in that range to which at least one virtual modifier is bound. The vmodmap list has totalVModMapKeys elements of type KB_KEYVMODMAP; each entry of vmodmap specifies a key in the specified range and a new set of virtual modifiers to be associated with that key. Any key that falls in the range specified by firstVModMapKey and nVModMapKeys that is not assigned some value in vmodmap has no associated virtual modifiers.

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 XkbSetMapRecomputeActions bit is set in flags , the actions associated with any keys for which symbol or modifier bindings were changed by this request are recomputed as described in See Assigning Actions To Keys. Note that actions are recomputed after any actions specified in this request are bound to keys, so the actions specified in this request might be clobbered by the automatic assignment of actions to keys.

If the group width of an existing key type is changed, the list of symbols associated with any keys of the changed type might be 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 calculated by applying any keyboard symbol interpretations to the corresponding symbols.

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

Assigning key behavior KB_RadioGroup to a key adds that key as a member of the specified radio group. Changing a key with the existing behavior KB_RadioGroup removes that key from the group. Changing the elements of a radio group can cause synthetic key press or key release events if the key to be added or removed is logically down at the time of the change.

Changing a key with behavior KB_Lock causes a synthetic key release event if the key is logically but not physically down at the time of the change.

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

Key press and key release events caused by changing key behavior may cause additional XkbStateNotify or XkbIndicatorStateNotify events.

This request returns the listed compatibility map components for the keyboard specified by deviceSpec . If deviceSpec does not specify a valid keyboard device, a Keyboard Error results. On return, deviceID reports the input extension identifier of the keyboard device or 0 if the server does not support the input extension.

If getAllSI is False , firstSI and nSI specify a subset of the symbol interpretations to be returned; if used, 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 getAllSyms is True , the server ignores firstSym and nSyms and returns all of the symbol interpretations defined for the keyboard.