# XKB Protocol Requests

This document uses the syntactic conventions and common types defined by the specification of the core X protocol with a number of additions, which are detailed below.

## Errors

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

### Keyboard Errors

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:

high-order byte | value | meaning | low-order byte
--- | --- | --- | ---
XkbErr_BadDevice | 0xff | device not found | device id
XkbErr_BadClass | 0xfe | device found, but is the wrong class | class id
XkbErr_BadId | 0xfd | device found, class ok, but device does not have a feedback with the indicated id | feedback id

### Side-Effects of Errors

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.

## Common Types

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

Name | Value
--- | ---
LISTofITEMs | The type LISTofITEMs is special. It is similar to the LISTofVALUE defined by the core protocol, but the elements of a LISTofITEMs are not necessarily all the same size. The use of a BITMASK to indicate which members are present is optional for a LISTofITEMs — it is possible for the set of elements to be derived from one or more fields of the request.
KB_DEVICESPEC | 8 bit unsigned integer, UseCoreKbd, or UseCorePtr
KB_LEDCLASSSPEC | { KbdFeedbackClass , LedFeedbackClass , DfltXIClass , AllXIClasses , XINone }
KB_BELLCLASSSPEC | { KbdFeedbackClass , BellFeedbackClass , DfltXIClass , AllXIClasses }
KB_IDSPEC | 8 bit unsigned integer or DfltXIId
KB_VMODMASK | CARD16, each bit corresponds to a virtual modifier
KB_GROUPMASK | { Group1 , Group2 , Group3 , Group4 }
KB_GROUPSWRAP | { WrapIntoRange , ClampIntoRange , RedirectIntoRange }
KB_GROUPINFO | { groupsWrap: KB_GROUPSWRAP redirectGroup: 1…4, numGroups: 1…4 }
KB_NKNDETAILSMASK | { NKN_Keycodes , NKN_Geometry, NKN_DeviceID }
KB_STATEMASK | KEYBUTMASK or KB_GROUPMASK
KB_STATEPARTMASK | { ModifierState , ModifierBase , ModifierLatch , ModifierLock , GroupState , GroupBase , GroupLatch , GroupLock , CompatState , GrabMods , CompatGrabMods , LookupMods , CompatLookupMods , PointerButtons }
KB_BOOLCTRLMASK | { RepeatKeys , SlowKeys , BounceKeys , StickyKeys , MouseKeys , MouseKeysAccel , AccessXKeys , AccessXTimeout , AccessXFeedback , AudibleBell , Overlay1 , Overlay2 , IgnoreGroupLock }
KB_CONTROLSMASK | { GroupsWrap, InternalMods , IgnoreLockMods , PerKeyRepeat , ControlsEnabled } or KB_BOOLCTRLMASK
KB_MAPPARTMASK | { KeyTypes , KeySyms , ModifierMap , ExplicitComponents , KeyActions , KeyBehaviors , VirtualMods , VirtualModMap }
KB_CMDETAILMASK | { SymInterp , GroupCompat }
KB_NAMEDETAILMASK | { KeycodesName , GeometryName , SymbolsName , PhysSymbolsName , TypesName , CompatName , KeyTypeNames , KTLevelNames , IndicatorNames , KeyNames , KeyAliases , VirtualModNames , GroupNames , RGNames }
KB_AXNDETAILMASK | { AXN_SKPress , AXN_SKAccept , AXN_SKReject , AXN_SKRelease, AXN_BKAccept, AXN_BKReject, AXN_AXKWarning }
KB_AXSKOPTSMASK | { AX_TwoKeys , AX_LatchToLock }
KB_AXFBOPTSMASK | { AX_SKPressFB , AX_SKAcceptFB , AX_FeatureFB , AX_SlowWarnFB , AX_IndicatorFB , AX_StickyKeysFB , AX_SKReleaseFB , AX_SKRejectFB , AX_BKRejectFB , AX_DumbBellFB }
KB_AXOPTIONSMASK | KB_AXFBOPTSMASK or KB_AXSKOPTSMASK
KB_GBNDETAILMASK | { GBN_Types , GBN_CompatMap , GBN_ClientSymbols , GBN_ServerSymbols , GBN_IndicatorMap , GBN_KeyNames , GBN_Geometry , GBN_OtherNames }
KB_BELLDETAILMASK | { XkbAllBellNotifyEvents }
KB_MSGDETAILMASK | { XkbAllActionMessages }
KB_EVENTTYPE | { XkbNewKeyboardNotify , XkbMapNotify , XkbStateNotify , XkbControlsNotify , XkbIndicatorStateNotify , XkbIndicatorMapNotify , XkbNamesNotify , XkbCompatMapNotify , XkbBellNotify , XkbActionMessage , XkbAccessXNotify , XkbExtensionDeviceNotify }
KB_ACTION | [ type: CARD8 data: LISTofCARD8 ]
KB_BEHAVIOR | [ type: CARD8, data: CARD 8 ]
KB_MODDEF | [ mask: KEYMASK, mods: KEYMASK, vmods: KB_VMODMASK ]
KB_KTMAPENTRY | [ active: BOOL, level: CARD8, mods: KB_MODDEF ]
KB_KTSETMAPENTRY | [ level: CARD8, mods: KB_MODDEF ]
KB_KEYTYPE | [ mods: KB_MODDEF, numLevels: CARD8, map: LISTofKB_KTMAPENTRY, preserve: LISTofKB_MODDEF ]
KB_SETKEYTYPE | [ realMods: KEYMASK, vmods: CARD16, numLevels: CARD8, map: LISTofKB_KTSETMAPENTRY, preserve: LISTofKB_MODDEF ]
KB_KEYSYMMAP | [ ktIndex: LISTofCARD8, width: CARD8 numGroups: 0…4, groupsWrap: KB_GROUPSWRAP, redirectGroup: 0…3, syms: LISTofKEYSYM ]
KB_KEYVMODMAP | [ key: KEYCODE, vmods: CARD16 ]
KB_KEYMODMAP | [ key: KEYCODE, mods: KEYMASK ]
KB_EXPLICITMASK | { ExplicitKeyType1 , ExplicitKeyType2 , ExplicitKeyType3 , ExplicitKeyType4 , ExplicitInterpret , ExplicitAutoRepeat , ExplicitBehavior , ExplicitVModMap }
KB_INDICATORMASK | CARD32, each bit corresponds to an indicator
KB_IMFLAGS | { IM_NoExplicit , IM_NoAutomatic , IM_LEDDrivesKB }
KB_IMMODSWHICH | { IM_UseNone , IM_UseBase , IM_UseLatched , IM_UseLocked , IM_UseEffective , IM_UseCompat }
KB_IMGROUPSWHICH | { IM_UseNone , IM_UseBase , IM_UseLatched , IM_UseLocked , IM_UseEffective }
KB_INDICATORMAP | [ flags: CARD8, mods: KB_MODDEF, whichMods: groups: KB_GROUPMASK, whichGroups: ctrls: KB_BOOLCTRLMASK ]
KB_SYMINTERPMATCH | { SI_NoneOf , SI_AnyOfOrNone , SI_AnyOf , SI_AllOf , SI_Exactly }
KB_SYMINTERP | [ sym: KEYSYM, mods; KEYMASK, levelOneOnly: BOOL, match: KB_SYMINTERPMATCH, virtualMod: CARD8, autoRepeat: BOOL, lockingKey: BOOL ]
KB_PCFMASK | { PCF_DetectableAutorepeat , PCF_GrabsUseXkbState , PCF_AutoResetControls , PCF_LookupStateWhenGrabbed , PCF_SendEventUsesXKBState }
KB_LCFLAGSMASK | { LC_Hidden , LC_Default , LC_Partial }
KB_LCSYMFLAGSMASK | { LC_AlphanumericKeys , LC_ModifierKeys , LC_KeypadKeys , LC_FunctionKeys , LC_AlternateGroup }

These types are used by the XkbGetGeometry and XkbSetGeometry requests:

Name | Value
--- | ---
KB_PROPERTY | [ name, value: STRING8 ]
KB_POINT | [ x, y: CARD16 ]
KB_OUTLINE | [ cornerRadius: CARD8, points: LISTofKB_POINT ]
KB_SHAPE | [ name: ATOM, outlines: LISTofKB_OUTLINE primaryNdx, approxNdx: CARD8 ]
KB_KEYNAME | [ name: LISTofCHAR ]
KB_KEYALIAS | [ real: LISTofCHAR, alias: LISTofCHAR ]
KB_KEY | [ name: KB_KEYNAME, gap: INT16, shapeNdx, colorNdx: CARD8 ]
KB_ROW | [ top, left: INT16, vertical: BOOL, keys LISTofKB_KEY ]
KB_OVERLAYKEY | [ over, under: KB_KEYNAME ]
KB_OVERLAYROW | [ rowUnder: CARD8, keys: LISTofKB_OVERLAYKEY ]
KB_OVERLAY | [ sectionUnder: CARD8, rows: LISTofKB_OVERLAYROW ]
KB_SHAPEDOODAD | [ name: ATOM, priority: CARD8, top, left: INT16, type: { SolidDoodad, OutlineDoodad }, angle: INT16, width, height: CARD16 colorNdx, shapeNdx: CARD8 ]
KB_TEXTDOODAD | [ name: ATOM, priority: CARD8, top, left: INT16, angle: INT16, width, height: CARD16, colorNdx: CARD8, text: STRING8, font: STRING8 ]
KB_INDICATORDOODAD | [ name: ATOM, priority: CARD8, top, left: INT16, angle: INT16, shapeNdx, onColorNdx, offColorNdx: CARD8 ]
KB_LOGODOODAD | [ name: ATOM, priority: CARD8, top, left: INT16, angle: INT16, colorNdx, shapeNdx: CARD8, logoName: STRING8 ]
KB_DOODAD | KB_SHAPEDOODAD, or KB_TEXTDOODAD, or KB_INDICATORDOODAD, or KB_LOGODOODAD
KB_SECTION | [ name: ATOM, top, left, angle: INT16, width, height: CARD16, priority: CARD8, rows: LISTofKB_ROW, doodads: LISTofKB_DOODAD, overlays: LISTofKB_OVERLAY ]

These types are used by XkbGetDeviceInfo and XkbSetDeviceInfo :

Name | Value
--- | ---
KB_XIDEVFEATUREMASK | { XI_ButtonActions , XI_IndicatorNames , XI_IndicatorMaps , XI_IndicatorState }
KB_XIFEATUREMASK | { KB_XIDEVFEATURES or XI_Keyboards
KB_XIDETAILMASK | { KB_XIFEATURES or XI_UnsupportedFeature }
KB_DEVICELEDINFO | [ ledClass: KB_LEDCLASSSPEC, ledID: KB_IDSPEC, physIndicators: CARD32, state: CARD32, names: LISTofATOM, maps: LISTofKB_INDICATORMAP ]

## Requests

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

### Initializing the X Keyboard Extension

XkbUseExtension
wantedMajor, wantedMinor: CARD16
supported: BOOL
serverMajor, serverMinor: CARD16

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.

### Selecting Events

XkbSelectEvents
deviceSpec: KB_DEVICESPEC
affectWhich, clear, selectAll: KB_EVENTTYPE
affectMap, map: KB_MAPPARTMASK
details: LISTofITEMs
Errors: Keyboard , Match , Value

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:

- If the event type is also set in clear , the detail mask for the corresponding event is set to 0 or False , as appropriate.

- If the event type is also set in selectAll , the detail mask for the corresponding event is set to include all legal detail values for that type.

- If the event type is not set in either clear or selectAll , the corresponding element of details lists a set of explicit changes to the details mask for the event, as described below.

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:

Event Type | Legal Details | Type
--- | --- | ---
XkbNewKeyboardNotify | KB_NKNDETAILSMASK | CARD16
XkbStateNotify | KB_STATEPARTMASK | CARD16
XkbControlsNotify | KB_CONTROLMASK | CARD32
XkbIndicatorMapNotify | KB_INDICATORMASK | CARD32
XkbIndicatorStateNotify | KB_INDICATORMASK | CARD32
XkbNamesNotify | KB_NAMEDETAILMASK | CARD16
XkbCompatMapNotify | KB_CMDETAILMASK | CARD8
XkbBellNotify | KB_BELLDETAILMASK | CARD8
XkbActionMessage | KB_MSGDETAILMASK | CARD8
XkbAccessXNotify | KB_AXNDETAILMASK | CARD16
XkbExtensionDeviceNotify | KB_XIDETAILMASK | CARD16

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. Events describes all XKB events and the conditions under which the server generates them.

### Generating Named Keyboard Bells

XkbBell
deviceSpec: KB_DEVICESPEC
bellClass: KB_BELLCLASSSPEC
bellID: KB_IDSPEC
percent: INT8
forceSound: BOOL
eventOnly: BOOL
pitch, duration: INT16
name: ATOM
window: WINDOW
Errors: Keyboard , Value , Match

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.

### Querying and Changing Keyboard State

XkbGetState
deviceSpec: KB_DEVICESPEC
deviceID: CARD8
mods, baseMods, latchedMods, lockedMods: KEYMASK
group, lockedGroup: KB_GROUP
baseGroup, latchedGroup: INT16
compatState: KEYMASK
grabMods, compatGrabMods: KB_GROUP
lookupMods, compatLookupMods: KEYMASK
ptrBtnState: BUTMASK
Errors: Keyboard

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. 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 Group Compatibility Map.

XkbLatchLockState
deviceSpec: KB_DEVICESPEC
affectModLocks, modLocks: KEYMASK
lockGroup: BOOL
groupLock: KB_GROUP
affectModLatches,modLatches: KEYMASK
latchGroup: BOOL
groupLatch: INT16
Errors: Keyboard , Value

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.

### Querying and Changing Keyboard Controls

XkbGetControls
deviceSpec: KB_DEVICESPEC
deviceID: CARD8
mouseKeysDfltBtn: CARD8
numGroups: CARD8
groupsWrap: KB_GROUPINFO
internalMods,ignoreLockMods: KB_MODDEF
repeatDelay,repeatInterval: CARD16
slowKeysDelay, debounceDelay: CARD16
mouseKeysDelay, mouseKeysInterval: CARD16
mouseKeysTimeToMax, mouseKeysMaxSpeed: CARD16
mouseKeysCurve: INT16
accessXOptions: KB_AXOPTIONMASK
accessXTimeout: CARD16
accessXTimeoutOptionsMask, accessXTimeoutOptionValues: CARD16
accessXTimeoutMask,accessXTimeoutValues: CARD32
enabledControls: KB_BOOLCTRLMASK
perKeyRepeat: LISTofCARD8
Errors: Keyboard

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 Key Symbol Map. The internalMods and ignoreLockMods return values report the current values of the server internal and ignore locks modifiers as described in Keyboard State. Both are modifier definitions ( 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 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.

XkbSetControls
deviceSpec: KB_DEVICESPEC
affectInternalRealMods, internalRealMods: KEYMASK
affectInternalVirtualMods,internalVirtualMods: KB_VMODMASK
affectIgnoreLockRealMods,ignoreLockRealMods: KB_MODMASK
affectIgnoreLockVirtualMods,ignoreLockVirtualMods: KB_VMODMASK
mouseKeysDfltBtn: CARD8
groupsWrap: KB_GROUPINFO
accessXOptions: CARD16
affectEnabledControls: KB_BOOLCTRLMASK
enabledControls: KB_BOOLCTRLMASK
changeControls: KB_CONTROLMASK
repeatDelay,repeatInterval: CARD16
slowKeysDelay, debounceDelay: CARD16
mouseKeysDelay, mouseKeysInterval: CARD16
mouseKeysTimeToMax, mouseKeysMaxSpeed: CARD16
mouseKeysCurve: INT16
accessXTimeout: CARD16
accessXTimeoutMask, accessXTimeoutValues: KB_BOOLCTRLMASK
accessXTimeoutOptionsMask,accessXTimeoutOptionsValues: CARD16
perKeyRepeat: LISTofCARD8
Errors: Keyboard , Value

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:

Bit in changeControls | Field(s) to be Applied
--- | ---
XkbRepeatKeysMask | repeatDelay , repeatInterval
XkbSlowKeysMask | slowKeysDelay
XkbStickyKeysMask | accessXOptions (only the XkbAX_TwoKeys and the XkbAX_LatchToLock options are affected)
XkbBounceKeysMask | debounceDelay
XkbMouseKeysMask | mouseKeysDfltBtn
XkbMouseKeysAccelMask | mouseKeysDelay , mouseKeysInterval , mouseKeysCurve , mouseKeysTimeToMax , mouseKeysMaxSpeed
XkbAccessXKeysMask | accessXOptions (all options)
XkbAccessXTimeoutMask | accessXTimeout , accessXTimeoutMask , accessXTimeoutValues , accessXTimeoutOptionsMask , accessXTimeoutOptionsValues
XkbAccessXFeedbackMask | accessXOptions (all options except those affected by the XkbStickyKeysMask bit)
XkbGroupsWrapMask | groupsWrap
XkbInternalModsMask | affectInternalRealMods , internalRealMods , affectInternalVirtualMods , internalVirtualMods
XkbIgnoreLockModsMask | affectIgnoreLockRealMods , ignoreLockRealMods , affectIgnoreLockVirtualMods , ignoreLockVirtualMods
XkbPerKeyRepeatMask | perKeyRepeat
XkbControlsEnabledMask | affectEnabledControls , enabledControls

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

### Querying and Changing the Keyboard Mapping

XkbGetMap
deviceSpec: KB_DEVICESPEC
full, partial: KB_MAPPARTMASK
firstType, nTypes: CARD8
firstKeySym, firstKeyAction: KEYCODE
nKeySyms, nKeyActions: CARD8
firstKeyBehavior,firstKeyExplicit: KEYCODE
nKeyBehaviors,nKeyExplicit: CARD8
firstModMapKey,firstVModMapKey: KEYCODE
nModMapKeys, nVModMapKeys: CARD8
virtualMods: KB_VMODMASK
deviceID: CARD8
minKeyCode, maxKeyCode: KEYCODE
present: KB_MAPPARTMASK
firstType, nTypes, nTotalTypes: CARD8
firstKeySym, firstKeyAction: KEYCODE
nKeySyms, nKeyActions: CARD8
totalSyms, totalActions: CARD16
firstKeyBehavior, firstKeyExplicit: KEYCODE
nKeyBehaviors, nKeyExplicit: CARD8
totalKeyBehaviors, totalKeyExplicit: CARD8
firstModMapKey, firstVModMapKey: KEYCODE
nModMapKeys, nVModMapKeys: CARD8
totalModMapKeys, totalVModMapKeys: CARD8
virtualMods: KB_VMODMASK
typesRtrn: LISTofKB_KEYTYPE
symsRtrn: LISTofKB_KEYSYMMAP
actsRtrn: { count: LISTofCARD8, acts: LISTofKB_ACTION }
behaviorsRtrn: LISTofKB_SETBEHAVIOR
vmodsRtrn: LISTofSETofKEYMASK
explicitRtrn: LISTofKB_SETEXPLICIT
modmapRtrn: LISTofKB_KEYMODMAP
vmodMapRtrn: LISTofKB_KEYVMODMAP
Errors: Keyboard , Value , Match , Alloc

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:

Bit in the Partial Mask | Type | Corresponding Field(s)
--- | --- | ---
XkbKeyTypesMask | key types | firstType , nTypes
XkbKeySymsMask | keycodes | firstKeySym , nKeySyms
XkbKeyActionsMask | keycodes | firstKeyAction , nKeyActions
XkbKeyBehaviorsMask | keycodes | firstKeyBehavior , nKeyBehaviors
XkbExplicitComponentsMask | keycodes | firstKeyExplicit , nKeyExplicit
XkbModifierMapMask | keycodes | firstModMapKey , nModMapKeys
XkbVirtualModMapMask | keycodes | firstVModMapKey , nVModMapKeys
XkbVirtualModsMask | virtual modifiers | virtualMods

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 :

- firstType and nTypes specify the types reported in the reply.

- nTotalTypes reports the total number of types defined for the keyboard

- typesRtrn has nTypes elements of type KB_KEYTYPE which describe consecutive key types starting from firstType .

If XkbKeySymsMask is set in present :

- firstKeySym and nKeySyms specify the subset of the keyboard keys for which symbols will be reported.

- totalSyms reports the total number of keysyms bound to the keys returned in this reply.

- symsRtrn has nKeySyms elements of type KB_KEYSYMMAP, which describe the symbols bound to consecutive keys starting from firstKeySym .

If XkbKeyActionsMask is set in present :

- firstKeyAction and nKeyActions specify the subset of the keys for which actions are reported.

- totalActions reports the total number of actions bound to the returned keys.

- The count field of the actsRtrn return value has nKeyActions entries of type CARD8, which specify the number of actions bound to consecutive keys starting from firstKeyAction . The acts field of actsRtrn has totalActions elements of type KB_ACTION and specifies the actions bound to the keys.

If XkbKeyBehaviorsMask is set in present :

- The firstKeyBehavior and nKeyBehaviors return values report the range of keyboard keys for which behaviors will be reported.

- The totalKeyBehaviors return value reports the number of keys in the range to be reported that have non-default values.

- The behaviorsRtrn value has totalKeyBehaviors entries of type KB_BEHAVIOR. Each entry specifies a key in the range for which behaviors are being reported and the behavior associated with that key. Any keys in that range that do not have an entry in behaviorsRtrn have the default behavior, KB_Default .

If XkbExplicitComponentsMask is set in present :

- The firstKeyExplicit and nKeyExplicit return values report the range of keyboard keys for which the set of explicit components is to be returned.

- The totalKeyExplicit return value reports the number of keys in the range specified by firstKeyExplicit and nKeyExplicit that have one or more explicit components.

- The explicitRtrn return value has totalKeyExplicit entries of type KB_KEYEXPLICIT. Each entry specifies the a key in the range for which explicit components are being reported and the explicit components that are bound to it. Any keys in that range that do not have an entry in explicitRtrn have no explicit components.

If XkbModifierMapMask is set in present :

- The firstModMapKey and nModMapKeys return values report the range of keyboard keys for which the modifier map is to be reported.

- The totalModMapKeys return value reports the number of keys in the range specified by firstModMapKey and nModMapKeys that are bound with to one or more modifiers.

- The modmapRtrn return value has totalModMapKeys entries of type KB_KEYMODMAP. Each entry specifies the a key in the range for which the modifier map is being reported and the set of modifiers that are bound to that key. Any keys in that range that do not have an entry in modmapRtrn are not associated with any modifiers by the modifier mapping.

If XkbVirtualModMapMask is set in present :

- The firstVModMapKey and nVModMapKeys return values report the range of keyboard keys for which the virtual modifier map is to be reported.

- The totalVModMapKeys return value reports the number of keys in the range specified by firstVModMapKey and nVModMapKeys that are bound with to or more virtual modifiers.

- The vmodmapRtrn return value has totalVModMapKeys entries of type KB_KEYVMODMAP. Each entry specifies the a key in the range for which the virtual modifier map is being reported and the set of virtual modifiers that are bound to that key. Any keys in that range that do not have an entry in vmodmapRtrn are not associated with any virtual modifiers,

If XkbVirtualModsMask is set in present :

- The virtualMods return value is a mask with one bit per virtual modifier which specifies the virtual modifiers for which a set of corresponding real modifiers is to be returned.

- The vmodsRtrn return value is a list with one entry of type KEYBUTMASK for each virtual modifier that is specified in virtualMods . The entries in vmodsRtrn contain the real modifier bindings for the specified virtual modifiers, beginning with the lowest-numbered virtual modifier that is present in virtualMods and proceeding to the highest.

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.

XkbSetMap
deviceSpec: KB_DEVICESPEC
flags: { SetMapResizeTypes, SetMapRecomputeActions }
present: KB_MAPPARTMASK
minKeyCode, maxKeyCode: KEYCODE
firstType, nTypes: CARD8
firstKeySym, firstKeyAction: KEYCODE
nKeySyms, nKeyActions: CARD8
totalSyms, totalActions: CARD16
firstKeyBehavior, firstKeyExplicit: KEYCODE
nKeyBehaviors, nKeyExplicit: CARD8
totalKeyBehaviors, totalKeyExplicit: CARD8
firstModMapKey, firstVModMapKey: KEYCODE
nModMapKeys, nVModMapKeys: CARD8
totalModMapKeys, totalVModMapKeys: CARD8
virtualMods: VMODMASK
types: LISTofKB_KEYTYPE
syms: LISTofKB_KEYSYMMAP
actions: { count: LISTofCARD8, actions: LISTofKB_ACTION }
behaviors: LISTofKB_BEHAVIOR
vmods: LISTofKEYMASK
explicit: LISTofKB_EXPLICIT
modmap: LISTofKB_KEYMODMAP
vmodmap: LISTofKB_KEYVMODMAP
Errors: Keyboard , Value , Match , Alloc

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

- The numLevels for the type must be greater than zero.

- If the key type is ONE_LEVEL (i.e. index zero in the list of key types), numLevels must be one.

- If the key type is TWO_LEVEL or KEYPAD , or ALPHABETIC (i.e. index one, two, or three in the lest of key types) group width must be two.

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:

- Each map entry must specify a resulting level that is legal for the type.

- Any real or virtual modifiers specified in any of the map entries must also be specified in the mods for the type.

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:

- The key type indices must specify legal result key types.

- The number of groups specified by groupInfo must be in the range 0…4 .

- The width of the key symbol map must be equal to numLevels of the widest key type bound to the key.

- The number of symbols, nSyms , must equal the number of groups times width .

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:

- Specify a key in the range indicated by firstKeyBehavior and nKeyBehaviors .

- Not specify the permanent flag; permanent behaviors cannot be set or changed using the XkbSetMap request.

- If present, the KB_Overlay1 and KB_Overlay2 behaviors must specify a keycode for the overlay key that is valid for the current keyboard.

- If present, the KB_RadioGroup behavior must specify a legal index (0…31) for the radio group to which the key belongs.

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

### Querying and Changing the Compatibility Map

XkbGetCompatMap
deviceSpec: KB_DEVICESPEC
groups: KB_GROUPMASK
getAllSI: BOOL
firstSI, nSI: CARD16
deviceID: CARD8
groupsRtrn: KB_GROUPMASK
firstSIRtrn, nSIRtrn, nTotalSI: CARD16
siRtrn: LISTofKB_SYMINTERP
groupRtrn: LISTofKB_MODDEF
Errors: Keyboard , Match , Alloc

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.

The groups mask specifies the groups for which compatibility maps are to be returned.

The nTotalSI return value reports the total number of symbol interpretations defined for the keyboard. On successful return, the siRtrn return list contains the definitions for nSIRtrn symbol interpretations beginning at firstSIRtrn .

The groupRtrn return values report the entries in the group compatibility map for any groups specified in the groupsRtrn return value.

XkbSetCompatMap
deviceSpec: KB_DEVICESPEC
recomputeActions: BOOL
truncateSI: BOOL
groups: KB_GROUPMASK
firstSI, nSI: CARD16
si: LISTofKB_SYMINTERPRET
groupMaps: LISTofKB_MODDEF
Errors: Keyboard , Match , Value , Alloc

This request changes a specified subset of the compatibility map of the keyboard indicated by deviceSpec . If deviceSpec specifies an invalid device, a Keyboard error results and nothing is changed.

The firstSI and nSI fields specify a subset of the keyboard symbol interpretations to be changed. The si list specifies new values for each of the interpretations in that range.

The first symbol interpretation to be changed, firstSI , must be less than or equal to the unchanged length of the list of symbol interpretations, or a Value error results. If the resulting list would be larger than the unchanged list, it server list of symbol interpretations is automatically increased in size. Otherwise, if truncateSyms is True , the server deletes any symbol interpretations after the last element changed by this request, and reduces the length of the list accordingly.

The groupMaps fields contain new definitions for a subset of the group compatibility map; groups specifies the group compatibility map entries to be updated from groupMaps .

All changed compatibility maps and symbol interpretations must either ignore group state or specify a legal range of groups, or a Value error results.

If the recomputeActions field is True , the server regenerates recalculates the actions bound to all keyboard keys by applying the new symbol interpretations to the entire key symbol map, as described in Assigning Actions To Keys.

### Querying and Changing Indicators

XkbGetIndicatorState
deviceSpec: KB_DEVICESPEC
deviceID: CARD8 state: KB_INDICATORMASK
Errors: Keyboard

This request reports the current state of the indicators for the keyboard specified by deviceSpec . If deviceSpec does not specify a valid keyboard, a Keyboard error results.

On 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 state return value reports the state of each of the thirty-two indicators on the specified keyboard. The least-significant bit corresponds to indicator 0, the most significant bit to indicator 31; if a bit is set, the corresponding indicator is lit.

XkbGetIndicatorMap
deviceSpec: KB_DEVICESPEC
which: KB_INDICATORMASK
deviceID: CARD8
which: KB_INDICATORMASK
realIndicators: KB_INDICATORMASK
nIndicators: CARD8
maps: LISTofKB_INDICATORMAP
Errors: Keyboard , Value

This request returns a subset of the maps for the indicators on the keyboard specified by deviceSpec . If deviceSpec does not specify a valid keyboard device, a Keyboard error results.

The which field specifies the subset to be returned; a set bit in the which field indicates that the map for the corresponding indicator should be returned.

On successful return, the deviceID field reports the input extension identifier of the keyboard or 0 if the server does not support the input extension. Any indicators specified in realIndicators are 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 XkbIndicatorStateNotify events.

The maps return value reports the requested indicator maps. Indicator maps are described in Indicator Maps

XkbSetIndicatorMap
deviceSpec: KB_DEVICESPEC
which: KB_INDICATORMASK
maps: LISTofKB_INDICATORMAP
Errors: Keyboard , Value

This request changes a subset of the maps on the keyboard specified by deviceSpec . If deviceSpec does not specify a valid keyboard device, a Keyboard error results.

The which field specifies the subset to be changed; the maps field contains the new definitions.

If successful, the new indicator maps are applied immediately. If any indicators change state as a result of the new maps, the server generates XkbIndicatorStateNotify events as appropriate.

XkbGetNamedIndicator
deviceSpec: KB_DEVICESPEC
ledClass: KB_LEDCLASSSPEC
ledID: KB_IDSPEC
indicator: ATOM
deviceID: CARD8
supported: BOOL
indicator: ATOM
found: BOOL
on: BOOL
realIndicator: BOOL
ndx: CARD8
map: KB_INDICATORMAP
Errors: Keyboard , Atom , Value

This request returns information about the indicator specified by ledClass , ledID , and indicator on the keyboard specified by deviceSpec . The indicator field specifies the name of the indicator for which information is to be returned.

If deviceSpec does not specify a device with indicators, a Keyboard error results. If ledClass does not have the value DfltXIClass , LedFeedbackClass , or KbdFeedbackClass , a Value error results. If ledID does not have the value DfltXIId or specify the identifier of a feedback of the class specified by ledClass on the device specified by deviceSpec , a Match error results. If indicator is not a valid ATOM other than None , an Atom error results.

This request is always supported with default class and identifier on the core keyboard device. If the request specifies a device other than the core keyboard device or a feedback class and identifier other than the defaults, and the server does not support indicator names or indicator maps for extension devices, the supported return value is False and the values of the other fields in the reply are undefined. If the client which issued the unsupported request has also selected to do so, it will also receive an XkbExtensionDeviceNotify event which reports the attempt to use an unsupported feature, in this case one or both of XkbXI_IndicatorMaps or XkbXI_IndicatorNames .

Otherwise, supported is True and the deviceID field reports the input extension identifier of the keyboard or 0 if the server does not support the input extension. The indicator return value reports the name for which information was requested and the found return value is True if an indicator with the specified name was found on the device.

If a matching indicator was found:

- The on return value reports the state of the indicator at the time of the request.

- The realIndicator return value is True if the requested indicator is actually present on the keyboard or False if it is virtual.

- The ndx return value reports the index of the indicator in the requested feedback.

- The map return value reports the indicator map used by to automatically change the state of the specified indicator in response to changes in keyboard state or controls.

If no matching indicator is found, the found return value is False , and the on , realIndicator , ndx , and map return values are undefined.

XkbSetNamedIndicator
deviceSpec: KB_DEVICESPEC
ledClass: KB_LEDCLASSSPEC
ledID: KB_IDSPEC
indicator: ATOM
setState: BOOL
on: BOOL
setMap: BOOL
createMap: BOOL
map: KB_SETINDICATORMAP
Errors: Keyboard , Atom , Access

This request changes various aspects of the indicator specified by ledClass , ledID , and indicator on the keyboard specified by deviceSpec . The indicator argument specifies the name of the indicator to be updated.

If deviceSpec does not specify a device with indicators, a Keyboard error results. If ledClass does not have the value DfltXIClass , LedFeedbackClass , or KbdFeedbackClass , a Value error results. If ledID does not have the value DfltXIId or specify the identifier of a feedback of the class specified by ledClass on the device specified by deviceSpec , a Match error results. If indicator is not a valid ATOM other than None , an Atom error results.

This request is always supported with default class and identifier on the core keyboard device. If the request specifies a device other than the core keyboard device or a feedback class and identifier other than the defaults, and the server does not support indicator names or indicator maps for extension devices, the supported return value is False and the values of the other fields in the reply are undefined. If the client which issued the unsupported request has also selected to do so, it will also receive an XkbExtensionDeviceNotify event which reports the attempt to use an unsupported feature, in this case one or both of XkbXI_IndicatorMaps and XkbXI_IndicatorNames .

Otherwise, supported is True and the deviceID field reports the input extension identifier of the keyboard or 0 if the server does not support the input extension. The indicator return value reports the name for which information was requested and the found return value is True if an indicator with the specified name was found on the device.

If no indicator with the specified name is found on the specified device, and the createMap field is True , XKB assigns the specified name to the lowest-numbered indicator that has no name (i.e. whose name is None ) and applies the rest of the fields in the request to the newly named indicator. If no unnamed indicators remain, this request reports no error and has no effect.

If no matching indicator is found or new indicator assigned this request reports no error and has no effect. Otherwise, it updates the indicator as follows:

If setMap is True , XKB changes the map for the indicator (see Indicator Maps) to reflect the values specified in map .

If setState is True , XKB attempts to explicitly change the state of the indicator to the state specified in on . The effects of an attempt to explicitly change the state of an indicator depend on the values in the map for that indicator and are not guaranteed to succeed.

If this request affects both indicator map and state, it updates the indicator map before attempting to change its state, so the success of the explicit change depends on the indicator map values specified in the request.

If this request changes the indicator map, it applies the new map immediately to determine the appropriate state for the indicator given the new indicator map and the current state of the keyboard.

### Querying and Changing Symbolic Names

XkbGetNames
deviceSpec: KB_DEVICESPEC
which: KB_NAMEDETAILMASK
deviceID: CARD8 which: KB_NAMESMASK minKeyCode, maxKeyCode: KEYCODE nTypes: CARD8 nKTLevels: CARD16 groupNames: KB_GROUPMASK virtualMods: KB_VMODMASK firstKey: KEYCODE nKeys: CARD8 indicators: KB_INDICATORMASK nRadioGroups, nKeyAliases: CARD8 present: KB_NAMEDETAILMASK valueList: LISTofITEMs
Errors: Keyboard , Value

This request returns the symbolic names for various components of the keyboard mapping for the device specified by deviceSpec . The which field specifies the keyboard components for which names are to be returned. If deviceSpec does not specify a valid keyboard device, a Keyboard error results. If any undefined bits in which are non-zero, a Value error results.

The deviceID return value contains the X Input Extension device identifier of the specified device or 0 if the server does not support the input extension. The present and valueList return values specify the components for which names are being reported. If a component is specified in present , the corresponding element is present in the valueList , otherwise that component has length 0 . The components of the valueList appear in the following order, when present:.

Component | Size | Type
--- | --- | ---
XkbKeycodesName | 1 | ATOM
XkbGeometryName | 1 | ATOM
XkbSymbolsName | 1 | ATOM
XkbPhysSymbolsName | 1 | ATOM
XkbTypesName | 1 | ATOM
XkbCompatName | 1 | ATOM
XkbKeyTypeNames | nTypes | LISTofATOM
XkbKTLevelNames | nTypes , nKTLevels | { count: LISTofCARD8, names: LISTofATOM }
XkbIndicatorNames | One per bit set in indicators | LISTofATOM
XkbVirtualModNames | One per bit set in virtualMods | LISTofATOM
XkbGroupNames | One per bit set in groupNames | LISTofATOM
XkbKeyNames | nKeys | LISTofKB_KEYNAME
XkbKeyAliases | nKeyAliases | LISTofKB_KEYALIAS
XkbRGNames | nRadioGroups | LISTofATOM

If type names are reported, the nTypes return value reports the number of types defined for the keyboard, and the list of key type names in valueList has nTypes elements.

If key type level names are reported, the list of key type level names in the valueList has two parts: The count array has nTypes elements, each of which reports the number of level names reported for the corresponding key type. The names array has nKTLevels atoms and reports the names of each type sequentially. The nKTLevels return value is always equal to the sum of all of the elements of the count array.

If indicator names are reported, the indicators mask specifies the indicators for which names are defined; any indicators not specified in indicators have the name None . The list of indicator names in valueList contains the names of the listed indicators, beginning with the lowest-numbered indicator for which a name is defined and proceeding to the highest.

If virtual modifier names are reported, the virtualMods mask specifies the virtual modifiers for which names are defined; any virtual modifiers not specified in virtualMods have the name None . The list of virtual modifier names in valueList contains the names of the listed virtual modifiers, beginning with the lowest-numbered virtual modifier for which a name is defined and proceeding to the highest.

If group names are reported, the groupNames mask specifies the groups for which names are defined; any groups not specified in groupNames have the name None . The list of group names in valueList contains the names of the listed groups, beginning with the lowest-numbered group for which a name is defined and proceeding to the highest.

If key names are reported, the firstKey and nKeys return values specify a range of keys which includes all keys for which names are defined; any key that does not fall in the range specified by firstKey and nKeys has the name NullKeyName . The list of key names in the valueList has nKeys entries and specifies the names of the keys beginning at firstKey .

If key aliases are reported, the nKeyAliases return value specifies the total number of key aliases defined for the keyboard. The list of key aliases in valueList has nKeyAliases entries, each of which reports an alias and the real name of the key to which it corresponds.

If radio group names are reported, the nRadioGroups return value specifies the number of radio groups on the keyboard for which names are defined. The list of radio group names in valueList reports the names of each group and has nRadioGroups entries.

XkbSetNames
deviceSpec: KB_DEVICESPEC
which: KB_NAMEDETAILMASK
virtualMods: KB_VMODMASK
firstType, nTypes: CARD8
firstKTLevel, nKTLevels: CARD8
totalKTLevelNames: CARD16
indicators: KB_INDICATORMASK
groupNames: KB_GROUPMASK
nRadioGroups: CARD8
firstKey: KEYCODE
nKeys, nKeyAliases: CARD8
valueList: LISTofITEMs
Errors: Keyboard , Atom , Value , Match , Alloc

This request changes the symbolic names for the requested components of the keyboard specified by deviceSpec . The which field specifies the components for which one or more names are to be updated. If deviceSpec does not specify a valid keyboard device, a Keyboard error results. If any undefined bits in which are non-zero, a Value error results. If any error (other than Alloc or Implementation ) occurs, this request returns without modifying any names.

The which and valueList fields specify the components to be changed; the type of each valueList entry, the order in which components appear in the valueList when specified, and the correspondence between components in which and the entries in the valueList are as specified for the XkbGetNames request.

If keycodes, geometry, symbols, physical symbols, types or compatibility map names are to be changed, the corresponding entries in the valueList must have the value None or specify a valid ATOM, else an Atom error occurs.

If key type names are to be changed, the firstType and nTypes fields specify a range of types for which new names are supplied, and the list of key type names in valueList has nTypes elements. Names for types that fall outside of the range specified by firstType and nTypes are not affected. If this request specifies names for types that are not present on the keyboard, a Match error results. All of the type names in the valueList must be valid ATOMs or have the value None , or an Atom error results.

The names of the first four keyboard types are specified by the XKB extension and cannot be changed; including any of the canonical types in this request causes an Access error, as does trying to assign the name reserved for a canonical type to one of the other key types.

If key type level names are to be changed, the firstKTLevel and nKTLevels fields specify a range of key types for which new level names are supplied, and the list of key type level names in the valueList has two parts: The count array has nKTLevels elements, each of which specifies the number of levels for which names are supplied on the corresponding key type; any levels for which no names are specified are assigned the name None . The names array has totalKTLevels atoms and specifies the names of each type sequentially. The totalKTLevels field must always equal the sum of all of the elements of the count array. Level names for types that fall outside of the specified range are not affected. If this request specifies level names for types that are not present on the keyboard, or if it specifies more names for a type than the type has levels, a Match error results. All specified type level names must be None or a valid ATOM or an Atom error results.

If indicator names are to be changed, the indicators mask specifies the indicators for which new names are specified; the names for indicators not specified in indicators are not affected. The list of indicator names in valueList contains the new names for the listed indicators, beginning with the lowest-numbered indicator for which a name is defined and proceeding to the highest. All specified indicator names must be a valid ATOM or None , or an Atom error results.

If virtual modifier names are to be changed, the virtualMods mask specifies the virtual modifiers for which new names are specified; names for any virtual modifiers not specified in virtualMods are not affected. The list of virtual modifier names in valueList contains the new names for the specified virtual modifiers, beginning with the lowest-numbered virtual modifier for which a name is defined and proceeding to the highest. All virtual modifier names must be valid ATOMs or None , or an Atom error results.

If group names are to be changed, the groupNames mask specifies the groups for which new names are specified; the name of any group not specified in groupNames is not changed. The list of group names in valueList contains the new names for the listed groups, beginning with the lowest-numbered group for which a name is defined and proceeding to the highest. All specified group names must be a valid ATOM or None , or an Atom error results.

If key names are to be changed, the firstKey and nKeys fields specify a range of keys for which new names are defined; the name of any key that does not fall in the range specified by firstKey and nKeys is not changed. The list of key names in the valueList has nKeys entries and specifies the names of the keys beginning at firstKey .

If key aliases are to be changed, the nKeyAliases field specifies the length of a new list of key aliases for the keyboard. The list of key aliases can only be replaced in its entirety; it cannot be replaced. The list of key aliases in valueList has nKeyAliases entries, each of which reports an alias and the real name of the key to which it corresponds.

XKB does not check key names or aliases for consistency and validity, so applications should take care not to assign duplicate names or aliases

If radio group names are to be changed, the nRadioGroups field specifies the length of a new list of radio group names for the keyboard. There is no way to edit the list of radio group names; it can only be replaced in its entirety. The list of radio group names in valueList reports the names of each group and has nRadioGroups entries. If the list of radio group names specifies names for more radio groups than XKB allows (32), a Match error results. All specified radio group names must be valid ATOMs or have the value None , or an Atom error results.

### Querying and Changing Keyboard Geometry

XkbGetGeometry
deviceSpec: KB_DEVICESPEC
name: ATOM
deviceID: CARD8
name: ATOM
found: BOOL
widthMM, heightMM: CARD16
baseColorNdx, labelColorNdx: CARD8
properties: LISTofKB_PROPERTY
colors: LISTofSTRING8
shapes: LISTofKB_SHAPE
sections: LISTofKB_SECTION
doodads: LISTofKB_DOODAD
keyAliases: LISTofKB_KEYALIAS
Errors: Keyboard

This request returns a description of the physical layout of a keyboard. If the name field has the value None , or if name is identical to the name of the geometry for the keyboard specified by deviceSpec , this request returns the geometry of the keyboard specified by deviceSpec ; otherwise, if name is a valid atom other than None , the server returns the keyboard geometry description with that name in the server database of keyboard components (see The Server Database of Keyboard Components) if one exists. If deviceSpec does not specify a valid keyboard device, a Keyboard error results. If name has a value other than None or a valid ATOM, an Atom error results.

On successful return, the deviceID field reports the X Input extension identifier of the keyboard device specified in the request, or 0 if the server does not support the input extension.

The found return value reports whether the requested geometry was available. If found is False , no matching geometry was found and the remaining fields in the request reply are undefined; if found is True , the remaining fields of the reply describe the requested keyboard geometry. The interpretation of the components that make up a keyboard geometry is described in detail in Keyboard Geometry

XkbSetGeometry
deviceSpec: KB_DEVICESPEC
name: ATOM
widthMM, heightMM, CARD16
baseColorNdx, labelColorNdx: CARD8
shapes: LISTofKB_SHAPE
sections: LISTofKB_SECTION
properties: LISTofKB_PROPERTY
colors: LISTofSTRING8
doodads: LISTofKB_DOODAD
keyAliases: LISTofKB_KEYALIAS
Errors: Keyboard , Atom , Value

This request changes the reported description of the geometry for the keyboard specified by deviceSpec . If deviceSpec does not specify a valid keyboard device, a Keyboard error results.

The name field specifies the name of the new keyboard geometry and must be a valid ATOM or an Atom error results. The new geometry is not added to the server database of keyboard components, but it can be retrieved using the XkbGetGeometry request for as long as it is bound to the keyboard. The keyboard geometry symbolic name is also updated from the name field, and an XkbNamesNotify event is generated, if necessary.

The list of colors must include at least two definitions, or a Value error results. All color definitions in the geometry must specify a legal color (i.e. must specify a valid index for one of the entries of the colors list) or a Match error results. The baseColorNdx and the labelColorNdx must be different or a Match error results.

The list of shapes must include at least one shape definition, or a Value error results. If any two shapes have the same name, a Match error result. All doodads and keys which specify shape must specify a valid index for one of the elements of the shapes list, or a Match error results.

All section, shape and doodad names must be valid ATOMs or an Atom error results; the constant None is not permitted for any of these components.

All doodads must be of a known type; XKB does not support "private" doodad types.

If, after rotation, any keys or doodads fall outside of the bounding box for a section, the bounding box is automatically adjusted to the minimum size which encloses all of its components.

If, after adjustment and rotation, the bounding box of any section or doodad extends below zero on either the X or Y axes, the entire geometry is translated so that the minimum extent along either axis is zero.

If, after rotation and translation, any keyboard components fall outside of the rectangle specified by widthMM and heightMM , the keyboard dimensions are automatically resized to the minimum bounding box that surrounds all components. Otherwise, the width and height of the keyboard are left as specified.

The under field of any overlay key definitions must specify a key that is in the section that contains the overlay key, or a Match error results. This request does not check the value of the over field of an overlay key definition, so applications must be careful to avoid conflicts with actual keys.

This request does not verify that key names or aliases are unique. It also does not verify that all key names specified in the geometry are bound to some keycode or that all keys that are named in the keyboard definition are also available in the geometry. Applications should make sure that keyboard geometry has no internal conflicts and is consistent with the other components of the keyboard definition, but XKB does not check for or guarantee it.

### Querying and Changing Per-Client Flags

XkbPerClientFlags
deviceSpec: KB_DEVICESPEC
change: KB_PCFMASK
value: KB_PCFMASK
ctrlsToChange: KB_BOOLCTRLMASK
autoCtrls: KB_BOOLCTRLMASK
autoCtrlValues: KB_BOOLCTRLMASK
deviceID: CARD8 supported: KB_PCFMASK value: KB_PCFMASK autoCtrls: KB_BOOLCTRLMASK autoCtrlValues: KB_BOOLCTRLMASK where: KB_PCFMASK:
Errors: Keyboard , Value , Match , Alloc

Changes the client specific flags for the keyboard specified by deviceSpec . Reports a Keyboard error if deviceSpec does not specify a valid keyboard device.

Any flags specified in change are set to the corresponding values in value , provided that the server supports the requested control. Legal per-client-flags are:

Flag… | Described in…
--- | ---
XkbPCF_DetectableAutorepeat | Detectable Autorepeat
XkbPCF_GrabsUseXKBStateMask | Setting a Passive Grab for an XKB State
XkbPCF_AutoResetControlsMask | Automatic Reset of Boolean Controls
XkbPCF_LookupStateWhenGrabbed | Effects of XKB on Core Protocol Events
XkbPCF_SendEventUsesXKBState | Sending Events to Clients

If PCF_AutoResetControls is set in both change and value , the client’s mask of controls to be changed is updated from ctrlsToChange , autoCtrls , and autoCtrlValues . Any controls specified in ctrlsToChange are modified in the auto-reset controls mask for the client; the corresponding bits from the autoCtrls field are copied into the auto-reset controls mask and the corresponding bits from autoCtrlValues are copied into the auto-reset controls state values. If any controls are specified in autoCtrlValues but not in autoCtrls , a Match error results. If any controls are specified in autoCtrls but not in ctrlsToChange , a Match error results.

If PCF_AutoResetControls is set in change but not in value , the client’s mask of controls to be changed is reset to all zeroes (i.e. the client does not change any controls when it exits).

This request reports a Match error if a bit is set in any of the value masks but not in the control mask that governs it or a Value error if any undefined bits are set in any of the masks.

On successful return, the deviceID field reports the X Input extension identifier of the keyboard, or 0 if the server does not support the X Input Extension.

The supported return value reports the set of per-client flags that are supported by the server; in this version of XKB, only the XkbPCF_DetectableAutorepeat per-client flag is optional; all other per-client flags must be supported.

The value return value reports the current settings of all per-client flags for the specified keyboard. The autoCtrls return value reports the current set of controls to be reset when the client exits, while the autoCtrlValues return value reports the state to which they should be set.

### Using the Server’s Database of Keyboard Components

XkbListComponents
deviceSpec: KB_DEVICESPEC
maxNames: CARD16
keymapsSpec: STRING8
keycodesSpec: STRING8
typesSpec: STRING8
compatMapSpec: STRING8
symbolsSpec: STRING8
geometrySpec: STRING8
deviceID: CARD8
extra: CARD16
keymaps,keycodes,types,compatMaps: LISTofKB_COMPONENTNAME
symbols, geometries: LISTofKB_COMPONENTNAME
Where:
KB_COMPONENTNAME { hints: CARD8, name: STRING8 }
Errors: Keyboard , Alloc

This request returns one or more lists of keyboard components that are available from the X server database of keyboard components for the device specified by deviceSpec . The X server is allowed, but not required or expected, to maintain separate databases for each keyboard device. A Keyboard error results if deviceSpec does not specify a valid keyboard device.

The maxNames field specifies the maximum number of component names to be reported, in total, by this request.

The keymapsSpec , keycodesSpec , typesSpec , compatMapSpec , symbolsSpec and geometrySpec request fields specify a pattern to be matched against the names of all components of the corresponding type in the server database of keyboard components.

Each pattern uses the ISO Latin-1 encoding and should contain only parentheses, the wildcard characters "?" and "*" or characters that are permitted in a component class or member name (see Component Names). Illegal characters in a pattern are simply ignored; no error results if a pattern contains illegal characters.

Comparison is case-sensitive and, in a pattern, the "?" wildcard character matches any single character except parentheses while the "*" character matches any number of characters except parentheses. If an implementation accepts characters other than those required by XKB, whether or not those characters match either wildcard is also implementation dependent. An empty pattern does not match any component names.

On successful return, the deviceID return value reports the X Input Extension device identifier of the specified device, or 0 if the server does not support the X input extension. The extra return value reports the number of matching component names that could not be returned due to the setting of the maxNames field in the request.

The keymaps , keycodes , types , compatMaps , symbols and geometries return the hints (see Component Hints) and names of any components from the server database that match the corresponding pattern.

The Server Database of Keyboard Components describes the X server database of keyboard components in more detail.

XkbGetKbdByName
deviceSpec: KB_DEVICESPEC
need, want: KB_GBNDETAILMASK
load: BOOL
keymapsSpec: STRING8
keycodesSpec, typesSpec: STRING8
compatMapSpec, symbolsSpec: STRING8
geometrySpec: STRING8
deviceID: CARD8
minKeyCode, maxKeyCode: KEYCODE
loaded, newKeyboard: BOOL
found, reported: KB_GBNDETAILMASK
map: optional XkbGetMap reply
compat: optional XkbGetCompatMap reply
indicators: optional XkbGetIndicatorMap reply
names: optional XkbGetNames reply
geometry: optional XkbGetGeometry reply
Errors: Keyboard , Access , Alloc

Assembles and returns a keymap from the current mapping and specified elements from the server database of keymap components for the keyboard specified by deviceSpec , and optionally replaces the current keyboard mapping with the newly generated description. If deviceSpec does not specify a valid keyboard device, a Keyboard error results.

The keymapsSpec , keycodesSpec , typesSpec , compatMapSpec , symbolsSpec and geometrySpec component expressions (see Partial Components and Combining Multiple Components) specify the database components to be used to assemble the keyboard description.

The want field lists the pieces of the keyboard description that the client wants to have reported for the newly constructed keymap. The need field lists all of the pieces that must be reported. If any of the pieces in need cannot be loaded from the specified names, no description of the keyboard is returned.

The want and need fields can include any combinations of these XkbGetMapByName (GBN) components:

XkbGetMapByName Keyboard Component… | Database Component… | Components of Keyboard Description
--- | --- | ---
XkbGBN_Types | types | key types
XkbGBN_CompatMap | compat | symbol interpretations, group compatibility map
XkbGBN_ClientSymbols | symbols, types, keycodes | key types, key symbol mappings, modifier mapping
XkbGBN_ServerSymbols | symbols, types, keycodes | key behaviors, key actions, key explicit components, virtual modifiers, virtual modifier mapping
XkbGBN_IndicatorMap | compat | indicator maps, indicator names
XkbGBN_KeyNames | keycodes | key names, key aliases
XkbGBN_Geometry | geometry | keyboard geometry
XkbGBN_OtherNames | all | key types, symbol interpretations, indicator maps, names, geometry

If either field contains a GBN component that depends on some database component for which the request does not supply an expression, XKB automatically substitutes the special pattern "%" which copies the corresponding component from the current keyboard description, as described in Partial Components and Combining Multiple Components.

The load flag asks the server to replace the current keyboard description for deviceSpec with the newly constructed keyboard description. If load is True , the request must include component expressions for all of the database components; if any are missing, XKB substitutes "%" as described above.

If all necessary components are both specified and found, the new keyboard description is loaded. If the new keyboard description has a different geometry or keycode range than the previous keyboard description, XKB sends XkbNewKeyboardNotify events to all interested clients. See Replacing the Keyboard "On-the-Fly" for more information about the effects of replacing the keyboard description on the fly.

If the range of keycodes changes, clients that have requested XkbNewKeyboardNotify events are not sent any other change notification events by this request. Clients that do not request XkbNewKeyboardNotify events are sent other XKB change notification events (e.g. XkbMapNotify , XkbNamesNotify ) as necessary to alert them to as many of the keyboard changes as possible.

If no error occurs, the request reply reports the GBN components that were found and sends a description of any of the resulting keyboard that includes and of the components that were requested.

The deviceID return value reports the X Input extension device identifier of the keyboard that was used, or 0 if the server does not support the X input extension.

The minKeyCode and maxKeyCode return values report the legal range of keycodes for the keyboard description that was created. If the resulting keyboard description does not include at least one of the key names, client symbols or server symbols components, minKeyCode and maxKeyCode are both 0 .

The loaded return value reports whether or not the existing keyboard definition was replaced with the newly created one. If loaded is True , the newKeyboard return value reports whether or not the new map changed the geometry or range of keycodes and caused XkbNewKeyboardNotify events for clients that have requested them.

The found return value reports the GBN components that were present in the keymap that was constructed by this request. The reported return value lists the subset of those components for which descriptions follow. if any of the components specified in the need field of the request were not found, reported is empty, otherwise it contains the intersection of the found return value with the union of the need and want request fields.

If any of GBN_Types , GBN_ClientSymbols or GBN_ServerSymbols are set in reported , the map return value has the same format as the reply to an XkbGetMap request and reports the corresponding pieces of the newly constructed keyboard description.

If GBN_CompatMap is set in reported , the compat return value has the same format as the reply to an XkbGetCompatMap request and reports the symbol interpretations and group compatibility map for the newly constructed keyboard description.

If GBN_IndicatorMap is set in reported , the indicators return value has the same format as the reply to an XkbGetIndicatorMap request and reports the physical indicators and indicator maps for the newly constructed keyboard description.

If GBN_KeyNames or GBN_OtherNames are set in reported , the names return value has the same format as the reply to an XkbGetNames reply and reports the corresponding set of symbolic names for the newly constructed keyboard description.

If GBN_Geometry is set in reported , the geometry return value has the same format as the reply to an XkbGetGeometryMap request and reports the keyboard geometry for the newly constructed keyboard description.

### Querying and Changing Input Extension Devices

XkbGetDeviceInfo
deviceSpec: KB_DEVICESPEC
wanted: KB_XIDEVFEATUREMASK
ledClass: KB_LEDCLASSSPEC
ledID: KB_IDSPEC
allButtons: BOOL
firstButton, nButtons: CARD8
deviceID: CARD8
present: KB_XIDEVFEATUREMASK
supported: KB_XIFEATUREMASK
unsupported: KB_XIFEATUREMASK
firstBtnWanted: CARD8
nBtnsWanted: CARD8
firstBtnRtrn: CARD8
nBtnsRtrn: CARD8
totalBtns: CARD8
hasOwnState: BOOL
dfltKbdFB, dfltLedFB: KB_IDSPEC
devType: ATOM
name: STRING
btnActions: LISTofKB_ACTION
leds: LISTofKB_DEVICELEDINFO
Errors: Device , Match , Access , Alloc

Reports a subset of the XKB-supplied information about the input device specified by deviceSpec . Unlike most XKB requests, the device specified for XkbGetDeviceInfo need not be a keyboard device. Nonetheless, a Keyboard error results if deviceSpec does not specify a valid core or input extension device.

The wanted field specifies the types of information to be returned, and controls the interpretation of the other request fields.

If the server does not support assignment of XKB actions to extension device buttons, the allButtons , firstButton and nButtons fields are ignored.

Otherwise, if the XkbXI_ButtonActions flag is set in wanted , the allButtons , firstButton and nButtons fields specify the device buttons for which actions should be returned. Setting allButtons to True requests actions for all device buttons; if allButtons is False , firstButton and nButtons specify a range of buttons for which actions are requested. If the device has no buttons or if firstButton and nButtons specify illegal buttons, a Match error results. If allButtons is True , firstButton and nButtons are ignored.

If the server does not support XKB access to any aspect of the indicators on extension devices, or if the wanted field does not include any of the indicator flags, the ledClass and ledID fields are ignored. Otherwise, ledClass and ledID specify one or more feedback(s) for which indicator information is requested. If ledClass or ledID have illegal values, a Value error results. If they have legal values but do not specify a keyboard or indicator class feedback for the device in question, a Match error results.

The ledClass field can specify either KbdFeedbackClass , LedFeedbackClass , XkbDfltXIClass , or XkbAllXIClasses . If at least one keyboard feedback is defined for the specified device, XkbDfltXIClass is equivalent to KbdFeedbackClass , otherwise it is equivalent to LedFeedbackClass . If XkbAllXIClasses is specified, this request returns information about both indicator and keyboard class feedbacks which match the requested identifier, as described below.

The ledID field can specify any valid input extension feedback identifier, XkbDfltXIId , or XkbAllXIIds . The default keyboard feedback is the one that is affected by core protocol requests; the default led feedback is implementation-specific. If XkbAllXIIds is specified, this request returns indicator information about all feedbacks of the class(es) specified by ledClass .

If no error results, the deviceID return value reports the input extension device identifier of the device for which values are being returned. The supported return value reports the set of optional XKB extension device features that are supported by this implementation (see Interactions Between XKB and the X Input Extension) for the specified device, and the unsupported return value reports any unsupported features.

If hasOwnState is True , the device is also a keyboard, and any indicator maps bound to the device use the current state and control settings for this device to control automatic changes. If hasOwnState is False , the state and control settings of the core keyboard device control automatic indicator changes.

The name field reports the X Input Extension name for the device. The devType field reports the X Input Extension device type. Both fields are provided merely for convenience and are not interpreted by XKB.

The present return value reports the kinds of device information being returned, and controls the interpretation of the remaining fields. The present field consists of the wanted field from the original request minus the flags for any unsupported features.

If XkbXI_ButtonActions is set in present , the totalBtns return value reports the total number of buttons present on the device, firstBtnWanted and nBtnsWanted specify the range of buttons for which actions were requested, and the firstBtnRtrn and nBtnsRtrn values specify the range of buttons for which actions are reported. The actionsRtrn list has nButtonsRtrn entries which contain the actions bound to the specified buttons on the device. Any buttons for which actions were requested but not returned have the action NoAction() .

If any indicator information is reported, the leds list contains one element for each requested feedback. For example, if ledClass is XkbAllXIClasses and ledID is XkbAllXIIds , leds describes all of the indicators on the device and has one element for each keyboard or led class feedback defined for the device. If any information at all is reported about a feedback, the set of physical indicators is also reported in the physIndicators field of the corresponding element of leds .

If the server supports assignment of indicator maps to extension device indicators, and if the XkbXI_IndicatorMaps flag is set in wanted , each member of leds reports any indicators on the corresponding feedback to which names have been assigned. Any indicators for which no map is reported have the default map, which allows explicit changes and does not request any automatic changes.

If the server supports assignment of indicator names to extension device indicators, and the XkbXI_IndicatorNames flag is set in wanted , each member of leds reports any indicators on the corresponding feedback to which names have been assigned. Any indicators for which no name is reported have the name None .

If the server supports XKB access to the state of extension device indicators, and the XkbXI_IndicatorState flag is set in wanted, each member of leds reports the state of the indicators on the corresponding feedback.

If any unsupported features are requested, and the requesting client has selected for them, the server sends the client an XkbExtensionDeviceNotify event which indicates that an unsupported feature was requested. This event is only generated if the client which issued the unsupported request has selected for it and, if generated, is not sent to any other clients.

XkbSetDeviceInfo
deviceSpec: KB_DEVICESPEC
change: KB_XIDEVFEATUREMASK
firstBtn, nBtns: CARD8
btnActions:LISTofKB_ACTION
leds: LISTofKB_DEVICELEDINFO
Errors: Device , Match , Access , Alloc

Changes a subset of the XKB-supplied information about the input device specified by deviceSpec . Unlike most XKB requests, the device specified for XkbGetDeviceInfo need not be a keyboard device. Nonetheless, a Keyboard error results if deviceSpec does not specify a valid core or input extension device

The change field specifies the features for which new values are supplied, and controls the interpretation of the other request fields.

If the server does not support assignment of XKB actions to extension device buttons, the firstButton and nButtons fields are ignored.

Otherwise, if the XkbXI_ButtonActions flag is set in change , the firstBtn and nBtns fields specify a range of buttons for which actions are specified in this request. If the device has no buttons or if firstBtn and nBtns specify illegal buttons, a Match error results.

Each element of the leds list describes the changes for a single keyboard or led feedback. If the ledClass field of any element of leds contains any value other than KbdFeedbackClass , LedFeedbackClass or XkbDfltXIClass , a Value error results. If the ledId field of any element of leds contains any value other than a valid input extension feedback identifier or XkbDfltXIId , a Value error results. If both fields are valid, but the device has no matching feedback, a Match error results.

The fields of each element of leds are interpreted as follows:

- If XkbXI_IndicatorMaps is set in change and the server supports XKB assignment of indicator maps to the corresponding feedback, the maps for all indicators on the corresponding feedback are taken from leds . If the server does not support this feature, any maps specified in leds are ignored.

- If XkbXI_IndicatorNames is set in change , and the server supports XKB assignment of names to indicators for the corresponding feedback, the names for all indicators on the corresponding feedback are taken from leds . If the server does not support this feature, any names specified in leds are ignored. Regardless of whether they are used, any names be a valid Atom or None , or an Atom error results.

- If XkbXI_IndicatorState is set in change, and the server supports XKB changes to extension device indicator state, the server attempts to change the indicators on the corresponding feedback as specified by leds . Any indicator maps bound to the feedback are applied, so state changes might be blocked or have side-effects.

If any unsupported features are requested, and the requesting client has selected for them, the server sends the client an XkbExtensionDeviceNotify event which indicates that an unsupported feature was requested. This event is only generated if the client which issued the unsupported request has selected for it and, if generated, is not sent to any other clients.

### Debugging the X Keyboard Extension

XkbSetDebuggingFlags
affectFlags, flags: CARD32
affectCtrls, ctrls: CARD32
message: STRING
currentFlags, supportedFlags: CARD32
currentCtrls, supportedCtrls: CARD32

This request sets up various internal XKB debugging flags and controls. It is intended for developer use and may be disabled in production servers. If disabled, XkbSetDebuggingFlags has no effect but returns Success .

The affectFlags field specifies the debugging flags to be changed, the flags field specifies new values for the changed flags. The interpretation of the debugging flags is implementation-specific, but flags are intended to control debugging output and should not otherwise affect the operation of the server.

The affectCtrls field specifies the debugging controls to be changed, the ctrls field specifies new values for the changed controls. The interpretation of the debugging controls is implementation-specific, but debugging controls are allowed to affect the behavior of the server.

The message field provides a message that the X server can print in any logging or debugging files before changing the flags. The server must accept this field but it is not required to actually display it anywhere.

The X Test Suite makes some assumptions about the implementation of locking modifier keys that do not apply when XKB is present. The XkbDF_DisableLocks debugging control provides a simple workaround to these test suite problems by simply disabling all locking keys. If XkbDF_DisableLocks is enabled, the SA_LockMods and SA_LockGroup actions behave like SA_SetMods and SA_LockMods , respectively. If it is disabled, SA_LockMods and SA_LockGroup actions behave normally.

Implementations are free to ignore the XkbDF_DisableLocks debugging control or to define others.

The currentFlags return value reports the current setting for the debugging flags, if applicable. The currentCtrls return value reports the setting for the debugging controls, if applicable. The supportedFlags and supportedCtrls fields report the flags and controls that are recognized by the implementation. Attempts to change unsupported fields or controls are silently ignored.

If the XkbSetDebuggingFlags request contains more data than expected, the server ignores the extra data, but no error results. If the request has less data than expected, a Length error results.

If the XkbSetDebuggingFlags reply contains more data than expected, the client just ignores any uninterpreted data without reporting an error. If the reply has less data than expected, a Length error results.

## Events

All XKB events report the time at which they occurred in a field named time and the device on which they occurred in a field named deviceID . XKB uses a single X event code for all events and uses a common field to distinguish XKB event type.

### Tracking Keyboard Replacement

XkbNewKeyboardNotify
time: TIMESTAMP
deviceID: CARD8
changed: KB_NKNDETAILMASK
minKeyCode, maxKeyCode: KEYCODE
oldDeviceID: CARD8
oldMinKeyCode, oldMaxKeyCode: KEYCODE
requestMajor, requestMinor: CARD8

An XkbNewKeyboardNotify event reports that a new core keyboard has been installed. New keyboard notify events can be generated:

- When the X server detects that the keyboard was changed.

- When a client installs a new extension device as the core keyboard using the X Input Extension ChangeKeyboardDevice request.

- When a client issues an XkbGetMapByName request which changes the keycodes range or geometry.

The changed field of the event reports the aspects of the keyboard that have changed, and can contain any combination of the event details for this event:

Bit in Changed | Meaning
--- | ---
NKN_Keycodes | The new keyboard has a different minimum or maximum keycode.
NKN_Geometry | The new keyboard has a different keyboard geometry.
NKN_DeviceID | The new keyboard has a new X Input Extension device identifier

The server sends an XkbNewKeyboardNotify event to a client only if at least one of the bits that is set in the changed field of the event is also set in the appropriate event details mask for the client.

The minKeyCode and maxKeyCode fields report the minimum and maximum keycodes that can be returned by the new keyboard. The oldMinKeyCode and oldMaxKeyCode fields report the minimum and maximum values that could be returned before the change. This event always reports all four values, but the old and new values are the same unless NKN_Keycodes is set in changed .

Once a client receives a new keyboard notify event which reports a new keycode range, the X server reports events from all keys in the new range to that client. Clients that do not request or receive new keyboard notify events receive events only from keys that fall in the last range for legal keys reported to that client. See Replacing the Keyboard "On-the-Fly" for a more detailed explanation.

If NKN_Keycodes is set in changed , the XkbNewKeyboardNotify event subsumes all other change notification events (e.g. XkbMapNotify , XkbNamesNotify ) that would otherwise result from the keyboard change. Clients who receive an XkbNewKeyboardNotify event should assume that all other aspects of the keyboard mapping have changed and regenerate the entire local copy of the keyboard description.

The deviceID field reports the X Input Extension device identifier of the new keyboard device; oldDeviceID reports the device identifier before the change. This event always includes both values, but they are the same unless NKN_DeviceID is set in changed . If the server does not support the X Input Extension, both fields have the value 0 .

The requestMajor and requestMinor fields report the major and minor opcode of the request that caused the keyboard change. If the keyboard change was not caused by some client request, both fields have the value 0 .

### Tracking Keyboard Mapping Changes

XkbMapNotify
time: TIMESTAMP
deviceID: CARD8
ptrBtnActions: CARD8
changed: KB_MAPPARTMASK
minKeyCode, maxKeyCode: KEYCODE
firstType, nTypes: CARD8
firstKeySym, firstKeyAction: KEYCODE
nKeySyms, nKeyActions: CARD8
firstKeyBehavior, firstKeyExplicit: KEYCODE
nKeyBehaviors, nKeyExplicit: CARD8
virtualMods: KB_VMODMASK
firstModMapKey, firstVModMapKey: KEYCODE
nModMapKeys, nVModMapKeys: CARD8

An XkbMapNotify event reports that some aspect of XKB map for a keyboard has changed. Map notify events can be generated whenever some aspect of the keyboard map is changed by an XKB or core protocol request.

The deviceID field reports the keyboard for which some map component has changed and the changed field reports the components with new values, and can contain any of the values that are legal for the full and partial fields of the XkbGetMap request. The server sends an XkbMapNotify event to a client only if at least one of the bits that is set in the changed field of the event is also set in the appropriate event details mask for the client.

The minKeyCode and maxKeyCode fields report the range of keycodes that are legal on the keyboard for which the change is being reported.

If XkbKeyTypesMask is set in changed , the firstType and nTypes fields report a range of key types that includes all changed types. Otherwise, both fields are 0 .

If XkbKeySymsMask is set in changed , the firstKeySym and nKeySyms fields report a range of keycodes that includes all keys with new symbols. Otherwise, both fields are 0 .

If XkbKeyActionsMask is set in changed , the firstKeyAction and nKeyActions fields report a range of keycodes that includes all keys with new actions. Otherwise, both fields are 0 .

If XkbKeyBehaviorsMask is set in changed , the firstKeyBehavior and nKeyBehaviors fields report a range of keycodes that includes all keys with new key behavior. Otherwise, both fields are 0 .

If XkbVirtualModsMask is set in changed , virtualMods contains all virtual modifiers to which a new set of real modifiers is bound. Otherwise, virtualMods is 0 .

If XkbExplicitComponentsMask is set in changed , the firstKeyExplicit and nKeyExplicit fields report a range of keycodes that includes all keys with changed explicit components. Otherwise, both fields are 0 .

If XkbModifierMapMask is set in changed , the firstModMapKey and nModMapKeys fields report a range of keycodes that includes all keys with changed modifier bindings. Otherwise, both fields are 0 .

If XkbVirtualModMapMask is set in changed , the firstVModMapKey and nVModMapKeys fields report a range of keycodes that includes all keys with changed virtual modifier mappings. Otherwise, both fields are 0 .

### Tracking Keyboard State Changes

XkbStateNotify
time: TIMESTAMP
deviceID: CARD8
mods, baseMods, latchedMods, lockedMods: KEYMASK
group, lockedGroup: CARD8
baseGroup, latchedGroup: INT16
compatState: KEYMASK
grabMods, compatGrabMods: KEYMASK
lookupMods, compatLookupMods: KEYMASK
ptrBtnState: BUTMASK
changed: KB_STATEPARTMASK
keycode: KEYCODE
eventType: CARD8
requestMajor, requestMinor: CARD8

An XkbStateNotify event reports that some component of the XKB state (see Keyboard State) has changed. State notify events are usually caused by key or pointer activity, but they can also result from explicit state changes requested by the XkbLatchLockState request or by other extensions.

The deviceID field reports the keyboard on which some state component changed. The changed field reports the XKB state components (see Keyboard State) that have changed and contain any combination of:

Bit in changed | Event field | Changed component
--- | --- | ---
ModifierState | mods | The effective modifiers
ModifierBase | baseMods | The base modifiers
ModifierLatch | latchedMods | The latched modifiers
ModifierLock | lockedMods | The locked modifiers
GroupState | group | The effective keyboard group
GroupBase | baseGroup | The base keyboard group
GroupLatch | latchedGroup | The latched keyboard group
GroupLock | lockedGroup | The locked keyboard group
PointerButtons | ptrBtnState | The state of the core pointer buttons
GrabMods | grabMods | The XKB state used to compute grabs
LookupMods | lookupMods | The XKB state used to look up symbols
CompatState | compatState | Default state for non-XKB clients
CompatGrabMods | compatGrabMods | The core state used to compute grabs
CompatLookupMods | compatLookupMods | The core state used to look up symbols

The server sends an XkbStateNotify event to a client only if at least one of the bits that is set in the changed field of the event is also set in the appropriate event details mask for the client.

A state notify event reports current values for all state components, even those with unchanged values.

The keycode field reports the key or button which caused the change in state while the eventType field reports the exact type of event (e.g. KeyPress ). If the change in state was not caused by key or button activity, both fields have the value 0 .

The requestMajor and requestMinor fields report the major and minor opcodes of the request that caused the change in state and have the value 0 if it was resulted from key or button activity.

### Tracking Keyboard Control Changes

XkbControlsNotify
time: TIMESTAMP
deviceID: CARD8
numGroups: CARD8
changedControls: KB_CONTROLMASK
enabledControls,enabledControlChanges: KB_BOOLCTRLMASK
keycode: KEYCODE
eventType: CARD8
requestMajor: CARD8
requestMinor: CARD8

An XkbControlsNotify event reports a change in one or more of the global keyboard controls (see Global Keyboard Controls) or in the internal modifiers or ignore locks masks (see Server Internal Modifiers and Ignore Locks Behavior). Controls notify events are usually caused by and XkbSetControls request, but they can also be caused by keyboard activity or certain core protocol and input extension requests.

The deviceID field reports the keyboard for which some control has changed, and the changed field reports the controls that have new values.

The changed field can contain any of the values that are permitted for the changeControls field of the XkbSetControls request. The server sends an XkbControlsNotify event to a client only if at least one of the bits that is set in the changed field of the event is also set in the appropriate event details mask for the client.

The numGroups field reports the total number of groups defined for the keyboard, whether or not the number of groups has changed.

The enabledControls field reports the current status of all of the boolean controls, whether or not any boolean controls changed state. If EnabledControls is set in changed , the enabledControlChanges field reports the boolean controls that were enabled or disabled; if a control is specified in enabledControlChanges , the value that is reported for that control in enabledControls represents a change in state.

The keycode field reports the key or button which caused the change in state while the eventType field reports the exact type of event (e.g. KeyPress ). If the change in state was not caused by key or button activity, both fields have the value 0 .

The requestMajor and requestMinor fields report the major and minor opcodes of the request that caused the change in state and have the value 0 if it was resulted from key or button activity.

### Tracking Keyboard Indicator State Changes

XkbIndicatorStateNotify
time: TIMESTAMP
deviceID: CARD8
stateChanged, state: KB_INDICATORMASK

An XkbIndicatorStateNotify event indicates that one or more of the indicators on a keyboard have changed state. Indicator state notify events can be caused by:

- Automatic update to reflect changes in keyboard state (keyboard activity, XkbLatchLockState requests).

- Automatic update to reflect changes in keyboard controls ( XkbSetControls , keyboard activity, certain core protocol and input extension requests).

- Explicit attempts to change indicator state (core protocol and input extension requests, XkbSetNamedIndicator requests).

- Changes to indicator maps ( XkbSetIndicatorMap and XkbSetNamedIndicator requests).

The deviceID field reports the keyboard for which some indicator has changed, and the state field reports the new state for all indicators on the specified keyboard. The stateChanged field specifies which of the values in state represent a new state for the corresponding indicator. The server sends an XkbIndicatorStateNotify event to a client only if at least one of the bits that is set in the stateChanged field of the event is also set in the appropriate event details mask for the client.

### Tracking Keyboard Indicator Map Changes

XkbIndicatorMapNotify
time: TIMESTAMP
deviceID: CARD8
state: KB_INDICATORMASK
mapChanged: KB_INDICATORMASK

An XkbIndicatorMapNotify event indicates that the maps for one or more keyboard indicators have been changed. Indicator map notify events can be caused by XkbSetIndicatorMap and XkbSetNamedIndicator requests.

The deviceID field reports the keyboard for which some indicator map has changed, and the mapChanged field reports the indicators with changed maps. The server sends an XkbIndicatorMapNotify event to a client only if at least one of the bits that is set in the mapChanged field of the event is also set in the appropriate event details mask for the client.

The state field reports the current state of all indicators on the specified keyboard.

### Tracking Keyboard Name Changes

XkbNamesNotify
time: TIMESTAMP
deviceID: CARD8
changed: KB_NAMEDETAILMASK
firstType, nTypes: CARD8
firstLevelName, nLevelNames: CARD8
firstKey: KEYCODE
nKeys, nKeyAliases, nRadioGroups: CARD8
changedGroupNames: KB_GROUPMASK
changedVirtualMods: KB_VMODMASK
changedIndicators: KB_INDICATORMASK

An XkbNamesNotify event reports a change to one or more of the symbolic names associated with a keyboard. Symbolic names can change when:

- Some client explicitly changes them using XkbSetNames .

- The list of key types or radio groups is resized

- The group width of some key type is changed

The deviceID field reports the keyboard on which names were changed. The changed mask lists the components for which some names have changed and can have any combination of the values permitted for the which field of the XkbGetNames request. The server sends an XkbNamesNotify event to a client only if at least one of the bits that is set in the changed field of the event is also set in the appropriate event details mask for the client.

If KeyTypeNames is set in changed , the firstType and nTypes fields report a range of types that includes all types with changed names. Otherwise, both fields are 0 .

If KTLevelNames is set in changed , the firstLevelName and nLevelNames fields report a range of types that includes all types with changed level names. Otherwise, both fields are 0 .

If IndicatorNames is set in changed , the changedIndicators field reports the indicators with changed names. Otherwise, changedIndicators is 0 .

If VirtualModNames is set in changed , the changedVirtualMods field reports the virtual modifiers with changed names. Otherwise, changedVirtualMods is 0 .

If GroupNames is set in changed , the changedGroupNames field reports the groups with changed names. Otherwise, changedGroupNames is 0 .

If KeyNames is set in changed , the firstKey and nKeys fields report a range of keycodes that includes all keys with changed names. Otherwise, both fields are 0 .

The nKeyAliases field reports the total number of key aliases associated with the keyboard, regardless of whether KeyAliases is set in changed .

The nRadioGroups field reports the total number of radio group names associated with the keyboard, regardless of whether RGNames is set in changed .

### Tracking Compatibility Map Changes

XkbCompatMapNotify
time: TIMESTAMP
deviceID: CARD8
changedGroups: KB_GROUPMASK
firstSI, nSI: CARD16
nTotalSI: CARD16

An XkbCompatMapNotify event indicates that some component of the compatibility map for a keyboard has been changed. Compatibility map notify events can be caused by XkbSetCompatMap and XkbGetMapByName requests.

The deviceID field reports the keyboard for which the compatibility map has changed; if the server does not support the X input extension, deviceID is 0 .

The changedGroups field reports the keyboard groups, if any, with a changed entry in the group compatibility map. The firstSI and nSI fields specify a range of symbol interpretations in the symbol compatibility map that includes all changed symbol interpretations; if the symbol compatibility map is unchanged, both fields are 0 . The nTotalSI field always reports the total number of symbol interpretations present in the symbol compatibility map, regardless of whether any symbol interpretations have been changed.

The server sends an XkbCompatMapNotify event to a client only if at least one of the following conditions is met:

- The nSI field of the event is non-zero, and the XkbSymInterpMask bit is set in the appropriate event details mask for the client.

- The changedGroups field of the event contains at least one group, and the XkbGroupCompatMask bit is set in the appropriate event details mask for the client.

### Tracking Application Bell Requests

XkbBellNotify
time: TIMESTAMP
deviceID: CARD8
bellClass: { KbdFeedbackClass, BellFeedbackClass }
bellID: CARD8
percent: CARD8
pitch: CARD16
duration: CARD16
eventOnly: BOOL
name: ATOM
window: WINDOW

An XkbBellNotify event indicates that some client has requested a keyboard bell. Bell notify events are usually caused by Bell , DeviceBell , or XkbBell requests, but they can also be generated by the server (e.g. if the AccessXFeedback control is active).

The server sends an XkbBellNotify event to a client if the appropriate event details field for the client has the value True .

The deviceID field specifies the device for which a bell was requested, while the bellClass and bellID fields specify the input extension class and identifier of the feedback for which the bell was requested. If the reporting server does not support the input extension, all three fields have the value 0.

The percent , pitch and duration fields report the volume, tone and duration requested for the bell as specified by the XkbBell request. Bell notify events caused by core protocol or input extension requests use the pitch and duration specified in the corresponding bell or keyboard feedback control.

If the bell was caused by an XkbBell request or by the X server, name reports an optional symbolic name for the bell and the window field optionally reports the window for which the bell was generated. Otherwise, both fields have the value None .

If the eventOnly field is True , the server did not generate a sound in response to the request, otherwise the server issues the beep before sending the event. The eventOnly field can be True if the AudibleBell control is disabled or if a client explicitly requests eventOnly when it issues an XkbBell request.

### Tracking Messages Generated by Key Actions

XkbActionMessage
time: TIMESTAMP
deviceID: CARD8
keycode: KEYCODE
press: BOOL
mods: KEYMASK
group: KB_GROUP
keyEventFollows: BOOL
message: LISTofCARD8

An XkbActionMessage event is generated when the user operates a key to which an SA_ActionMessage message is bound under the appropriate state and group. The server sends an XkbActionMessage event to a client if the appropriate event details field for the client has the value True .

The deviceID field specifies the keyboard device that contains the key which activated the event. The keycode field specifies the key whose operation caused the message and press is True if the message was caused by the user pressing the key. The mods and group fields report the effective keyboard modifiers and group in effect at the time the key was pressed or released.

If keyEventFollows is True , the server will also send a key press or release event, as appropriate, for the key that generated the message. If it is False , the key causes only a message. Note that the key event is delivered normally with respect to passive grabs, keyboard focus, and cursor position, so that keyEventFollows does not guarantee that any particular client which receives the XkbActionMessage notify event will also receive a key press or release event.

The message field is NULL -terminated string of up to ActionMessageLength ( 6 ) bytes, which reports the contents of the message field in the action that caused the message notify event.

### Tracking Changes to AccessX State and Keys

XkbAccessXNotify
time: TIMESTAMP
deviceID: CARD8
detail: KB_AXNDETAILMASK
keycode: KEYCODE
slowKeysDelay: CARD16
debounceDelay: CARD16

An XkbAccessXNotify event reports on some kinds of keyboard activity when any of the SlowKeys , BounceKeys or AccessXKeys controls are active. Compatibility map notify events can only be caused by keyboard activity.

The deviceID and keycode fields specify the keyboard and key for which the event occurred. The detail field describes the event that occurred and has one of the following values:

Detail | Control | Meaning
--- | --- | ---
AXN_SKPress | SlowKeys | Key pressed
AXN_SKAccept | SlowKeys | K ey held until it was accepted.
AXN_SKReject | SlowKeys | Key released before it was accepted.
AXN_SKRelease | SlowKeys | Key released after it was accepted.
AXN_BKAccept | BounceKeys | Key pressed while it was active.
AXN_BKReject | BounceKeys | Key pressed while it was still disabled.
AXN_AXKWarning | AccessXKeys | Shift key held down for four seconds

Each subclass of the AccessX notify event is generated only when the control specified in the table above is enabled. The server sends an XkbAccessXNotify event to a client only if the bit which corresponds to the value of the detail field for the event is set in the appropriate event details mask for the client.

Regardless of the value of detail , the slowKeysDelay and debounceDelay fields always reports the current slow keys acceptance delay (see The SlowKeys Control) and debounce delay (see The BounceKeys Control) for the specified keyboard.

### Tracking Changes To Extension Devices

XkbExtensionDeviceNotify
time: TIMESTAMP
deviceID: CARD16
ledClass: { KbdFeedbackClass, LedFeedbackClass }
ledID: CARD16
reason: KB_XIDETAILMASK
supported: KB_XIFEATUREMASK
unsupported: KB_XIFEATUREMASK
ledsDefined: KB_INDICATORMASK
ledState: KB_INDICATORMASK
firstButton, nButtons: CARD8

An XkbExtensionDeviceNotify event reports:

- A change to some part of the XKB information for an extension device.

- An attempt to use an XKB extension device feature that is not supported for the specified device by the current implementation.

The deviceID field specifies the X Input Extension device identifier of some device on which an XKB feature was requested, or XkbUseCorePtr if the request affected the core pointer device. The reason field explains why the event was generated in response to the request, and can contain any combination of XkbXI_UnsupportedFeature and the values permitted for the change field of the XkbSetDeviceInfo request.

If XkbXI_ButtonActions is set in reason , this event reports a successful change to the XKB actions bound to one or more buttons on the core pointer or an extension device. The firstButton and nButtons fields report a range of device buttons that include all of the buttons for which actions were changed.

If any combination of XkbXI_IndicatorNames , XkbXI_IndicatorMaps , or XkbXI_IndicatorState is set in either reason or unsupported , the ledClass and ledID fields specify the X Input Extension feedback class and identifier of the feedback for which the change is reported. If this event reports any changes to an indicator feedback, the ledsDefined field reports all indicators on that feedback for which either a name or a indicator map are defined, and ledState reports the current state of all of the indicators on the specified feedback.

If XkbXI_IndicatorNames is set in reason , this event reports a successful change to the symbolic names bound to one or more extension device indicators by XKB. If XkbXI_IndicatorMaps is set in reason , this event reports a successful change to the indicator maps bound to one or more extension device indicators by XKB. If XkbXI_IndicatorState is set in reason, this event reports that one or more indicators in the specified device and feedback have changed state.

If XkbXI_UnsupportedFeature is set in reason, this event reports an unsuccessful attempt to use some XKB extension device feature that is not supported by the XKB implementation in the server for the specified device. The unsupported mask reports the requested features that are not available on the specified device. See Interactions Between XKB and the X Input Extension for more information about possible XKB interactions with the X Input Extension.

The server sends an XkbExtensionDeviceNotify event to a client only if at least one of the bits that is set in the reason field of the event is also set in the appropriate event details mask for the client.

Events that report a successful change to some extension device feature are reported to all clients that have expressed interest in the event; events that report an attempt to use an unsupported feature are reported only to the client which issued the request. Events which report a partial success are reported to all interested clients, but only the client that issued the request is informed of the attempt to use unsupported features.