XKB FUNCTIONS XkbApplyCompatMapToKey(3x11)
NAME
XkbApplyCompatMapToKey - Apply the new compatibility mapping
to an individual key to get its semantics updatedSYNOPSIS
cc [ flag... ] file... -lX11 [ library... ]
Bool XkbApplyCompatMapToKey (XkbDescPtr xkb, KeyCode key,
XkbChangesPtr changes); ARGUMENTS- xkb
keyboard description to be updated- key
key to be updated- changes
notes changes to the Xkb keyboard descriptionDESCRIPTION
XkbApplyCompatMapToKey essentially performs the operation
described in Core Keyboard Mapping to Xkb Keyboard Mapping Transformation to a specific key. This updates the behavior, actions, repeat status, and virtual modifier bindings of the key. Core Keyboard Mapping to Xkb Keyboard When a core protocol keyboard mapping request is received by the server, the server's core keyboard map is updated, and then the Xkb map maintained by the server is updated. Because a client may have explicitly configured some of theXkb keyboard mapping in the server, this automatic regenera-
tion of the Xkb keyboard mapping from the core protocol key-
board mapping should not modify any components of the Xkb keyboard mapping that were explicitly set by a client. The client must set explicit override controls to prevent thisfrom happening (see Explicit Components-Avoiding Automatic
Remapping by the Server). The core-to-Xkb mapping is done as
follows:Explicit Components-Avoiding Automatic Remapping by the
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.This automatic remapping might replace definitions expli-
citly requested by an application, so the Xkb keyboard description defines an explicit components mask for each X Version 11 Last change: libX11 1.3.5 1XKB FUNCTIONS XkbApplyCompatMapToKey(3x11)
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 1. Table 1 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 thefields of a symbol interpreta-
tion to the key in question. ExplicitAutoRepeat (1<<5) Automatic determination ofauto-repeat status for the
key, as specified in a symbol interpretation. ExplicitBehavior (1<<6) Automatic assignment of theXkbKB_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. 1. Map the symbols from the keys in the core keyboard map to groups and symbols on keys in the Xkb keyboard map. The core keyboard mapping is of fixed width, so each keyin the core mapping has the same number of symbols asso-
ciated with it. The Xkb mapping allows a different number of symbols to be associated with each key; those symbols may be divided into a different number of groups(1-4) for each key. For each key, this process therefore
X Version 11 Last change: libX11 1.3.5 2XKB FUNCTIONS XkbApplyCompatMapToKey(3x11)
involves partitioning the fixed number of symbols fromthe core mapping into a set of variable-length groups
with a variable number of symbols in each group. For example, if the core protocol map is of width five, the partition for one key might result in one group with two symbols and another with three symbols. A different key might result in two groups with two symbols plus a third group with one symbol. The core protocol map requires at least two symbols in each of the first two groups. 1a. For each changed key, determine the number of groups represented in the new core keyboard map. This results in a tentative group count for each key in the Xkb map. 1b. For each changed key, determine the number of symbols ineach of the groups found in step 1a. There is one expli-
cit override control associated with each of the four possible groups for each Xkb key, ExplicitKeyType1through ExplicitKeyType4. If no explicit override con-
trol is set for a group, the number of symbols used for that group from the core map is two. If the explicit override control is set for a group on the key, the number of symbols used for that Xkb group from the core map is the width of the Xkb group with one exception: because of the core protocol requirement for at least two symbols in each of groups one and two, the number of symbols used for groups one and two is the maximum of 2 or the width of the Xkb group. 1c. For each changed key, assign the symbols in the core map to the appropriate group on the key. If the total number of symbols required by the Xkb map for a particular key needs more symbols than the core protocol map contains, the additional symbols are taken to be NoSymbol keysyms appended to the end of the core set. If the core map contains more symbols than are needed by the Xkb map, trailing symbols in the core map are discarded. In the absence of an explicit override for group one or two,symbols are assigned in order by group; the first sym-
bols in the core map are assigned to group one, in order, followed by group two, and so on. For example, ifthe core map contained eight symbols per key, and a par-
ticular Xkb map contained 2 symbols for G1 and G2 and three for G3, the symbols would be assigned as (G is group, L is shift level): G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3 If an explicit override control is set for group one ortwo, the symbols are taken from the core set in a some-
what different order. The first four symbols from the core set are assigned to G1L1, G1L2, G2L1, G2L2, X Version 11 Last change: libX11 1.3.5 3XKB FUNCTIONS XkbApplyCompatMapToKey(3x11)
respectively. If group one requires more symbols, they are taken next, and then any additional symbols needed by group two. Group three and four symbols are taken in complete sequence after group two. For example, a key with four groups and three symbols in each group would take symbols from the core set in the following order: G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3 As previously noted, the core protocol map requires at lease two symbols in groups one and two. Because of this, if an explicit override control for an Xkb key is set and group one and / or group two is of width one, it is not possible to generate the symbols taken from the core protocol set and assigned to position G1L2 and / or G2L2. 1d. For each group on each changed key, assign a key type appropriate for the symbols in the group. 1e. For each changed key, remove any empty or redundant groups. At this point, the groups and their associated symbols have been assigned to the corresponding key definitions in the Xkb map. 2. Apply symbol interpretations to modify key operation.This phase is completely skipped if the ExplicitInter-
pret override control bit is set in the explicit con-
trols mask for the Xkb key (see Explicit Components-
Avoiding Automatic Remapping by the Server). 2a. For each symbol on each changed key, attempt to match the symbol and modifiers from the Xkb map to a symbol interpretation describing how to generate the symbol. 2b. When a match is found in step 2a, apply the symbol interpretation to change the semantics associated with the symbol in the Xkb key map. If no match is found, apply a default interpretation. The symbol interpretations used in step 2 are configurable and may be specified using XkbSymInterpretRec structuresreferenced by the sym_interpret field of an XkbCompatMapRec.
Symbol Interpretations - the XkbSymInterpretRec Structure
Symbol interpretations are used to guide the X server whenit modifies the Xkb keymap in step 2. An initial set of sym-
bol interpretations is loaded by the server when it starts. A client may add new ones using XkbSetCompatMap. X Version 11 Last change: libX11 1.3.5 4XKB FUNCTIONS XkbApplyCompatMapToKey(3x11)
Symbol interpretations result in key semantics being set.When a symbol interpretation is applied, the following com-
ponents of server key event processing may be modified for the particular key involved: Virtual modifier map Auto repeatKey behavior (may be set to XkbKB_Lock)
Key action The XkbSymInterpretRec structure specifies a symbol interpretation: typedef struct { KeySym sym; /* keysym of interest or NULL */unsigned char flags; /* XkbSI_AutoRepeat, XkbSI_LockingKey */
unsigned char match; /* specifies how mods is interpreted */ unsigned char mods; /* modifier bits, correspond to eight real modifiers */unsigned char virtual_mod; /* 1 modifier to add to key virtual mod map */
XkbAnyAction act; /* action to bind to symbol position on key */ } XkbSymInterpretRec,*XkbSymInterpretPtr; If sym is not NULL, it limits the symbol interpretation to keys on which that particular keysym is selected by the modifiers matching the criteria specified by mods and match. If sym is NULL, the interpretation may be applied to anysymbol selected on a key when the modifiers match the cri-
teria specified by mods and match.match must be one of the values shown in Table 2 and speci-
fies how the real modifiers specified in mods are to be interpreted. Table 2 Symbol Interpretation Match Criteria__________________________________________________________
Match Criteria Value Effect__________________________________________________________
XkbSI_NoneOf (0) None of the bits that are on
in mods can be set, but other bits can be.XkbSI_AnyOfOrNone (1) Zero or more of the bits that
are on in mods can be set, as well as others.XkbSI_AnyOf (2) One or more of the bits that
are on in mods can be set, as well as any others.XkbSI_AllOf (3) All of the bits that are on in
mods must be set, but others may be set as well. X Version 11 Last change: libX11 1.3.5 5XKB FUNCTIONS XkbApplyCompatMapToKey(3x11)
XkbSI_Exactly (4) All of the bits that are on in
mods must be set, and no other bits may be set. In addition to the above bits, match may contain theXkbSI_LevelOneOnly bit, in which case the modifier match
criteria specified by mods and match applies only if sym is in level one of its group; otherwise, mods and match areignored and the symbol matches a condition where no modif-
iers are set.#define XkbSI_LevelOneOnly (0x80) /* use mods + match only if sym is level 1 */
If no matching symbol interpretation is found, the server uses a default interpretation where: sym = 0flags = XkbSI_AutoRepeat
match = XkbSI_AnyOfOrNone
mods = 0virtual_mod = XkbNoModifier
act = SA_NoAction
When a matching symbol interpretation is found in step 2a,the interpretation is applied to modify the Xkb map as fol-
lows. The act field specifies a single action to be bound to the symbol position; any key event that selects the symbol causes the action to be taken. Valid actions are defined in Key Actions.If the Xkb keyboard map for the key does not have its Expli-
citVModMap control set, the XkbSI_LevelOneOnly bit and sym-
bol position are examined. If the XkbSI_LevelOneOnly bit is
not set in match or the symbol is in position G1L1, thevirtual_mod field is examined. If virtual_mod is not
XkbNoModifier, virtual_mod specifies a single virtual modif-
ier to be added to the virtual modifier map for the key.virtual_mod is specified as an index in the range [0..15].
If the matching symbol is in position G1L1 of the key, two bits in the flags field potentially specify additional behavior modifications:#define XkbSI_AutoRepeat (1<<0) /* key repeats if sym is in position G1L1 */
#define XkbSI_LockingKey (1<<1) /* set KB_Lock behavior if sym is in psn G1L1 */
If the Xkb keyboard map for the key does not have its Expli-
citAutoRepeat control set, its auto repeat behavior is setbased on the value of the XkbSI_AutoRepeat bit. If the
XkbSI_AutoRepeat bit is set, the auto-repeat behavior of the
X Version 11 Last change: libX11 1.3.5 6XKB FUNCTIONS XkbApplyCompatMapToKey(3x11)
key is turned on; otherwise, it is turned off.If the Xkb keyboard map for the key does not have its Expli-
citBehavior control set, its locking behavior is set basedon the value of the XkbSI_LockingKey bit. If
XkbSI_LockingKey is set, the key behavior is set to KB_Lock;
otherwise, it is turned off.SEE ALSO
XkbKeyAction(3x11), XkbKeyActionEntry(3x11), XkbKeyActionsPtr(3x11), XkbKeyHasActions(3x11), XkbKeyNumActions(3x11)ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | x11/library/libx11 ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | See XInitThreads(3X11) |
|_____________________________|_____________________________|
X Version 11 Last change: libX11 1.3.5 7