1XkbApplyCompatMapToKey(3)        XKB FUNCTIONS       XkbApplyCompatMapToKey(3)
2
3
4

NAME

6       XkbApplyCompatMapToKey  - Apply the new compatibility mapping to an in‐
7       dividual key to get its semantics updated
8

SYNOPSIS

10       Bool XkbApplyCompatMapToKey (XkbDescPtr xkb, KeyCode key, XkbChangesPtr
11              changes);
12

ARGUMENTS

14       xkb    keyboard description to be updated
15
16       key    key to be updated
17
18       changes
19              notes changes to the Xkb keyboard description
20

DESCRIPTION

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
27       Core Keyboard Mapping to Xkb Keyboard Mapping Transformation
28
29       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
40       Explicit Components-Avoiding Automatic Remapping by the Server
41
42       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
46       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
52       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
57
58                      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
66
67       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
95       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
111       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
115       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
128       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
142                         G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3
143
144           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
154              G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3
155
156           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
163       1d. For each group on each changed key, assign a key  type  appropriate
164           for the symbols in the group.
165
166       1e. For each changed key, remove any empty or redundant groups.
167
168           At  this  point,  the groups and their associated symbols have been
169           assigned to the corresponding key definitions in the Xkb map.
170
171       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
176       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
180       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
184       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
188       Symbol Interpretations - the XkbSymInterpretRec Structure
189
190       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
195       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
199           Virtual modifier map
200           Auto repeat
201           Key behavior (may be set to XkbKB_Lock)
202           Key action
203
204       The XkbSymInterpretRec structure specifies a symbol interpretation:
205
206       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
215       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
221       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
224
225              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
245       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
251       #define XkbSI_LevelOneOnly  (0x80)  /* use mods + match only if sym is level 1 */
252
253       If  no  matching  symbol interpretation is found, the server uses a de‐
254       fault interpretation where:
255
256           sym =           0
257           flags =         XkbSI_AutoRepeat
258           match =         XkbSI_AnyOfOrNone
259           mods =          0
260           virtual_mod =   XkbNoModifier
261           act =           SA_NoAction
262
263       When a matching symbol interpretation is found in step 2a,  the  inter‐
264       pretation is applied to modify the Xkb map as follows.
265
266       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
270       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
278       If  the matching symbol is in position G1L1 of the key, two bits in the
279       flags field potentially specify additional behavior modifications:
280
281       #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
284       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
289       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

SEE ALSO

295       XkbKeyAction(3), XkbKeyActionEntry(3), XkbKeyActionsPtr(3),  XkbKeyHas‐
296       Actions(3), XkbKeyNumActions(3)
297
298
299
300X Version 11                     libX11 1.8.7        XkbApplyCompatMapToKey(3)
Impressum