1XkbApplyCompatMapToKey(3) XKB FUNCTIONS XkbApplyCompatMapToKey(3)
2
6 XkbApplyCompatMapToKey - Apply the new compatibility mapping to an in‐
7 dividual key to get its semantics updated
8
10 Bool XkbApplyCompatMapToKey (XkbDescPtr xkb, KeyCode key, XkbChangesPtr
11 changes);
12
14 - xkb keyboard description to be updated
15 - key key to be updated
17 - changes
19 notes changes to the Xkb keyboard description
20
22 XkbApplyCompatMapToKey essentially performs the operation described in
23 Core Keyboard Mapping to Xkb Keyboard Mapping Transformation to a spe‐
24 cific key. This updates the behavior, actions, repeat status, and vir‐
25 tual modifier bindings of the key.
26 Core Keyboard Mapping to Xkb Keyboard Mapping Transformation
28 When a core protocol keyboard mapping request is received by the
30 server, the server's core keyboard map is updated, and then the Xkb map
31 maintained by the server is updated. Because a client may have explic‐
32 itly configured some of the Xkb keyboard mapping in the server, this
33 automatic regeneration of the Xkb keyboard mapping from the core proto‐
34 col keyboard mapping should not modify any components of the Xkb key‐
35 board mapping that were explicitly set by a client. The client must set
36 explicit override controls to prevent this from happening (see Explicit
37 Components-Avoiding Automatic Remapping by the Server). The core-to-Xkb
38 mapping is done as follows:
39 Explicit Components-Avoiding Automatic Remapping by the Server
41 Whenever a client remaps the keyboard using core protocol requests, Xkb
43 examines the map to determine likely default values for the components
44 that cannot be specified using the core protocol.
45 This automatic remapping might replace definitions explicitly requested
47 by an application, so the Xkb keyboard description defines an explicit
48 components mask for each key. Any aspects of the automatic remapping
49 listed in the explicit components mask for a key are not changed by the
50 automatic keyboard mapping.
51 The explicit components masks are held in the explicit field of the
53 server map, which is an array indexed by keycode. Each entry in this
54 array is a mask that is a bitwise inclusive OR of the values shown in
55 Table 1.
56 Table 1 Explicit Component Masks
59 ───────────────────────────────────────────────────────────────
60 Bit in Explicit Mask Value Protects Against
61 ───────────────────────────────────────────────────────────────
62 ExplicitKeyType1 (1<<0) Automatic determination of the
63 key type associated with
64 Group1.
65 ExplicitKeyType2 (1<<1) Automatic determination of the
68 key type associated with
69 Group2.
70 ExplicitKeyType3 (1<<2) Automatic determination of the
71 key type associated with
72 Group3.
73 ExplicitKeyType4 (1<<3) Automatic determination of the
74 key type associated with
75 Group4.
76 ExplicitInterpret (1<<4) Application of any of the
77 fields of a symbol interpreta‐
78 tion to the key in question.
79 ExplicitAutoRepeat (1<<5) Automatic determination of
80 auto-repeat status for the
81 key, as specified in a symbol
82 interpretation.
83 ExplicitBehavior (1<<6) Automatic assignment of the
84 XkbKB_Lock behavior to the
85 key, if the XkbSI_LockingKey
86 flag is set in a symbol inter‐
87 pretation.
88 ExplicitVModMap (1<<7) Automatic determination of the
89 virtual modifier map for the
90 key based on the actions as‐
91 signed to the key and the sym‐
92 bol interpretations that match
93 the key.
94 1. Map the symbols from the keys in the core keyboard map to groups
96 and symbols on keys in the Xkb keyboard map. The core keyboard map‐
97 ping is of fixed width, so each key in the core mapping has the
98 same number of symbols associated with it. The Xkb mapping allows
99 a different number of symbols to be associated with each key; those
100 symbols may be divided into a different number of groups (1-4) for
101 each key. For each key, this process therefore involves partition‐
102 ing the fixed number of symbols from the core mapping into a set of
103 variable-length groups with a variable number of symbols in each
104 group. For example, if the core protocol map is of width five, the
105 partition for one key might result in one group with two symbols
106 and another with three symbols. A different key might result in two
107 groups with two symbols plus a third group with one symbol. The
108 core protocol map requires at least two symbols in each of the
109 first two groups.
110 1a. For each changed key, determine the number of groups represented in
112 the new core keyboard map. This results in a tentative group count
113 for each key in the Xkb map.
114 1b. For each changed key, determine the number of symbols in each of
116 the groups found in step 1a. There is one explicit override control
117 associated with each of the four possible groups for each Xkb key,
118 ExplicitKeyType1 through ExplicitKeyType4. If no explicit override
119 control is set for a group, the number of symbols used for that
120 group from the core map is two. If the explicit override control
121 is set for a group on the key, the number of symbols used for that
122 Xkb group from the core map is the width of the Xkb group with one
123 exception: because of the core protocol requirement for at least
124 two symbols in each of groups one and two, the number of symbols
125 used for groups one and two is the maximum of 2 or the width of the
126 Xkb group.
127 1c. For each changed key, assign the symbols in the core map to the ap‐
129 propriate group on the key. If the total number of symbols required
130 by the Xkb map for a particular key needs more symbols than the
131 core protocol map contains, the additional symbols are taken to be
132 NoSymbol keysyms appended to the end of the core set. If the core
133 map contains more symbols than are needed by the Xkb map, trailing
134 symbols in the core map are discarded. In the absence of an ex‐
135 plicit override for group one or two, symbols are assigned in order
136 by group; the first symbols in the core map are assigned to group
137 one, in order, followed by group two, and so on. For example, if
138 the core map contained eight symbols per key, and a particular Xkb
139 map contained 2 symbols for G1 and G2 and three for G3, the symbols
140 would be assigned as (G is group, L is shift level):
141 G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3
143 If an explicit override control is set for group one or two, the
145 symbols are taken from the core set in a somewhat different order.
146 The first four symbols from the core set are assigned to G1L1,
147 G1L2, G2L1, G2L2, respectively. If group one requires more symbols,
148 they are taken next, and then any additional symbols needed by
149 group two. Group three and four symbols are taken in complete se‐
150 quence after group two. For example, a key with four groups and
151 three symbols in each group would take symbols from the core set in
152 the following order:
153 G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3
155 As previously noted, the core protocol map requires at lease two
157 symbols in groups one and two. Because of this, if an explicit
158 override control for an Xkb key is set and group one and / or group
159 two is of width one, it is not possible to generate the symbols
160 taken from the core protocol set and assigned to position G1L2 and
161 / or G2L2.
162 1d. For each group on each changed key, assign a key type appropriate
164 for the symbols in the group.
165 1e. For each changed key, remove any empty or redundant groups.
167 At this point, the groups and their associated symbols have been
169 assigned to the corresponding key definitions in the Xkb map.
170 2. Apply symbol interpretations to modify key operation. This phase is
172 completely skipped if the ExplicitInterpret override control bit
173 is set in the explicit controls mask for the Xkb key (see Explicit
174 Components-Avoiding Automatic Remapping by the Server).
175 2a. For each symbol on each changed key, attempt to match the symbol
177 and modifiers from the Xkb map to a symbol interpretation describ‐
178 ing how to generate the symbol.
179 2b. When a match is found in step 2a, apply the symbol interpretation
181 to change the semantics associated with the symbol in the Xkb key
182 map. If no match is found, apply a default interpretation.
183 The symbol interpretations used in step 2 are configurable and may be
185 specified using XkbSymInterpretRec structures referenced by the sym_in‐
186 terpret field of an XkbCompatMapRec.
187 Symbol Interpretations - the XkbSymInterpretRec Structure
189 Symbol interpretations are used to guide the X server when it modifies
191 the Xkb keymap in step 2. An initial set of symbol interpretations is
192 loaded by the server when it starts. A client may add new ones using
193 XkbSetCompatMap.
194 Symbol interpretations result in key semantics being set. When a symbol
196 interpretation is applied, the following components of server key event
197 processing may be modified for the particular key involved:
198 Virtual modifier map
200 Auto repeat
201 Key behavior (may be set to XkbKB_Lock)
202 Key action
203 The XkbSymInterpretRec structure specifies a symbol interpretation:
205 typedef struct {
207 KeySym sym; /∗ keysym of interest or NULL */
208 unsigned char flags; /∗ XkbSI_AutoRepeat, XkbSI_LockingKey */
209 unsigned char match; /∗ specifies how mods is interpreted */
210 unsigned char mods; /∗ modifier bits, correspond to eight real modifiers */
211 unsigned char virtual_mod; /∗ 1 modifier to add to key virtual mod map */
212 XkbAnyAction act; /∗ action to bind to symbol position on key */
213 } XkbSymInterpretRec,*XkbSymInterpretPtr;
214 If sym is not NULL, it limits the symbol interpretation to keys on
216 which that particular keysym is selected by the modifiers matching the
217 criteria specified by mods and match. If sym is NULL, the interpreta‐
218 tion may be applied to any symbol selected on a key when the modifiers
219 match the criteria specified by mods and match.
220 match must be one of the values shown in Table 2 and specifies how the
222 real modifiers specified in mods are to be interpreted.
223 Table 2 Symbol Interpretation Match Criteria
226 ───────────────────────────────────────────────────────────
227 Match Criteria Value Effect
228 ───────────────────────────────────────────────────────────
229 XkbSI_NoneOf (0) None of the bits that are on
230 in mods can be set, but other
231 bits can be.
232 XkbSI_AnyOfOrNone (1) Zero or more of the bits that
233 are on in mods can be set, as
234 well as others.
235 XkbSI_AnyOf (2) One or more of the bits that
236 are on in mods can be set, as
237 well as any others.
238 XkbSI_AllOf (3) All of the bits that are on in
239 mods must be set, but others
240 may be set as well.
241 XkbSI_Exactly (4) All of the bits that are on in
242 mods must be set, and no other
243 bits may be set.
244 In addition to the above bits, match may contain the XkbSI_LevelOneOnly
246 bit, in which case the modifier match criteria specified by mods and
247 match applies only if sym is in level one of its group; otherwise, mods
248 and match are ignored and the symbol matches a condition where no modi‐
249 fiers are set.
250 #define XkbSI_LevelOneOnly (0x80) /∗ use mods + match only if sym is level 1 */
252 If no matching symbol interpretation is found, the server uses a de‐
254 fault interpretation where:
255 sym = 0
257 flags = XkbSI_AutoRepeat
258 match = XkbSI_AnyOfOrNone
259 mods = 0
260 virtual_mod = XkbNoModifier
261 act = SA_NoAction
262 When a matching symbol interpretation is found in step 2a, the inter‐
264 pretation is applied to modify the Xkb map as follows.
265 The act field specifies a single action to be bound to the symbol posi‐
267 tion; any key event that selects the symbol causes the action to be
268 taken. Valid actions are defined in Key Actions.
269 If the Xkb keyboard map for the key does not have its ExplicitVModMap
271 control set, the XkbSI_LevelOneOnly bit and symbol position are exam‐
272 ined. If the XkbSI_LevelOneOnly bit is not set in match or the symbol
273 is in position G1L1, the virtual_mod field is examined. If virtual_mod
274 is not XkbNoModifier, virtual_mod specifies a single virtual modifier
275 to be added to the virtual modifier map for the key. virtual_mod is
276 specified as an index in the range [0..15].
277 If the matching symbol is in position G1L1 of the key, two bits in the
279 flags field potentially specify additional behavior modifications:
280 #define XkbSI_AutoRepeat (1<<0) /∗ key repeats if sym is in position G1L1 */
282 #define XkbSI_LockingKey (1<<1) /∗ set KB_Lock behavior if sym is in psn G1L1 */
283 If the Xkb keyboard map for the key does not have its ExplicitAutoRe‐
285 peat control set, its auto repeat behavior is set based on the value of
286 the XkbSI_AutoRepeat bit. If the XkbSI_AutoRepeat bit is set, the auto-
287 repeat behavior of the key is turned on; otherwise, it is turned off.
288 If the Xkb keyboard map for the key does not have its ExplicitBehavior
290 control set, its locking behavior is set based on the value of the
291 XkbSI_LockingKey bit. If XkbSI_LockingKey is set, the key behavior is
292 set to KB_Lock; otherwise, it is turned off.
293
295 XkbKeyAction(3), XkbKeyActionEntry(3), XkbKeyActionsPtr(3), XkbKeyHas‐
296 Actions(3), XkbKeyNumActions(3)
297X Version 11 libX11 1.7.0 XkbApplyCompatMapToKey(3)