From 16b53769eba7d5d8249a217aa29287d72b7713c2 Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 14 Sep 2011 14:23:18 +0200 Subject: libX11 git update 14 sep 2011 --- libX11/specs/XKB/ch07.xml | 446 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 446 insertions(+) create mode 100644 libX11/specs/XKB/ch07.xml (limited to 'libX11/specs/XKB/ch07.xml') diff --git a/libX11/specs/XKB/ch07.xml b/libX11/specs/XKB/ch07.xml new file mode 100644 index 000000000..cd1b7dbd0 --- /dev/null +++ b/libX11/specs/XKB/ch07.xml @@ -0,0 +1,446 @@ + +Virtual Modifiers + + +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 +, Xkb provides a set of sixteen named +virtual modifiers +. 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 Modifier Names and Masks + + +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 Chapter 18. + + + + + +Modifier Definitions + + +An Xkb + 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 sections 8.2.2, +10.8, and 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. + + + + + +Binding Virtual Modifiers to Real Modifiers + + +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. + + + + + +Virtual Modifier Key Mapping + + +Xkb maintains a +virtual modifier 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 +. + + + + + + + + +Bool +XkbVirtualModsToReal +( +xkb, virtual_mask, mask_rtrn +) + + + + +XkbDescPtr + xkb +; /* keyboard description for input device */ + + + + +unsigned int + virtual_mask +; /* virtual modifier mask to translate */ + + + + +unsigned int * +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. + + + +Inactive Modifier Sets + + +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. + + + + + + +Conventions + + +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 + + + + +Example + + +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) + + + -- cgit v1.2.3