# Xkb Server Keyboard Mapping

The server field of the complete Xkb keyboard description (see section 6.1) is a pointer to the Xkb server map.

Figure 16.1 shows the relationships between elements in the server map:

Server Map Relationships

The Xkb server map contains the information the server needs to interpret key events and is of type XkbServerMapRec:

    #define XkbNumVirtualMods            16

    typedef struct {                       /* Server Map */
        unsigned short     num_acts;       /* # of occupied entries in acts */
        unsigned short     size_acts;      /* # of entries in acts */
        XkbAction *        acts;           /* linear 2d tables of key actions,
                                              1 per keycode */
        XkbBehavior *      behaviors;      /* key behaviors, 1 per keycode */
        unsigned short *   key_acts;       /* index into acts, 1 per keycode */
        unsigned char *    explicit;       /* explicit overrides of core
                                              remapping, 1 per key */
        unsigned char      vmods[XkbNumVirtualMods];  /* real mods bound
                                                         to virtual mods */
        unsigned short *   vmodmap;        /* virtual mods bound to key,
                                              1 per keycode */
    } XkbServerMapRec, *XkbServerMapPtr;

XkbServerMapRec

The num_acts, size_acts, acts, and key_acts fields specify the key actions, defined in section 16.1. The behaviors field describes the behavior for each key and is defined in section 16.2. The explicit field describes the explicit components for a key and is defined in section 16.3. The vmods and the vmodmap fields describe the virtual modifiers and the per-key virtual modifier mapping and are defined in section 16.4.

## Key Actions

A key action defines the effect key presses and releases have on the internal state of the server. For example, the expected key action associated with pressing the Shift key is to set the Shift modifier. There is zero or one key action associated with each keysym bound to each key.

Just as the entire list of key symbols for the keyboard mapping is held in the syms field of the client map, the entire list of key actions for the keyboard mapping is held in the acts array of the server map. The total size of acts is specified by size_acts, and the number of entries is specified by num_acts.

The key_acts array, indexed by keycode, describes the actions associated with a key. The key_acts array has min_key_code unused entries at the start to allow direct indexing using a keycode. If a key_acts entry is zero, it means the key does not have any actions associated with it. If an entry is not zero, the entry represents an index into the acts field of the server map, much as the offset field of a KeySymMapRec structure is an index into the syms field of the client map.

The reason the acts field is a linear list of XkbActions is to reduce the memory consumption associated with a keymap. Because Xkb allows individual keys to have multiple shift levels and a different number of groups per key, a single two-dimensional array of KeySyms would potentially be very large and sparse. Instead, Xkb provides a small two-dimensional array of XkbActions for each key. To store all of these individual arrays, Xkb concatenates each array together in the acts field of the server map.

The key action structures consist only of fields of type char or unsigned char. This is done to optimize data transfer when the server sends bytes over the wire. If the fields are anything but bytes, the server has to sift through all of the actions and swap any nonbyte fields. Because they consist of nothing but bytes, it can just copy them out.

Xkb provides the following macros, to simplify accessing information pertaining to key actions:

Bool `XkbKeyHasActions` XkbDescPtr xkb KeyCode keycode

xkb

  Xkb description of interest

keycode

  keycode of interest

`XkbKeyHasActions` returns True if the key corresponding to keycode has any actions associated with it; otherwise, it returns False.

int `XkbKeyNumActions` XkbDescPtr xkb KeyCode keycode

xkb

  Xkb description of interest

keycode

  keycode of interest

`XkbKeyNumActions` computes the number of actions associated with the key corresponding to keycode. This should be the same value as the result of `XkbKeyNumSyms` (see section 15.3.3).

XkbKeyActionPtr `XkbKeyActionsPtr` XkbDescPtr xkb KeyCode keycode

xkb

  Xkb description of interest

keycode

  keycode of interest

`XkbKeyActionsPtr` returns a pointer to the two-dimensional array of key actions associated with the key corresponding to keycode. Use `XkbKeyActionsPtr` only if the key actually has some actions associated with it, that is, `XkbKeyNumActions` (xkb, keycode) returns something greater than zero.

XkbAction `XkbKeyAction` XkbDescPtr xkb KeyCode keycode int idx

xkb

  Xkb description of interest

keycode

  keycode of interest

idx

  index for group and shift level

`XkbKeyAction` returns the key action indexed by idx in the two-dimensional array of key actions associated with the key corresponding to keycode. idx may be computed from the group and shift level of interest as follows:

         idx = group_index * key_width + shift_level

XkbAction `XkbKeyActionEntry` XkbDescPtr xkb KeyCode keycode int shift int grp

xkb

  Xkb description of interest

keycode

  keycode of interest

shift

  shift level within group

grp

  group index for group of interest

`XkbKeyActionEntry` returns the key action corresponding to group grp and shift level shift from the two-dimensional table of key actions associated with the key corresponding to keycode.

### The XkbAction Structure

The description for an action is held in an XkbAction structure, which is a union of all possible Xkb action types:

    typedef union _XkbAction {
        XkbAnyAction              any;
        XkbModAction              mods;
        XkbGroupAction            group;
        XkbISOAction              iso;
        XkbPtrAction              ptr;
        XkbPtrBtnAction           btn;
        XkbPtrDfltAction          dflt;
        XkbSwitchScreenAction     screen;
        XkbCtrlsAction            ctrls;
        XkbMessageAction          msg;
        XkbRedirectKeyAction      redirect;
        XkbDeviceBtnAction        devbtn;
        XkbDeviceValuatorAction   devval;
        unsigned char             type;
    } XkbAction;

The type field is provided for convenience and is the same as the type field in the individual structures. The following sections describe the individual structures for each action in detail.

XkbAction

### The XkbAnyAction Structure

The XkbAnyAction structure is a convenience structure that refers to any of the actions:

    #define      XkbAnyActionDataSize       7

    typedef struct _XkbAnyAction {
        unsigned char    type;            /* type of action; determines interpretation for data */
        unsigned char    data[XkbAnyActionDataSize];
    } XkbAnyAction;

The data field represents a structure for an action, and its interpretation depends on the type field. The valid values for the type field, and the data structures associated with them are shown in Table 16.1:

Action Types

Type | Structure for Data | XkbAction Union Member | Section
--- | --- | --- | ---
XkbSA_NoAction | XkbSA_NoAction means the server does not perform an action for the key; this action does not have an associated data structure. | any |
XkbSA_SetMods XkbSA_LatchMods XkbSA_LockMods | XkbModAction | mods | 16.1.3
XkbSA_SetGroup XkbSA_LatchGroup XkbSA_LockGroup | XkbGroupAction | group | 16.1.4
XkbSA_MovePtr | XkbPtrAction | ptr | 16.1.5
XkbSA_PtrBtn XkbSA_LockPtrBtn | XkbPtrBtnAction | btn | 16.1.6
XkbSA_SetPtrDflt | XkbPtrDfltAction | dflt | 16.1.7
XkbSA_ISOLock | XkbISOAction | iso | 16.1.8
XkbSA_SwitchScreen | XkbSwitchScreenAction | screen | 16.1.9
XkbSA_SetControls XkbSA_LockControls | XkbCtrlsAction | ctrls | 16.1.10
XkbSA_ActionMessage | XkbMessageAction | msg | 16.1.11
XkbSA_RedirectKey | XkbRedirectKeyAction | redirect | 16.1.12
XkbSA_DeviceBtn XkbSA_LockDeviceBtn | XkbDeviceBtnAction | devbtn | 16.1.13
XkbSA_DeviceValuator | XkbDeviceValuatorAction | devval | 16.1.14

XkbAnyAction

### Actions for Changing Modifiers’ State

Actions associated with the XkbModAction structure change the state of the modifiers when keys are pressed and released (see for a discussion of modifiers):

    typedef struct _XkbModAction {
        unsigned char     type;         /* XkbSA_{Set|Latch|Lock}Mods */
        unsigned char     flags;        /* with type, controls the effect
                                           on modifiers */
        unsigned char     mask;         /* same as mask field of
                                           a modifier description */
        unsigned char     real_mods;    /* same as real_mods field of
                                           a modifier description */
        unsigned char     vmods1;       /* derived from vmods field of
                                           a modifier description */
        unsigned char     vmods2;       /* derived from vmods field of
                                           a modifier description */
    } XkbModAction;

In the following description, the term action modifiers means the real modifier bits associated with this action. Depending on the value of flags (see Table 16.3), these are designated either in the mask field of the XkbModAction structure itself or the real modifiers bound to the key for which the action is being used. In the latter case, this is the client map->modmap [ keycode ] field.

action modifiers
modifiers action

The type field can have any of the values shown in Table 16.2.

Modifier Action Types

Type | Effect
--- | ---
XkbSA_SetMods | A key press adds any action modifiers to the keyboard’s base modifiers. A key release clears any action modifiers in the keyboard’s base modifiers, provided no other key affecting the same modifiers is logically down. If no other keys are physically depressed when this key is released, and XkbSA_ClearLocks is set in the flags field, the key release unlocks any action modifiers.
XkbSA_LatchMods | Key press and key release events have the same effect as for XkbSA_SetMods; if no keys are physically depressed when this key is released, key release events have the following additional effects: Modifiers unlocked due to XkbSA_ClearLocks have no further effect. If XkbSA_LatchToLock is set in the flags field, a key release locks and then unlatches any remaining action modifiers that are already latched. A key release latches any action modifiers not used by the XkbSA_ClearLocks and XkbSA_LatchToLock flags.
XkbSA_LockMods | A key press sets the base state of any action modifiers. If XkbSA_LockNoLock is set in the flags field, a key press also sets the locked state of any action modifiers. A key release clears any action modifiers in the keyboard’s base modifiers, provided no other key that affects the same modifiers is down. If XkbSA_LockNoUnlock is not set in the flags field, and any of the action modifiers were locked before the corresponding key press occurred, a key release unlocks them.

The flags field is composed of the bitwise inclusive OR of the masks shown in Table 16.3. A general meaning is given in the table, but the exact meaning depends on the action type.

Modifier Action Flags

Flag | Meaning
--- | ---
XkbSA_UseModMapMods | If set, the action modifiers are determined by the modifiers bound by the modifier mapping of the key. Otherwise, the action modifiers are set to the modifiers specified by the mask, real_mods, vmods1, and vmods2 fields.
XkbSA_ClearLocks | If set and no keys are physically depressed when this key transition occurs, the server unlocks any action modifiers.
XkbSA_LatchToLock | If set, and the action type is XkbSA_LatchMods, the server locks the action modifiers if they are already latched.
XkbSA_LockNoLock | If set, and the action type is XkbSA_LockMods, the server only unlocks the action modifiers.
XkbSA_LockNoUnlock | If set, and the action is XkbSA_LockMods, the server only locks the action modifiers.

If XkbSA_UseModMapMods is not set in the flags field, the mask, real_mods, vmods1, and vmods2 fields are used to determine the action modifiers. Otherwise they are ignored and the modifiers bound to the key (client map->modmap [ keycode ]) are used instead.

The mask, real_mods, vmods1, and vmods2 fields represent the components of an Xkb modifier description (see section 7.2). While the mask and real_mods fields correspond directly to the mask and real_mods fields of an Xkb modifier description, the vmods1 and vmods2 fields are combined to correspond to the vmods field of an Xkb modifier description. Xkb provides the following macros, to convert between the two formats:

unsigned short `XkbModActionVMods` XkbAction act

act

  action from which to extract virtual mods

`XkbModActionVMods` returns the vmods1 and vmods2 fields of act converted to the vmods format of an Xkb modifier description.

void `XkbSetModActionVMods` XkbAction act unsigned short vmods

act

  action in which to set vmods

vmods

  virtual mods to set

`XkbSetModActionVMods` sets the vmods1 and vmods2 fields of act using the vmods format of an Xkb modifier description.

Despite the fact that the first parameter of these two macros is of type XkbAction, these macros may be used only with Actions of type XkbModAction and XkbISOAction.

XkbModAction
XkbModActionVMods
XkbSetModActionVMods

### Actions for Changing Group State

Actions associated with the XkbGroupAction structure change the current group state when keys are pressed and released (see for a description of groups and keyboard state):

    typedef struct _XkbGroupAction {
        unsigned char   type;       /* XkbSA_{Set|Latch|Lock}Group */
        unsigned char   flags;      /* with type , controls the effect on groups */
        char            group_XXX;  /* represents a group index or delta */
    } XkbGroupAction;

The type field can have any of the following values:

Group Action Types

Type | Effect
--- | ---
XkbSA_SetGroup | If the XkbSA_GroupAbsolute bit is set in the flags field, key press events change the base keyboard group to the group specified by the group_XXX field. Otherwise, key press events change the base keyboard group by adding the group_XXX field to the base keyboard group. In either case, the resulting effective keyboard group is brought back into range depending on the value of the groups_wrap field of the controls structure (see section 10.7.1). If a key with an XkbSA_ISOLock action (see section 16.1.8) is pressed while this key is down, the key release of this key has no effect. Otherwise, the key release cancels the effects of the key press. If the XkbSA_ClearLocks bit is set in the flags field, and no keys are physically depressed when this key is released, the key release also sets the locked keyboard group to Group1.
XkbSA_LatchGroup | Key press and key release events have the same effect as for XkbSA_SetGroup; if no keys are physically depressed when this key is released, key release events have the following additional effects. If the XkbSA_LatchToLock bit is set in the flags field and the latched keyboard group index is nonzero, the key release adds the delta applied by the corresponding key press to the locked keyboard group and subtracts it from the latched keyboard group. The locked and effective keyboard group are brought back into range according to the value of the groups_wrap field of the controls structure. Otherwise, the key press adds the key press delta to the latched keyboard group.
XkbSA_LockGroup | If the XkbSA_GroupAbsolute is set in the flags field, key press events set the locked keyboard group to the group specified by the group_XXX field. Otherwise, key press events add the group specified by the group_XXX field to the locked keyboard group. In either case, the resulting locked and effective keyboard groups are brought back into range depending on the value of the groups_wrap field of the controls structure. A key release has no effect.

The flags field is composed of the bitwise inclusive OR of the masks shown in Table 16.5. A general meaning is given in the table, but the exact meaning depends on the action type.

Group Action Flags

Flag | Meaning
--- | ---
XkbSA_ClearLocks | If set and no keys are physically depressed when this key transition occurs, the server sets the locked keyboard group to Group1 on a key release.
XkbSA_LatchToLock | If set, and the action type is XkbSA_LatchGroup, the server locks the action group if it is already latched.
XkbSA_GroupAbsolute | If set, the group_XXX field represents an absolute group number. Otherwise, it represents a group delta to be added to the current group to determine the new group number.

The group_XXX field represents a signed character. Xkb provides the following macros to convert between a signed integer value and a signed character:

int `XkbSAGroup` XkbAction act

act

  action from which to extract group

`XkbSAGroup` returns the group_XXX field of act converted to a signed int.

void `XkbSASetGroup` XkbAction act int grp

act

  action from which to set group

grp

  group index to set in group_XXX

`XkbSASetGroup` sets the group_XXX field of act from the group index grp.

Despite the fact that the first parameter of these two macros is of type XkbAction, these macros may only be used with Actions of type XkbGroupAction and XkbISOAction.

XkbGroupAction
XkbSAGroup
XkbSASetGroup

### Actions for Moving the Pointer

Actions associated with the XkbPtrAction structure move the pointer when keys are pressed and released:

    typedef struct _XkbPtrAction {
        unsigned char      type;      /* XkbSA_MovePtr */
        unsigned char      flags;     /* determines type of pointer motion */
        unsigned char      high_XXX;  /* x coordinate, high bits */
        unsigned char      low_XXX;   /* y coordinate, low bits */
        unsigned char      high_YYY;  /* x coordinate, high bits */
        unsigned char      low_YYY;   /* y coordinate, low bits */
    } XkbPtrAction;

If the MouseKeys control is not enabled (see section 10.5.1), KeyPress and KeyRelease events are treated as though the action is XkbSA_NoAction.

If the MouseKeys control is enabled, a server action of type XkbSA_MovePtr instructs the server to generate core pointer MotionNotify events rather than the usual KeyPress event, and the corresponding KeyRelease event disables any mouse keys timers that were created as a result of handling the XkbSA_MovePtr action.

The type field of the XkbPtrAction structure is always XkbSA_MovePtr.

The flags field is a bitwise inclusive OR of the masks shown in Table 16.6.

Pointer Action Types

Action Type | Meaning
--- | ---
XkbSA_NoAcceleration | If not set, and the MouseKeysAccel control is enabled (see section 10.5.2), the KeyPress initiates a mouse keys timer for this key; every time the timer expires, the cursor moves.
XkbSA_MoveAbsoluteX | If set, the X portion of the structure specifies the new pointer X coordinate. Otherwise, the X portion is added to the current pointer X coordinate to determine the new pointer X coordinate.
XkbSA_MoveAbsoluteY | If set, the Y portion of the structure specifies the new pointer Y coordinate. Otherwise, the Y portion is added to the current pointer Y coordinate to determine the new pointer Y coordinate.

Each of the X and Y coordinates of the XkbPtrAction structure is composed of two signed 16-bit values, that is, the X coordinate is composed of high_XXX and low_XXX, and similarly for the Y coordinate. Xkb provides the following macros, to convert between a signed integer and two signed 16-bit values in XkbPtrAction structures:

int `XkbPtrActionX` XkbPtrAction act

act

  action from which to extract X

`XkbPtrActionX` returns the high_XXX and low_XXX fields of act converted to a signed int.

int `XkbPtrActionY` XkbPtrAction act

act

  action from which to extract Y

`XkbPtrActionY` returns the high_YYY and low_YYY fields of act converted to a signed int.

void `XkbSetPtrActionX` XkbPtrAction act int x

act

  action in which to set X

x

  new value to set

`XkbSetPtrActionX` sets the high_XXX and low_XXX fields of act from the signed integer value x.

void `XkbSetPtrActionY` XkbPtrAction act int y

act

  action in which to set Y

y

  new value to set

`XkbSetPtrActionX` sets the high_YYY and low_YYY fields of act from the signed integer value y.

XkbPtrAction
XkbPtrActionX
XkbPtrActionY
XkbSetPtrActionX
XkbSetPtrActionY

### Actions for Simulating Pointer Button Press and Release

Actions associated with the XkbPtrBtnAction structure simulate the press and release of pointer buttons when keys are pressed and released:

    typedef struct _XkbPtrBtnAction {
        unsigned char   type;     /* XkbSA_PtrBtn, XkbSA_LockPtrBtn */
        unsigned char   flags;    /* with type, controls the effect
                                     on pointer buttons */
        unsigned char   count;    /* controls number of ButtonPress and
                                     ButtonRelease events */
        unsigned char   button;   /* pointer button to simulate */
    } XkbPtrBtnAction;

If the MouseKeys (see section 10.5.1) control is not enabled, KeyPress and KeyRelease events are treated as though the action is XkbSA_NoAction.

The type field can have any one of the values shown in Table 16.7.

Pointer Button Action Types

Type | Effect
--- | ---
XkbSA_PtrBtn | If XkbSA_UseDfltButton is set in the flags field, the event is generated for the pointer button specified by the mk_dflt_btn attribute of the MouseKeys control (see section 10.5.1). Otherwise, the event is generated for the button specified by the button field. If the mouse button specified for this action is logically down, the key press and corresponding key release are ignored and have no effect. Otherwise, a key press causes one or more core pointer button events instead of the usual KeyPress event. If count is zero, a key press generates a single ButtonPress event; if count is greater than zero, a key press generates count pairs of ButtonPress and ButtonRelease events. If count is zero, a key release generates a core pointer ButtonRelease that matches the event generated by the corresponding KeyPress; if count is nonzero, a key release does not cause a ButtonRelease event. A key release never generates a key KeyRelease event.
XkbSA_LockPtrBtn | If the button specified by the MouseKeys default button or button is not locked, a key press causes a ButtonPress event instead of a KeyPress event and locks the button. If the button is already locked or if XkbSA_LockNoUnlock is set in the flags field, a key press is ignored and has no effect. If the corresponding key press was ignored, and if XkbSA_LockNoLock is not set in the flags field, a key release generates a ButtonRelease event instead of a KeyRelease event and unlocks the specified button. If the corresponding key press locked a button, the key release is ignored and has no effect.

The flags field is composed of the bitwise inclusive OR of the masks shown in Table 16.8. A general meaning is given in the table, but the exact meaning depends on the action type:

Pointer Button Action Flags

Flag | Meaning
--- | ---
XkbSA_UseDfltButton | If set, the action uses the pointer button specified by the mk_dflt_btn attribute of the MouseKeys control (see section 10.5.1). Otherwise, the action uses the pointer button specified by the button field.
XkbSA_LockNoLock | If set, and the action type is XkbSA_LockPtrBtn, the server only unlocks the pointer button.
XkbSA_LockNoUnlock | If set, and the action type is XkbSA_LockPtrBtn, the server only locks the pointer button.

XkbPtrBtnAction

### Actions for Changing the Pointer Button Simulated

Actions associated with the XkbPtrDfltAction structure change the mk_dflt_btn attribute of the MouseKeys control (see section 10.5.1):

    typedef struct _XkbPtrDfltAction {
        unsigned char   type;      /* XkbSA_SetPtrDflt */
        unsigned char   flags;     /* controls the pointer button number */
        unsigned char   affect;    /* XkbSA_AffectDfltBtn */
        char            valueXXX;  /* new default button member */
    } XkbPtrDfltAction;

If the MouseKeys control is not enabled, KeyPress and KeyRelease events are treated as though the action is XkbSA_NoAction. Otherwise, this action changes the mk_dflt_btn attribute of the MouseKeys control.

The type field of the XkbPtrDfltAction structure should always be XkbSA_SetPtrDflt.

The flags field is composed of the bitwise inclusive OR of the values shown in Table 16.9 (currently there is only one value defined).

Pointer Default Flags

Flag | Meaning
--- | ---
XkbSA_DfltBtnAbsolute | If set, the value field represents an absolute pointer button. Otherwise, the value field represents the amount to be added to the current default button.

The affect field specifies what changes as a result of this action. The only valid value for the affect field is XkbSA_AffectDfltBtn.

The valueXXX field is a signed character that represents the new button value for the mk_dflt_btn attribute of the MouseKeys control (see section 10.5.1). If XkbSA_DfltBtnAbsolute is set in flags, valueXXX specifies the button to be used; otherwise, valueXXX specifies the amount to be added to the current default button. In either case, illegal button choices are wrapped back around into range. Xkb provides the following macros, to convert between the integer and signed character values in XkbPtrDfltAction structures:

int `XkbSAPtrDfltValue` XkbAction act

act

  action from which to extract group

`XkbSAPtrDfltValue` returns the valueXXX field of act converted to a signed int.

void `XkbSASetPtrDfltValue` XkbPtrDfltAction act int val

act

  action in which to set valueXXX

val

  value to set in valueXXX

`XkbSASetPtrDfltValue` sets the valueXXX field of act from val.

XkbPtrDfltAction
XkbSAPtrDfltValue
XkbSASetPtrDfltValue

### Actions for Locking Modifiers and Group

Actions associated with the XkbISOAction structure lock modifiers and the group according to the ISO9995 specification.

Operated by itself, the XkbISOAction is just a caps lock. Operated simultaneously with another modifier key, it transforms the other key into a locking key. For example, press ISO_Lock, press and release Control_L, release ISO_Lock ends up locking the Control modifier.

The default behavior is to convert:

- {Set,Latch}Mods to: LockMods
- {Set,Latch}Group to: LockGroup
- SetPtrBtn to: LockPtrBtn
- SetControls to: LockControls

The affects field allows you to turn those effects on or off individually. Set XkbSA_ISONoAffectMods to disable the first, XkbSA_ISONoAffectGroup to disable the second, and so forth.

    typedef struct _XkbISOAction {
        unsigned char   type;        /* XkbSA_ISOLock */
        unsigned char   flags;       /* controls changes to group or
                                        modifier state */
        unsigned char   mask;        /* same as mask field of
                                        a modifier description */
        unsigned char   real_mods;   /* same as real_mods field of
                                        a modifier description */
        char            group_XXX;   /* group index or delta group */
        unsigned char   affect;      /* specifies whether to affect
                                        mods, group, ptrbtn, or controls */
        unsigned char   vmods1;      /* derived from vmods field of
                                        a modifier description */
        unsigned char   vmods2;      /* derived from vmods field of
                                        a modifier description */
    } XkbISOAction;

The type field of the XkbISOAction structure should always be XkbSA_ISOLock.

The interpretation of the flags field depends on whether the XkbSA_ISODfltIsGroup is set in the flags field or not.

If the XkbSA_ISODfltIsGroup is set in the flags field, the action is used to change the group state. The remaining valid bits of the flags field are composed of a bitwise inclusive OR using the masks shown in Table 16.10.

ISO Action Flags when XkbSA_ISODfltIsGroup is Set

Flag | Meaning
--- | ---
XkbSA_ISODfltIsGroup | If set, the action is used to change the base group state. Must be set for the remaining bits in this table to carry their interpretations. A key press sets the base group as specified by the group_XXX field and the XkbSA_GroupAbsolute bit of the flags field (see section Note). If no other actions are transformed by the XkbSA_ISOLock action, a key release locks the group. Otherwise, a key release clears group set by the key press.
XkbSA_GroupAbsolute | If set, the group_XXX field represents an absolute group number. Otherwise, it represents a group delta to be added to the current group to determine the new group number.
XkbSA_ISONoAffectMods | If not set, any XkbSA_SetMods or XkbSA_LatchMods actions that occur simultaneously with the XkbSA_ISOLock action are treated as XkbSA_LockMods actions instead.
XkbSA_ISONoAffectGroup | If not set, any XkbSA_SetGroup or XkbSA_LatchGroup actions that occur simultaneously with the XkbSA_ISOLock action are treated as XkbSA_LockGroup actions instead.
XkbSA_ISONoAffectPtr | If not set, any XkbSA_PtrBtn actions that occur simultaneously with the XkbSA_ISOLock action are treated as XkbSA_LockPtrBtn actions instead.
XkbSA_ISONoAffectCtrls | If not set, any XkbSA_SetControls actions that occur simultaneously with the XkbSA_ISOLock action are treated as XkbSA_LockControls actions instead.

If the XkbSA_ISODfltIsGroup is not set in the flags field, the action is used to change the modifier state and the remaining valid bits of the flags field are composed of a bitwise inclusive OR using the masks shown in Table 16.11.

ISO Action Flags when XkbSA_ISODfltIsGroup is Not Set

Flag | Meaning
--- | ---
XkbSA_ISODfltIsGroup | If not set, action is used to change the base modifier state. Must not be set for the remaining bits in this table to carry their interpretations. A key press sets the action modifiers in the keyboard’s base modifiers using the mask, real_mods, vmods1, and vmods2 fields (see section 16.1.3). If no other actions are transformed by the XkbSA_ISOLock action, a key release locks the action modifiers. Otherwise, a key release clears the base modifiers set by the key press.
XkbSA_UseModMapMods | If set, the action modifiers are determined by the modifiers bound by the modifier mapping of the key. Otherwise, the action modifiers are set to the modifiers specified by the mask, real_mods, vmods1, and vmods2 fields.
XkbSA_LockNoLock | If set, the server only unlocks the action modifiers.
XkbSA_LockNoUnlock | If set, the server only locks the action modifiers.
XkbSA_ISONoAffectMods | If not set, any XkbSA_SetMods or XkbSA_LatchMods actions that occur simultaneously with the XkbSA_ISOLock action are treated as XkbSA_LockMods actions instead.
XkbSA_ISONoAffectGroup | If not set, any XkbSA_SetGroup or XkbSA_LatchGroup actions that occur simultaneously with the XkbSA_ISOLock action are treated as XkbSA_LockGroup actions instead.
XkbSA_ISONoAffectPtr | If not set, any XkbSA_PtrBtn actions that occur simultaneously with the XkbSA_ISOLock action are treated as XkbSA_LockPtrBtn actions instead.
XkbSA_ISONoAffectCtrls | If not set, any XkbSA_SetControls actions that occur simultaneously with the XkbSA_ISOLock action are treated as XkbSA_LockControls actions instead.

The group_XXX field represents a signed character. Xkb provides macros to convert between a signed integer value and a signed character as shown in section Note.

The mask, real_mods, vmods1, and vmods2 fields represent the components of an Xkb modifier description (see section 7.2). While the mask and real_mods fields correspond directly to the mask and real_mods fields of an Xkb modifier description, the vmods1 and vmods2 fields are combined to correspond to the vmods field of an Xkb modifier description. Xkb provides macros to convert between the two formats as shown in section 16.1.3.

The affect field is composed of a bitwise inclusive OR using the masks shown in Table 16.11.

ISO Action Affect Field Values

Affect | Meaning
--- | ---
XkbSA_ISONoAffectMods | If XkbSA_ISONoAffectMods is not set, any SA_SetMods or SA_LatchMods actions occurring simultaneously with the XkbISOAction are treated as SA_LockMods instead.
XkbSA_ISONoAffectGroup | If XkbSA_ISONoAffectGroup is not set, any SA_SetGroup or SA_LatchGroup actions occurring simultaneously with the XkbISOAction are treated as SA_LockGroup instead.
XkbSA_ISONoAffectPtr | If XkbSA_ISONoAffectPtr is not set, any SA_PtrBtn actions occurring simultaneously with the XkbISOAction are treated as SA_LockPtrBtn instead.
XkbSA_ISONoAffectCtrls | If XkbSA_ISONoAffectCtrls is not set, any SA_SetControls actions occurring simultaneously with the XkbISOAction are treated as SA_LockControls instead.

XkbISOAction

### Actions for Changing the Active Screen

Actions associated with the XkbSwitchScreenAction action structure change the active screen on a multiscreen display:

This action is optional. Servers are free to ignore the action or any of its flags if they do not support the requested behavior. If the action is ignored, it behaves like XkbSA_NoAction. Otherwise, key press and key release events do not generate an event.

    typedef struct _XkbSwitchScreenAction {
        unsigned char   type;        /* XkbSA_SwitchScreen */
        unsigned char   flags;       /* controls screen switching */
        char            screenXXX;   /* screen number or delta */
    } XkbSwitchScreenAction;

The type field of the XkbSwitchScreenAction structure should always be XkbSA_SwitchScreen.

The flags field is composed of the bitwise inclusive OR of the masks shown in Table 16.13.

Switch Screen Action Flags

Flag | Meaning
--- | ---
XkbSA_SwitchAbsolute | If set, the screenXXX field represents the index of the new screen. Otherwise, it represents an offset from the current screen to the new screen.
XkbSA_SwitchApplication | If not set, the action should switch to another screen on the same server. Otherwise, it should switch to another X server or application that shares the same physical display.

The screenXXX field is a signed character value that represents either the relative or absolute screen index, depending on the state of the XkbSA_SwitchAbsolute bit in the flags field. Xkb provides the following macros to convert between the integer and signed character value for screen numbers in XkbSwitchScreenAction structures:

int `XkbSAScreen` XkbSwitchScreenAction act

act

  action from which to extract screen

`XkbSAScreen` returns the screenXXX field of act converted to a signed int.

void `XkbSASetScreen` XkbSwitchScreenAction act int s

act

  action in which to set screenXXX

s

  value to set in screenXXX

`XkbSASetScreen` sets the screenXXX field of act from s.

XkbSwitchScreenAction
XkbSAScreen
XkbSASetScreen

### Actions for Changing Boolean Controls State

Actions associated with the XkbCtrlsAction structure change the state of the boolean controls (see section 10.1):

    typedef struct _XkbCtrlsAction {
        unsigned char     type;        /* XkbSA_SetControls,
                                          XkbSA_LockControls */
        unsigned char     flags;       /* with type, controls enabling
                                          and disabling of controls */
        unsigned char     ctrls3;      /* ctrls0 through ctrls3
                                          represent the boolean controls */
        unsigned char     ctrls2;      /* ctrls0 through ctrls3
                                          represent the boolean controls */
        unsigned char     ctrls1;      /* ctrls0 through ctrls3
                                          represent the boolean controls */
        unsigned char     ctrls0;      /* ctrls0 through ctrls3
                                          represent the boolean controls */
    } XkbCtrlsAction;

The type field can have any one of the values shown in Table 16.14.

Controls Action Types

Type | Effect
--- | ---
XkbSA_SetControls | A key press enables any boolean controls specified in the ctrls fields that were not already enabled at the time of the key press. A key release disables any controls enabled by the key press. This action can cause XkbControlsNotify events (see section 10.1).
XkbSA_LockControls | If the XkbSA_LockNoLock bit is not set in the flags field, a key press enables any controls specified in the ctrls fields that were not already enabled at the time of the key press. If the XkbSA_LockNoUnlock bit is not set in the flags field, a key release disables any controls specified in the ctrls fields that were not already disabled at the time of the key press. This action can cause XkbControlsNotify events (see section 10.1).

The flags field is composed of the bitwise inclusive OR of the masks shown in Table 16.15.

Control Action Flags

Flag | Meaning
--- | ---
XkbSA_LockNoLock | If set, and the action type is XkbSA_LockControls, the server only disables controls.
XkbSA_LockNoUnlock | If set, and the action type is XkbSA_LockControls, the server only enables controls.

The XkbSA_SetControls action implements a key that enables a boolean control when pressed and disables it when released. The XkbSA_LockControls action is used to implement a key that toggles the state of a boolean control each time it is pressed and released. The XkbSA_LockNoLock and XkbSA_LockNoUnlock flags allow modifying the toggling behavior to only unlock or only lock the boolean control.

The ctrls0, ctrls1, ctrls2, and ctrls3 fields represent the boolean controls in the enabled_ctrls field of the controls structure (see section 10.1). Xkb provides the following macros, to convert between the two formats:

unsigned int `XkbActionCtrls` XkbCtrlsAction act

act

  action from which to extract controls

`XkbActionCtrls` returns the ctrls fields of act converted to an unsigned int.

void `XkbActionSetCtrls` XkbCtrlsAction act unsigned int ctrls

act

  action in which to set ctrls0-ctrls3

ctrls

  value to set in ctrls0-ctrls3

`XkbActionSetCtrls` sets the ctrls0 through ctrls3 fields of act from ctrls.

XkbCtrlsAction
XkbActionCtrls
XkbActionSetCtrls

### Actions for Generating Messages

Actions associated with the XkbMessageAction structure generate XkbActionMessage events:

    #define             XkbActionMessageLength                  6

    typedef struct _XkbMessageAction {
        unsigned char   type;             /* XkbSA_ActionMessage */
        unsigned char   flags;            /* controls event generation via
                                             key presses and releases */
        unsigned char   message[XkbActionMessageLength];    /* message */
    } XkbMessageAction;

The type field of the XkbMessageAction structure should always be XkbSA_ActionMessage.

The flags field is composed of the bitwise inclusive OR of the masks shown in Table 16.16.

Message Action Flags

Flag | Meaning
--- | ---
XkbSA_MessageOnPress | If set, key press events generate an XkbActionMessage event that reports the keycode, event type, and contents of the message field.
XkbSA_MessageOnRelease | If set, key release events generate an XkbActionMessage event that reports the keycode, event type, and contents of the message field.
XkbSA_MessageGenKeyEvent | If set, key press and key release events generate KeyPress and KeyRelease events, regardless of whether they generate XkbActionMessage events.

The message field is an array of XkbActionMessageLength unsigned characters and may be set to anything the keymap designer wishes.

#### Detecting Key Action Messages

To receive XkbActionMessage events by calling either `XkbSelectEvents` or `XkbSelectEventDetails` (see section 4.3).

To receive XkbActionMessage events under all possible conditions, use `XkbSelectEvents` and pass XkbActionMessageMask in both bits_to_change and values_for_bits.

The XkbActionMessage event has no event details. However, you can call `XkbSelectEventDetails` using XkbActionMessage as the event_type and specifying XkbAllActionMessagesMask in bits_to_change and values_for_bits. This has the same effect as a call to `XkbSelectEvents`.

The structure for the XkbActionMessage event is defined as follows:

    typedef struct _XkbActionMessage {
        int            type;             /* Xkb extension base event code */
        unsigned long  serial;           /* X server serial number for event */
        Bool           send_event;       /* True ⇒ synthetically generated */
        Display *      display;          /* server connection where event generated */
        Time           time;             /* server time when event generated */
        int            xkb_type;         /* XkbActionMessage */
        int            device;           /* Xkb device ID,
                                            will not be XkbUseCoreKbd */
        KeyCode        keycode;          /* keycode of key triggering event */
        Bool           press;            /* True ⇒ key press,
                                            False ⇒ release */
        Bool           key_event_follows;/* True ⇒ KeyPress/KeyRelease follows */
        char           message[XkbActionMessageLength+1];  /* message text */
    } XkbActionMessageEvent;

The keycode is the keycode of the key that was pressed or released. The press field specifies whether the event was the result of a key press or key release.

The key_event_follows specifies whether a KeyPress (if press is True) or KeyRelease (if press is False) event is also sent to the client. As with all other Xkb events, XkbActionMessageEvents are delivered to all clients requesting them, regardless of the current keyboard focus. However, the KeyPress or KeyRelease event that conditionally follows an XkbActionMessageEvent is sent only to the client selected by the current keyboard focus. key_event_follows is True only for the client that is actually sent the following KeyPress or KeyRelease event.

The message field is set to the message specified in the action and is guaranteed to be NULL -terminated; the Xkb extension forces a NULL into message [ XkbActionMessageLength ].

events XkbActionMessage
XkbActionMessageEvent
XkbMessageAction

### Actions for Generating a Different Keycode

Actions associated with the XkbRedirectKeyAction structure generate KeyPress and KeyRelease events containing a keycode different from the key that was pressed or released:

    typedef struct      _XkbRedirectKeyAction {
        unsigned char      type;          /* XkbSA_RedirectKey */
        unsigned char      new_key;       /* keycode to be put in event */
        unsigned char      mods_mask;     /* mask of real mods to be reset */
        unsigned char      mods;          /* mask of real mods to take values from */
        unsigned char      vmods_mask0;   /* first half of mask of virtual mods
                                             to be reset */
        unsigned char      vmods_mask1;   /* other half of mask of virtual mods
                                             to be reset */
        unsigned char      vmods0;        /* first half of mask of virtual mods
                                             to take values from */
        unsigned char      vmods1;        /* other half of mask of virtual mods
                                             to take values from */
    } XkbRedirectKeyAction;

The type field for the XkbRedirectKeyAction structure should always be XkbSA_RedirectKey.

Key presses cause a KeyPress event for the key specified by the new_key field instead of the actual key. The state reported in this event reports the current effective modifiers changed as follows: any real modifiers selected by the mods_mask field are set to corresponding values from the mods field. Any real modifiers bound to the virtual modifiers specified by the vmods_mask0 and vmods_mask1 fields are either set or cleared, depending on the corresponding values in the vmods0 and vmods1 fields. If the real and virtual modifier definitions specify conflicting values for a single modifier, the real modifier definition has priority.

Key releases cause a KeyRelease event for the key specified by the new_key field instead of the actual key. The state for this event consists of the effective keyboard modifiers at the time of the release, changed as described previously.

The XkbSA_RedirectKey action normally redirects to another key on the same device as the key that caused the event, unless that device does not belong to the input extension KeyClass, in which case this action causes an event on the core keyboard device. (The input extension categorizes devices by breaking them into classes. Keyboards, and other input devices with keys, are classified as KeyClass devices by the input extension.)

The vmods_mask0 and vmods_mask1 fields actually represent one vmods_mask value, as described in . Xkb provides the following macros, to convert between the two formats:

unsigned int `XkbSARedirectVModsMask` XkbRedirectKeyAction act

act

  action from which to extract vmods

`XkbSARedirectVModsMask` returns the vmods_mask0 and vmods_mask1 fields of act converted to an unsigned int.

void `XkbSARedirectSetVModsMask` XkbRedirectKeyAction act unsigned int vm

act

  action in which to set vmods

vm

  new value for virtual modifier mask

`XkbSARedirectSetVModsMask` sets the vmods_mask0 and vmods_mask1 fields of act from vm.

Similarly, the vmods0 and vmods1 fields actually represent one vmods value, as described in . To convert between the two formats, Xkb provides the following convenience macros:

unsigned int `XkbSARedirectVMods` XkbRedirectKeyAction act

act

  action from which to extract vmods

`XkbSARedirectVModsMask` returns the vmods0 and vmods1 fields of act converted to an unsigned int.

void `XkbSARedirectSetVMods` XkbRedirectKeyAction act unsigned int v

act

  action in which to set vmods

v

  new value for virtual modifiers

`XkbSARedirectSetVModsMask` sets the vmods0 and vmods1 of act from v.

XkbRedirectKeyAction
XkbSARedirectVModsMask
XkbSARedirectSetVModsMask
XkbSARedirectVMods
XkbSARedirectSetVMods

### Actions for Generating DeviceButtonPress and DeviceButtonRelease

Actions associated with XkbDeviceBtnAction structures generate DeviceButtonPress and DeviceButtonRelease events instead of normal KeyPress and KeyRelease events:

    typedef struct _XkbDeviceBtnAction {
        unsigned char    type;      /* XkbSA_DeviceBtn, XkbSA_LockDeviceBtn */
        unsigned char    flags;     /* with type, specifies locking or unlocking */
        unsigned char    count;     /* controls number of DeviceButtonPress
                                       and Release events */
        unsigned char    button;    /* index of button on device */
        unsigned char    device;    /* device ID of an X input extension device */
    } XkbDeviceBtnAction;

The type field can have any one of the values shown in Table 16.17.

Device Button Action Types

Type | Effect
--- | ---
XkbSA_DeviceBtn | If the button specified by this action is logically down, the key press and corresponding release are ignored and have no effect. If the device or button specified by this action are illegal, this action behaves like XkbSA_NoAction. Otherwise, key presses cause one or more input extension device events instead of the usual key press event. If the count field is zero, a key press generates a single DeviceButtonPress event. If count is greater than zero, a key press event generates count pairs of DeviceButtonPress and DeviceButtonRelease events. If count is zero, a key release generates an input extension DeviceButtonRelease event that matches the event generated by the corresponding key press. If count is nonzero, a key release does not cause a DeviceButtonRelease event. Key releases never cause KeyRelease events.
XkbSA_LockDeviceBtn | If the device or button specified by this action are illegal, this action behaves like XkbSA_NoAction. Otherwise, if the specified button is not locked and the XkbSA_LockNoLock bit is not set in the flags field, a key press generates an input extension DeviceButtonPress event instead of a KeyPress event and locks the button. If the button is already locked or if XkbSA_LockNoLock bit is set in the flags field, the key press is ignored and has no effect. If the corresponding key press was ignored, and if the XkbSA_LockNoUnlock bit is not set in the flags field, a key release generates an input extension DeviceButtonRelease event instead of a KeyRelease event and unlocks the button. If the corresponding key press locked a button, the key release is ignored and has no effect.

The flags field is composed of the bitwise inclusive OR of the masks shown in Table 16.18.

Device Button Action Flags

Flag | Meaning
--- | ---
XkbSA_LockNoLock | If set, and the action type is XkbSA_LockDeviceBtn, the server only unlocks the button.
XkbSA_LockNoUnlock | If set, and the action type is XkbSA_LockDeviceBtn, the server only locks the button.

XkbDeviceBtnAction

### Actions for Simulating Events from Device Valuators

A valuator manipulates a range of values for some entity, like a mouse axis, a slider or a dial. Actions associated with XkbDeviceValuatorAction structures are used to simulate events from one or two input extension device valuators.

valuator

    typedef struct _XkbDeviceValuatorAction {
        unsigned char    type;        /* XkbSA_DeviceValuator */
        unsigned char    device;      /* device ID */
        unsigned char    v1_what;     /* determines how valuator is
                                         to behave for valuator 1 */
        unsigned char    v1_ndx;      /* specifies a real valuator */
        unsigned char    v1_value;    /* the value for valuator 1 */
        unsigned char    v2_what;     /* determines how valuator is
                                         to behave for valuator 2 */
        unsigned char    v2_ndx;      /* specifies a real valuator */
        unsigned char    v2_value;    /* the value for valuator 1 */
    } XkbDeviceValuatorAction;

If device is illegal or if neither v1_ndx nor v2_ndx specifies a legal valuator, this action behaves like XkbSA_NoAction.

The low four bits of v1_what and v2_what specify the corresponding scale value (denoted val<n>Scale in Table 16.17), if needed. The high four bits of v1_what and v2_what specify the operation to perform to set the values. The high four bits of v1_what and v2_what can have the values shown in Table 16.17; the use of val<n>Scale is shown in that table also.

Device Valuator v<n>_what High Bits Values

Value of high bits | Effect
--- | ---
XkbSA_IgnoreVal | No action
XkbSA_SetValMin | v<n>_value is set to its minimum legal value.
XkbSA_SetValCenter | v<n>_valueis centered (to (max-min)/2).
XkbSA_SetValMax | v<n>_value is set to its maximum legal value.
XkbSA_SetValRelative | v<n>_value * (2 val<n>Scale) is added to v<n>_value.
XkbSA_SetValAbsolute | v<n>_value is set to (2 val<n>Scale).

Illegal values for XkbSA_SetValRelative or XkbSA_SetValAbsolute are clamped into range. Note that all of these possibilities are legal for absolute valuators. For relative valuators, only XkbSA_SetValRelative is permitted. Part of the input extension description of a device is the range of legal values for all absolute valuators, whence the maximum and minimum legal values shown in Table 16.17.

The following two masks are provided as a convenience to select either portion of v1_what or v2_what:

    #define XkbSA_ValOpMask         (0x70)
    #define XkbSA_ValScaleMask      (0x07)

v1_ndx and v2_ndx specify valuators that actually exists. For example, most mice have two valuators (x and y axes) so the only legal values for a mouse would be 0 and 1. For a dial box with eight dials, any value in the range 0..7 would be correct.

XkbDeviceValuatorAction

### Obtaining Key Actions for Keys from the Server

To update the actions (the key_acts array) for a subset of the keys in a keyboard description, use `XkbGetKeyActions`.

Status `XkbGetKeyActions` Display *dpy unsigned int first unsigned int num XkbDescPtr xkb

dpy

  connection to X server

first

  keycode of first key of interest

num

  number of keys desired

xkb

  pointer to keyboard description where result is stored

`XkbGetKeyActions` sends a request to the server to obtain the actions for num keys on the keyboard starting with key first. It waits for a reply and returns the actions in the server->key_acts field of xkb. If successful, `XkbGetKeyActions` returns Success. The xkb parameter must be a pointer to a valid Xkb keyboard description.

If the server map in the xkb parameter has not been allocated, `XkbGetKeyActions` allocates and initializes it before obtaining the actions.

If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, `XkbGetKeyActions` returns BadAccess. If num is less than 1 or greater than XkbMaxKeyCount, `XkbGetKeyActions` returns BadValue. If any allocation errors occur, `XkbGetKeyActions` returns BadAlloc.

XkbGetKeyActions

### Changing the Number of Actions Bound to a Key

To change the number of actions bound to a key, use `XkbResizeKeyActions`.

XkbAction *`XkbResizeKeyActions` XkbDescRec *xkb int key int needed

xkb

  keyboard description to change

key

  keycode of key to change

needed

  new number of actions required

The xkb parameter points to the keyboard description containing the key whose number of actions is to be changed. The key parameter is the keycode of the key to change, and needed specifies the new number of actions required for the key.

`XkbResizeKeyActions` reserves the space needed for the actions and returns a pointer to the beginning of the new array that holds the actions. It can change the acts, num_acts, and size_acts fields of xkb->server if it is necessary to reallocate the acts array.

If needed is greater than the current number of keysyms for the key, `XkbResizeKeyActions` initializes all new actions in the array to NoAction.

Because the number of actions needed by a key is normally computed as width * number of groups, and `XkbResizeKeyActions` does not modify either the width or number of groups for the key, a discrepancy exists on return from `XkbResizeKeyActions` between the space allocated for the actions and the number required. The unused entries in the list of actions returned by `XkbResizeKeyActions` are not preserved across future calls to any of the map editing functions, so you must update the key actions (which updates the width and number of groups for the key) before calling another allocator function. A call to `XkbChangeTypesOfKey` updates these.

If any allocation errors occur while resizing the number of actions bound to the key, `XkbResizeKeyActions` returns NULL.

A change to the number of actions bound to a key should be accompanied by a change in the number of symbols bound to a key. Refer to section 15.3.7 for more information on changing the number of symbols bound to a key.

XkbResizeKeyActions
XkbKeyHasActions
XkbKeyNumActions
XkbKeyActionsPtr
XkbKeyAction
XkbKeyActionEntry

## Key Behavior

Key behavior refers to the demeanor of a key. For example, the expected behavior of the CapsLock key is that it logically locks when pressed, and then logically unlocks when pressed again.

### Radio Groups

Keys that belong to the same radio group have the XkbKB_RadioGroup type in the type field and the radio group index specified in the data field in the XkbBehavior structure. If the radio group has a name in the XkbNamesRec structure, the radio group index is the index into the radio_group array in the XkbNamesRec structure. A radio group key when pressed stays logically down until another key in the radio group is pressed, when the first key becomes logically up and the new key becomes logically down. Setting the XkbKB_RGAllowNone bit in the behavior for all of the keys of the radio group means that pressing the logically down member of the radio group causes it to logically release, in which case none of the keys of the radio group would be logically down. If XkbKB_RGAllowNone is not set, there is no way to release the logically down member of the group.

The low five bits of the data field of the XkbBehavior structure are the group number, the high three bits are flags. The only flag currently defined is:

    #define      XkbKB_RGAllowNone      0x80

### The XkbBehavior Structure

The behaviors field of the server map is an array of XkbBehavior structures, indexed by keycode, and contains the behavior for each key. The XkbBehavior structure is defined as follows:

    typedef struct _XkbBehavior {
        unsigned char  type;              /* behavior type + optional
                                             XkbKB_Permanent bit */
        unsigned char  data;
    } XkbBehavior;

The type field specifies the Xkb behavior, and the value of the data field depends on the type. Xkb supports the key behaviors shown in Table 16.20.

Key Behaviors

Type | Effect
--- | ---
XkbKB_Default | Press and release events are processed normally. The data field is unused.
XkbKB_Lock | If a key is logically up (that is, the corresponding bit of the core key map is cleared) when it is pressed, the key press is processed normally and the corresponding release is ignored. If the key is logically down when pressed, the key press is ignored but the corresponding release is processed normally. The data field is unused.
XkbKB_RadioGroup | If another member of the radio group is logically down (all members of the radio group have the same index, specified in data) when a key is pressed, the server synthesizes a key release for the member that is logically down and then processes the new key press event normally. If the key itself is logically down when pressed, the key press event is ignored, but the processing of the corresponding key release depends on the value of the XkbKB_RGAllowNone bit in flags. If it is set, the key release is processed normally; otherwise, the key release is also ignored. All other key release events are ignored.
XkbKB_Overlay1 | If the Overlay1 control is enabled (see section 10.4), data is interpreted as a keycode, and events from this key are reported as if they came from data’s keycode. Otherwise, press and release events are processed normally.
XkbKB_Overlay2 | If the Overlay2 control is enabled (see section 10.4), data is interpreted as a keycode, and events from this key are reported as if they came from data’s keycode. Otherwise, press and release events are processed normally.

Xkb also provides the mask, XkbKB_Permanent to specify whether the key behavior type should be simulated by Xkb or whether the key behavior describes an unalterable physical, electrical, or software aspect of the keyboard. If the XkbKB_Permanent bit is not set in the type field, Xkb simulates the behavior in software. Otherwise, Xkb relies upon the keyboard to implement the behavior.

XkbBehavior

### Obtaining Key Behaviors for Keys from the Server

To obtain the behaviors (the behaviors array) for a subset of the keys in a keyboard description from the server, use `XkbGetKeyBehaviors`:

Status `XkbGetKeyBehaviors` Display *dpy unsigned int first unsigned int num XkbDescPtr xkb

dpy

  connection to server

first

  keycode of first key to get

num

  number of keys for which behaviors are desired

xkb

  Xkb description to contain the result

`XkbGetKeyBehaviors` sends a request to the server to obtain the behaviors for num keys on the keyboard starting with the key whose keycode is first. It waits for a reply and returns the behaviors in the server->behaviors field of xkb. If successful, `XkbGetKeyBehaviors` returns Success.

If the server map in the xkb parameter has not been allocated, `XkbGetKeyBehaviors` allocates and initializes it before obtaining the actions.

If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, `XkbGetKeyBehaviors` returns BadAccess. If num is less than 1 or greater than XkbMaxKeyCount, `XkbGetKeyBehaviors` returns BadValue. If any allocation errors occur, `XkbGetKeyBehaviors` returns BadAlloc.

XkbGetKeyBehaviors

## Explicit Components—Avoiding Automatic Remapping by the Server

Whenever a client remaps the keyboard using core protocol requests, Xkb examines the map to determine likely default values for the components that cannot be specified using the core protocol (see section 17.1.2 for more information on how Xkb chooses the default values).

This automatic remapping might replace definitions explicitly requested by an application, so the Xkb keyboard description defines an explicit components mask for each key. Any aspects of the automatic remapping listed in the explicit components mask for a key are not changed by the automatic keyboard mapping.

The explicit components masks are held in the explicit field of the server map, which is an array indexed by keycode. Each entry in this array is a mask that is a bitwise inclusive OR of the values shown in Table 16.21.

Explicit Component Masks

Bit in Explicit Mask | Value | Protects Against
--- | --- | ---
ExplicitKeyType1 | (1<<0) | Automatic determination of the key type associated with Group1.
ExplicitKeyType2 | (1<<1) | Automatic determination of the key type associated with Group2.
ExplicitKeyType3 | (1<<2) | Automatic determination of the key type associated with Group3.
ExplicitKeyType4 | (1<<3) | Automatic determination of the key type associated with Group4.
ExplicitInterpret | (1<<4) | Application of any of the fields of a symbol interpretation to the key in question.
ExplicitAutoRepeat | (1<<5) | Automatic determination of auto-repeat status for the key, as specified in a symbol interpretation.
ExplicitBehavior | (1<<6) | Automatic assignment of the XkbKB_Lock behavior to the key, if the XkbSI_LockingKey flag is set in a symbol interpretation.
ExplicitVModMap | (1<<7) | Automatic determination of the virtual modifier map for the key based on the actions assigned to the key and the symbol interpretations that match the key.

### Obtaining Explicit Components for Keys from the Server

To obtain the explicit components (the explicit array) for a subset of the keys in a keyboard description, use `XkbGetKeyExplicitComponents`.

Status `XkbGetKeyExplicitComponents` Display *dpy unsigned int first unsigned int num XkbDescPtr xkb

dpy

  connection to server

first

  keycode of first key to fetch

num

  number of keys for which to get explicit info

xkb

  Xkb description in which to put results

`XkbGetKeyExplicitComponents` sends a request to the server to obtain the explicit components for num keys on the keyboard starting with key first. It waits for a reply and returns the explicit components in the server->explicit array of xkb. If successful, `XkbGetKeyExplicitComponents` returns Success. The xkb parameter must be a pointer to a valid Xkb keyboard description.

If the server map in the xkb parameter has not been allocated, `XkbGetKeyExplicitComponents` allocates and initializes it before obtaining the actions.

If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, `XkbGetKeyExplicitComponents` returns BadMatch. If num is less than 1 or greater than XkbMaxKeyCount, `XkbGetKeyExplicitComponents` returns BadValue. If any allocation errors occur, `XkbGetKeyExplicitComponents` returns BadAlloc.

XkbGetKeyExplicitComponents

## Virtual Modifier Mapping

The vmods member of the server map is a fixed-length array containing XkbNumVirtualMods entries. Each entry corresponds to a virtual modifier and provides the binding of the virtual modifier to the real modifier bits. Each entry in the vmods array is a bitwise inclusive OR of the legal modifier masks:

- ShiftMask
- LockMask
- ControlMask
- Mod1Mask
- Mod2Mask
- Mod3Mask
- Mod4Mask
- Mod5Mask

The vmodmap member of the server map is similar to the modmap array of the client map (see section 15.4), but is used to define the virtual modifier mapping for each key. Like the modmap member, it is indexed by keycode, and each entry is a mask representing the virtual modifiers bound to the corresponding key:

- Each of the bits in a vmodmap entry represents an index into the vmods member. That is, bit 0 of a vmodmap entry refers to index 0 of the vmods array, bit 1 refers to index 1, and so on.

- If a bit is set in the vmodmap entry for a key, that key is bound to the corresponding virtual modifier in the vmods array.

The vmodmap and vmods members of the server map are the master virtual modifier definitions. Xkb automatically propagates any changes to these fields to all other fields that use virtual modifier mappings.

The overall relationship of fields dealing with virtual modifiers in an Xkb keyboard description are shown in Figure 16.2.

Virtual Modifier Relationships

### Obtaining Virtual Modifier Bindings from the Server

To obtain a subset of the virtual modifier bindings (the vmods array) in a keyboard description, use `XkbGetVirtualMods`:

Status `XkbGetVirtualMods` Display *dpy unsigned int which XkbDescPtr xkb

dpy

  connection to server

which

  mask indicating virtual modifier bindings to get

xkb

  Xkb description where results will be placed

`XkbGetVirtualMods` sends a request to the server to obtain the vmods entries for the virtual modifiers specified in the mask, which, and waits for a reply. See section 7.1 for a description of how to determine the virtual modifier mask. For each bit set in which, `XkbGetVirtualMods` updates the corresponding virtual modifier definition in the server->vmods array of xkb. The xkb parameter must be a pointer to a valid Xkb keyboard description. If successful, `XkbGetVirtualMods` returns Success.

If the server map has not been allocated in the xkb parameter, `XkbGetVirtualMods` allocates and initializes it before obtaining the virtual modifier bindings.

If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, `XkbGetVirtualMods` returns BadMatch. Any errors in allocation cause `XkbGetVirtualMods` to return BadAlloc.

XkbGetVirtualMods

### Obtaining Per-Key Virtual Modifier Mappings from the Server

To obtain the virtual modifier map (the vmodmap array) for a subset of the keys in a keyboard description, use `XkbGetKeyVirtualModMap`:

Status `XkbGetKeyVirtualModMap` Display *dpy unsigned int first unsigned int num XkbDescPtr xkb

dpy

  connection to server

first

  keycode of first key to fetch

num

  # keys for which virtual mod maps are desired

xkb

  Xkb description where results will be placed

`XkbGetKeyVirtualModmap` sends a request to the server to obtain the virtual modifier mappings for num keys on the keyboard starting with key first. It waits for a reply and returns the virtual modifier mappings in the server->vmodmap array of xkb. If successful, `XkbGetKeyVirtualModMap` returns Success. The xkb parameter must be a pointer to a valid Xkb keyboard description

If the server map in the xkb parameter has not been allocated, `XkbGetKeyVirtualModMap` allocates and initializes it before obtaining the virtual modifier mappings.

If the server does not have a compatible version of Xkb, or the Xkb extension has not been properly initialized, `XkbGetKeyVirtualModMap` returns BadMatch. If num is less than 1 or greater than XkbMaxKeyCount, `XkbGetKeyVirtualModMap` returns BadValue. If any allocation errors occur, `XkbGetKeyVirtualModMap` returns BadAlloc.

XkbGetKeyVirtualModMap
server map
map server