The core protocol specifies that certain keysyms, when bound to modifiers, affect the rules of keycode to keysym interpretation for all keys; for example, when the Num_Lock keysym is bound to some modifier, that modifier is used to select between shifted and unshifted state for the numeric keypad keys. The core protocol does not provide a convenient way to determine the mapping of modifier bits (in particular Mod1 through Mod5) to keysyms such as Num_Lock and Mode_switch. Using the core protocol only, a client application must retrieve and search the modifier map to determine the keycodes bound to each modifier, and then retrieve and search the keyboard mapping to determine the keysyms bound to the keycodes. It must repeat this process for all modifiers whenever any part of the modifier mapping is changed. Xkb alleviates these problems by defining virtual modifiers. In addition to the eight core modifiers, referred to as the real modifiers, real modifiers modifiersreal Xkb provides a set of sixteen named virtual modifiers. virtual modifiers modifiersvirtual Each virtual modifier can be bound to any set of the real modifiers ( Shift, Lock, Control, and Mod1 – Mod5). The separation of function from physical modifier bindings makes it easier to specify more clearly the intent of a binding. X servers do not all assign modifiers the same way — for example, Num_Lock might be bound to Mod2 for one vendor and to Mod4 for another. This makes it cumbersome to automatically remap the keyboard to a desired configuration without some kind of prior knowledge about the keyboard layout and bindings. With XKB, applications can use virtual modifiers to specify the desired behavior, without regard for the actual physical bindings in effect. Virtual modifiers are named by converting their string name to an X Atom and storing the Atom in the names.vmods array in an XkbDescRec structure (see section 6.1). The position of a name Atom in the names.vmods array defines the bit position used to represent the virtual modifier and also the index used when accessing virtual modifier information in arrays: the name in the i-th (0 relative) entry of names.vmods is the i-th virtual modifier, represented by the mask (1<<i). Throughout Xkb, various functions have a parameter that is a mask representing virtual modifier choices. In each case, the i-th bit (0 relative) of the mask represents the i-th virtual modifier. To set the name of a virtual modifier, use XkbSetNames, using XkbVirtualModNamesMask in which and the name in the xkb argument; to retrieve indicator names, use XkbGetNames. These functions are discussed in . XkbModsRec An Xkb modifier definition modifier definition enumerates a collection of real and virtual modifiers but does not in itself bind those modifiers to any particular key or to each other. Modifier definitions are included in a number of structures in the keyboard description to define the collection of modifiers that affect or are affected by some other entity. A modifier definition is relevant only in the context of some other entity such as an indicator map, a control, or a key type. (See section 8.2.2, section 10.8, and section 15.2.) typedef struct _XkbMods { unsigned char mask; /* real_mods | vmods mapped to real modifiers */ unsigned char real_mods; /* real modifier bits */ unsigned short vmods; /* virtual modifier bits */ } XkbModsRec, *XkbModsPtr; An Xkb modifier definition consists of a set of bit masks corresponding to the eight real modifiers (real_mods); a similar set of bitmasks corresponding to the 16 named virtual modifiers (vmods); and an effective mask (mask). The effective mask represents the set of all real modifiers that can logically be set either by setting any of the real modifiers or by setting any of the virtual modifiers in the definition. mask is derived from the real and virtual modifiers and should never be explicitly changed — it contains all of the real modifiers specified in the definition (real_mods) plus any real modifiers that are bound to the virtual modifiers specified in the definition (vmods). The binding of the virtual modifiers to real modifiers is exterior to the modifier definition. Xkb automatically recomputes the mask field of modifier definitions as necessary. Whenever you access a modifier definition that has been retrieved using an Xkb library function, the mask field will be correct for the keyboard mapping of interest. The binding of virtual modifiers to real modifiers is defined by the server.vmods array in an XkbDescRec structure. Each entry contains the real modifier bits that are bound to the virtual modifier corresponding to the entry. The overall relationship of fields dealing with virtual modifiers in the server keyboard description are shown in Figure 16.2. Xkb maintains a virtual modifier mapping, virtual modifier mapping modifiersvirtual mapping which lists the virtual modifiers associated with, or bound to, each key. The real modifiers bound to a virtual modifier always include all of the modifiers bound to any of the keys that specify that virtual modifier in their virtual modifier mapping. The server.vmodmap array indicates which virtual modifiers are bound to each key; each entry is a bitmask for the virtual modifier bits. The server.vmodmap array is indexed by keycode. 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 (see section 16.4). For example, if Mod3 is bound to the Num_Lock key by the core protocol modifier mapping, and the NumLock virtual modifier is bound to they Num_Lock key by the virtual modifier mapping, Mod3 is added to the set of modifiers associated with NumLock. The virtual modifier mapping is normally updated whenever actions are automatically applied to symbols (see section 16.4 for details), and few applications should need to change the virtual modifier mapping explicitly. Use XkbGetMap (see section 14.2) to get the virtual modifiers from the server or use XkbGetVirtualMods (see section 16.4.1) to update a local copy of the virtual modifiers bindings from the server. To set the binding of a virtual modifier to a real modifier, use XkbSetMap (see section 14.3). To determine the mapping of virtual modifiers to core X protocol modifiers, use XkbVirtualModsToReal. XkbVirtualModsToReal Bool XkbVirtualModsToReal XkbDescPtr xkb unsigned int virtual_mask unsigned int *mask_rtrn xkb keyboard description for input device virtual_mask virtual modifier mask to translate mask_rtrn backfilled with real modifiers If the keyboard description defined by xkb includes bindings for virtual modifiers, XkbVirtualModsToReal uses those bindings to determine the set of real modifiers that correspond to the set of virtual modifiers specified in virtual_mask. The virtual_mask parameter is a mask specifying the virtual modifiers to translate; the i-th bit (0 relative) of the mask represents the i-th virtual modifier. If mask_rtrn is non- NULL, XkbVirtualModsToReal backfills it with the resulting real modifier mask. If the keyboard description in xkb does not include virtual modifier bindings, XkbVirtualModsToReal returns False; otherwise, it returns True. It is possible for a local (client-side) keyboard description (the xkb parameter) to not contain any virtual modifier information (simply because the client has not requested it) while the server’s corresponding definition may contain virtual modifier information. An unbound virtual modifier is one that is not bound to any real modifier ( server->vmods [virtual_modifier_index] is zero). Some Xkb operations ignore modifier definitions in which the virtual modifiers are unbound. Consider this example: if (state matches {Shift}) Do OneThing; if (state matches {Shift+NumLock}) Do Another; If the NumLock virtual modifier is not bound to any real modifiers, the effective masks for these two cases are identical (that is, contain only Shift). When it is essential to distinguish between OneThing and Another, Xkb considers only those modifier definitions for which all virtual modifiers are bound. modifiersnames The Xkb extension does not require any specific virtual modifier names. However, everyone benefits if the same names are used for common modifiers. The following names are suggested: NumLock ScrollLock Alt Meta AltGr LevelThree If the second (0-relative) entry in names.vmods contains the Atom for "NumLock", then 0x4 (1<<2) is the virtual modifier bit for the NumLock virtual modifier. If server.vmods [2] contains Mod3Mask, then the NumLock virtual modifier is bound to the Mod3 real modifier. A virtual modifier definition for this example would have: real_mods = 0 vmods = 0x4 (NumLock named virtual modifier) mask = 0x20 (Mod3Mask) Continuing the example, if the keyboard has a Num_Lock keysym bound to the key with keycode 14, and the NumLock virtual modifier is bound to this key, server.vmodmap[14] contains 0x4. Finally, if the keyboard also used the real Mod1 modifier for numeric lock operations, the modifier definition below would represent the situation where either the key bound to Mod1 or the NumLock virtual modifier could be used for this purpose: real_mods = 0x8 (Mod1Mask) vmods = 0x4 (NumLock named virtual modifier) mask = 0x28 (Mod1Mask | Mod3Mask)