aboutsummaryrefslogtreecommitdiff
path: root/libX11/specs/XKB/ch07.xml
blob: cbb549ce8c24091954e70e30116a65bad7368a49 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id='Virtual_Modifiers'>
<title>Virtual Modifiers</title>

<para>
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
<keysym>Num_Lock</keysym>
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
<symbol>Mod1</symbol>
through
<symbol>Mod5</symbol>)
to keysyms such as
<keysym>Num_Lock</keysym>
and
<keysym>Mode_switch</keysym>.
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.
</para>


<para>
Xkb alleviates these problems by defining virtual modifiers. In addition to the
eight core modifiers, referred to as the
<firstterm>real modifiers</firstterm>,
<indexterm significance="preferred" zone="Virtual_Modifiers">
<primary>real modifiers</primary></indexterm>
<indexterm significance="preferred" zone="Virtual_Modifiers">
<primary>modifiers</primary><secondary>real</secondary></indexterm>
Xkb provides a set of sixteen named
<firstterm>virtual modifiers</firstterm>.
<indexterm significance="preferred" zone="Virtual_Modifiers">
<primary>virtual modifiers</primary></indexterm>
<indexterm significance="preferred" zone="Virtual_Modifiers">
<primary>modifiers</primary><secondary>virtual</secondary></indexterm>
Each virtual modifier can be bound to any set of the real modifiers
(
<symbol>Shift</symbol>,
<symbol>Lock</symbol>,
<symbol>Control</symbol>,
and
<symbol>Mod1</symbol>
&ndash;
<symbol>Mod5</symbol>).

</para>


<para>
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,
<keysym>Num_Lock</keysym>
might be bound to
<symbol>Mod2</symbol>
for one vendor and to
<symbol>Mod4</symbol>
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.
</para>

<sect1 id='Virtual_Modifier_Names_and_Masks'>
<title>Virtual Modifier Names and Masks</title>

<para>
Virtual modifiers are named by converting their string name to an X
<type>Atom</type>
and storing the Atom in the
<structfield>names.vmods</structfield>
array in an
<structname>XkbDescRec</structname>
structure (see <link linkend="The_XkbDescRec_Structure">section 6.1</link>). The position of a name Atom in the
<structfield>names.vmods</structfield>
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
<structfield>names.vmods</structfield>
is the i-th virtual modifier, represented by the mask (1&lt;&lt;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.
</para>


<para>
To set the name of a virtual modifier, use
<function>XkbSetNames</function>,
using
<symbol>XkbVirtualModNamesMask</symbol>
in
<parameter>which</parameter>
and the name in the
<parameter>xkb</parameter>
argument; to retrieve indicator names, use
<function>XkbGetNames</function>.
These functions are discussed in <xref linkend="Symbolic_Names" />.
</para>


</sect1>
<sect1 id='Modifier_Definitions'>
<title>Modifier Definitions</title>

<indexterm significance="preferred" zone="Modifier_Definitions">
<primary><structname>XkbModsRec</structname></primary></indexterm>

<para>
An Xkb
<firstterm>modifier definition</firstterm>
<indexterm significance="preferred" zone="grab_state">
<primary>modifier definition</primary></indexterm>
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
<link linkend="XkbIndicatorMapRec">section 8.2.2</link>,
<link linkend="The_XkbControlsRec_Structure">section 10.8</link>, and
<link linkend="Key_Types">section 15.2</link>.)
</para>

<para><programlisting>
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 */
} <structname>XkbModsRec</structname>, *XkbModsPtr;
</programlisting></para>

<para>
An Xkb modifier definition consists of a set of bit masks corresponding to the
eight real modifiers
(<structfield>real_mods</structfield>);
a similar set of bitmasks corresponding to the 16 named virtual modifiers
(<structfield>vmods</structfield>);
and an effective mask
(<structfield>mask</structfield>).
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.
<structfield>mask</structfield>
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
(<structfield>real_mods</structfield>)
<emphasis>plus</emphasis>
any real modifiers that are bound to the virtual modifiers specified in the
definition
(<structfield>vmods</structfield>).
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.
</para>


</sect1>
<sect1 id='Binding_Virtual_Modifiers_to_Real_Modifiers'>
<title>Binding Virtual Modifiers to Real Modifiers</title>

<para>
The binding of virtual modifiers to real modifiers is defined by the
<structfield>server.vmods</structfield>
array in an
<structname>XkbDescRec</structname>
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
<link linkend="figure16.2">Figure 16.2</link>.
</para>


</sect1>
<sect1 id='Virtual_Modifier_Key_Mapping'>
<title>Virtual Modifier Key Mapping</title>

<para>
Xkb maintains a
<firstterm>virtual modifier mapping</firstterm>,
<indexterm significance="preferred" zone="Virtual_Modifier_Key_Mapping">
<primary>virtual modifier mapping</primary></indexterm>
<indexterm significance="preferred" zone="Virtual_Modifier_Key_Mapping">
<primary>modifiers</primary><secondary>virtual mapping</secondary></indexterm>
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
<structfield>server.vmodmap</structfield>
array indicates which virtual modifiers are bound to each key; each entry is a
bitmask for the virtual modifier bits. The
<structfield>server.vmodmap</structfield>
array is indexed by keycode.
</para>


<para>
The
<structfield>vmodmap</structfield>
and
<structfield>vmods</structfield>
members of the server map are the <quote>master</quote> virtual modifier definitions. Xkb
automatically propagates any changes to these fields to all other fields that
use virtual modifier mappings (see <link linkend="Virtual_Modifier_Mapping">section 16.4</link>).
</para>


<para>
For example, if
<symbol>Mod3</symbol>
is bound to the
<keysym>Num_Lock</keysym>
key by the core protocol modifier mapping, and the
<emphasis>NumLock</emphasis>
virtual modifier is bound to they
<keysym>Num_Lock</keysym>
key by the virtual modifier mapping,
<symbol>Mod3</symbol>
is added to the set of modifiers associated with
<emphasis>NumLock</emphasis>.
</para>


<para>
The virtual modifier mapping is normally updated whenever actions are
automatically applied to symbols (see <link linkend="Virtual_Modifier_Mapping">section 16.4</link> for details), and few
applications should need to change the virtual modifier mapping explicitly.
</para>


<para>
Use
<function>XkbGetMap</function>
(see <link linkend="Getting_Map_Components_from_the_Server">section 14.2</link>) to get the virtual modifiers from the server or use
<function>XkbGetVirtualMods</function>
(see <link linkend="Obtaining_Virtual_Modifier_Bindings_from_the_Server">section 16.4.1</link>) 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
<function>XkbSetMap</function>
(see
<link linkend="Changing_Map_Components_in_the_Server">section 14.3</link>).
</para>


<para>
To determine the mapping of virtual modifiers to core X protocol modifiers, use
<function>XkbVirtualModsToReal</function>.
</para>

<indexterm significance="preferred" zone="XkbVirtualModsToReal"><primary><function>XkbVirtualModsToReal</function></primary></indexterm>
<funcsynopsis id="XkbVirtualModsToReal">
  <funcprototype>
    <funcdef>Bool <function>XkbVirtualModsToReal</function></funcdef>
<!-- (
<parameter>xkb, virtual_mask, mask_rtrn</parameter>
) -->

    <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
    <paramdef>unsigned int <parameter>virtual_mask</parameter></paramdef>
    <paramdef>unsigned int *<parameter>mask_rtrn</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>xkb</parameter>
    </term>
    <listitem>
      <para>
        keyboard description for input device
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>virtual_mask</parameter>
    </term>
    <listitem>
      <para>
        virtual modifier mask to translate
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>mask_rtrn</parameter>
    </term>
    <listitem>
      <para>
        backfilled with real modifiers
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
If the keyboard description defined by
<parameter>xkb</parameter>
includes bindings for virtual modifiers,
<function>XkbVirtualModsToReal</function>
uses those bindings to determine the set of real modifiers that correspond to
the set of virtual modifiers specified in
<parameter>virtual_mask</parameter>.
The
<parameter>virtual_mask</parameter>
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
<parameter>mask_rtrn</parameter>
is non-
<symbol>NULL</symbol>,
<function>XkbVirtualModsToReal</function>
backfills it with the resulting real modifier mask. If the keyboard
description in
<parameter>xkb</parameter>
does not include virtual modifier bindings,
<function>XkbVirtualModsToReal</function>
returns
<symbol>False</symbol>;
otherwise, it returns
<symbol>True</symbol>.
</para>

<note><para>It is possible for a local (client-side) keyboard description (the
<parameter>xkb</parameter>
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. </para></note>


<sect2 id='Inactive_Modifier_Sets'>
<title>Inactive Modifier Sets</title>

<para>
An unbound virtual modifier is one that is not bound to any real modifier
(
<structfield>server</structfield>-&gt;<structfield>vmods</structfield>
[virtual_modifier_index] is zero).
</para>


<para>
Some Xkb operations ignore modifier definitions in which the virtual modifiers
are unbound. Consider this example:

<literallayout>        if (state matches {Shift}) Do OneThing;
        if (state matches {Shift+NumLock}) Do Another;
</literallayout>
</para>

<para>
If the
<emphasis>NumLock</emphasis>
virtual modifier is not bound to any real modifiers, the effective masks for
these two cases are identical (that is, contain only
<symbol>Shift</symbol>).
When it is essential to distinguish between
<emphasis>OneThing</emphasis>
and Another, Xkb considers only those modifier definitions for which all
virtual modifiers are bound.
</para>


</sect2>
</sect1>
<sect1 id='Conventions'>
<title>Conventions</title>

<indexterm significance="preferred" zone="Conventions">
<primary>modifiers</primary><secondary>names</secondary></indexterm>

<para>
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:

  <simplelist type='vert' columns='1'>
    <member><emphasis>NumLock</emphasis></member>
    <member><emphasis>ScrollLock</emphasis></member>
    <member><emphasis>Alt</emphasis></member>
    <member><emphasis>Meta</emphasis></member>
    <member><emphasis>AltGr</emphasis></member>
    <member><emphasis>LevelThree</emphasis></member>
  </simplelist>
</para>

</sect1>
<sect1 id='Example'>
<title>Example</title>

<para>
If the second (0-relative) entry in
<structfield>names.vmods</structfield>
contains the Atom for "NumLock", then 0x4 (1&lt;&lt;2) is the virtual modifier
bit for the
<emphasis>NumLock</emphasis>
virtual modifier. If
<structfield>server.vmods</structfield>
[2] contains
<symbol>Mod3Mask</symbol>,
then the
<emphasis>NumLock</emphasis>
virtual modifier is bound to the
<symbol>Mod3</symbol>
real modifier.
</para>


<para>
A virtual modifier definition for this example would have:
</para>

<literallayout class='monospaced'>
     real_mods = 0
     vmods = 0x4 (NumLock named virtual modifier)
     mask = 0x20 (Mod3Mask)
</literallayout>

<para>
Continuing the example, if the keyboard has a
<keysym>Num_Lock</keysym>
keysym bound to the key with keycode 14, and the
<emphasis>NumLock</emphasis>
virtual modifier is bound to this key,
<structfield>server.vmodmap[14]</structfield>
contains 0x4.
</para>


<para>
Finally, if the keyboard also used the real
<symbol>Mod1</symbol>
modifier for numeric lock operations, the modifier definition below would
represent the situation where either the key bound to
<symbol>Mod1</symbol>
or the
<emphasis>NumLock</emphasis>
virtual modifier could be used for this purpose:
</para>

<literallayout class='monospaced'>
     real_mods = 0x8 (Mod1Mask)
     vmods = 0x4 (NumLock named virtual modifier)
     mask = 0x28 (Mod1Mask | Mod3Mask)
</literallayout>
</sect1>
</chapter>