summaryrefslogtreecommitdiff
path: root/specs/ch13.xml
blob: 9efa7b219dfc0e2d8a99de5d91e7a787187e65ec (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
<chapter id='the_server_database_of_keyboard_components'>
<title>The Server Database of Keyboard Components</title>

<para>
The X server maintains a database of keyboard components and common keyboard
mappings. This database contains five kinds of components; when combined, these
five components provide a complete description of a keyboard and its behavior.
</para>


<para>
The X Keyboard Extension provides requests to list the contents of this
database, to assemble and complete keyboard descriptions by merging the current
keyboard description with the contents of this database, or to replace the
current keyboard description with a complete keyboard description assembled as
described below.
</para>

<sect1 id='component_names'>
<title>Component Names</title>

<para>
Component and keymap names have the form "<emphasis>
class</emphasis>
(<emphasis>
member</emphasis>
)" where <emphasis>
class</emphasis>
 describes a subset of the available components for a particular type and the
optional <emphasis>
member</emphasis>
 identifies a specific component from that subset. For example, the name
"atlantis(acme)" might specify the symbols used for the atlantis national
keyboard layout by the vendor "acme." Each class has an optional <emphasis>
default</emphasis>
 member — references which specify a class but not a member refer to the
default member of the class, if one exists.
</para>


<para>
The <emphasis>
class</emphasis>
 and <emphasis>
member</emphasis>
 names are both specified using characters from the Latin-1 character set. XKB
implementations must accept all alphanumeric characters, minus (‘-’) and
underscore (‘_’) in class or member names, and must not accept parentheses,
plus, vertical bar, percent sign, asterisk, question mark or white space. The
use of other characters is implementation-dependent.
</para>


</sect1>
<sect1 id='partial_components_and_combining_multiple_components'>
<title>Partial Components and Combining Multiple Components</title>

<para>
Some of the elements in the server database contain describe only a piece of
the corresponding keyboard component. These <emphasis>
partial</emphasis>
 components should be combined with other components of the same type to be
useful.
</para>


<para>
For example, a partial symbols map might describe the differences between a
common ASCII keyboard and some national layout. Such a partial map is not
useful on its own because it does not include those symbols that are the same
on both the ASCII and national layouts (such as function keys). On the other
hand, this partial map can configure <emphasis>
any</emphasis>
 ASCII keyboard to use a national layout.
</para>


<para>
Two components can be combined in two ways:
</para>

<itemizedlist>
<listitem>
  <para>If the second component <emphasis>
overrides</emphasis>
 the first, any definitions that are present in both components are taken from
the second.
  </para>
</listitem>
<listitem>
  <para>If the second component <emphasis>
augments</emphasis>
 the first, any definitions that are present in both components are taken from
the first.
  </para>
</listitem>
</itemizedlist>

<para>
Applications can use a <emphasis>
component expression</emphasis>
 to combine multiple components of some time into a complete description of
some aspect of the keyboard. A component expression is a string which lists the
components to be combined separated by operators which specify the rules for
combining them. A complete description is assembled from the listed components,
left to right, as follows:
</para>

<itemizedlist>
<listitem>
  <para>If the new elements are being merged with an existing map, the special
component name ‘%’ refers to the unmodified value of the map.
  </para>
</listitem>
<listitem>
  <para>The ‘+’ operator specifies that the next specified component should
override the current assembled definition.
  </para>
</listitem>
<listitem>
  <para>The ‘|’ operator specifies that the next specified component should
augment the currently assembled definition.
  </para>
</listitem>
<listitem>
  <para>If the new elements are being merged with an existing map and the
component expression begins with an operator, a leading ‘%’ is implied.
  </para>
</listitem>
<listitem>
  <para>If any unknown or illegal characters appear anywhere in the string, the
entire expression is invalid and is ignored.
  </para>
</listitem>
</itemizedlist>

<para>
For example, the component expression "+de" specifies that the default element
of the "de" map should be applied to the current keyboard mapping, overriding
any existing definitions.
</para>


<para>
A slightly more involved example: the expression
"acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping for the
ASCII keyboard supplied by the "acme" vendor. The new definition begins with
the symbols for the default ASCII keyboard for Acme, overrides them with any
keys that are defined for the default German keyboard layout and then applies
the definitions from the iso9995-3 to any undefined keys or groups of keys
(part three of the iso9995 standard defines a common set of bindings for the
secondary group, but allows national layouts to override those definitions
where necessary).
</para>


</sect1>
<sect1 id='component_hints'>
<title>Component Hints</title>

<para>
Each component has a set of flags that provide some additional hints about that
component. XKB provides these hints for clients that present the keyboard
database to users and specifies their interpretation only loosely. Clients can
use these hints to constrain the list of components or to control the way that
components are presented to the user.
</para>


<para>
Hints for a component are reported with its name. The least significant byte of
the hints field has the same meaning for all five types of keyboard components,
and can contain any combination of the following values:
</para>

<informaltable frame='none'>
<tgroup cols='2'>
<colspec align="left" colsep="0"/>
<colspec align="left" colsep="0"/>
<thead>
  <row rowsep='1'>
    <entry>Flag</entry>
    <entry>Meaning</entry>
  </row>
</thead>
<tbody>
  <row rowsep='0'>
    <entry><emphasis>
LC_Hidden</emphasis>
</entry>
    <entry>Indicates a component that should not normally be presented to the
user.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
LC_Default</emphasis>
</entry>
    <entry>Indicates a component that is the default member of its
class.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
LC_Partial</emphasis>
</entry>
    <entry>Indicates a partial component.</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
The interpretation of the most significant byte of the hints field is dependent
on the type of component. The hints defined for each kind of component are
listed in the section below that describes that kind of component.
</para>


</sect1>
<sect1 id='keyboard_components'>
<title>Keyboard Components</title>

<para>
The five types of components stored in the server database of keyboard
components correspond to the <emphasis>
symbols</emphasis>
, <emphasis>
geometry</emphasis>
, <emphasis>
keycodes</emphasis>
, <emphasis>
compat</emphasis>
 and <emphasis>
types</emphasis>
 symbolic names associated with a keyboard.
</para>

</sect1>
<sect1 id='the_keycodes_component'>
<title>The Keycodes Component</title>

<para>
The <emphasis>
keycodes</emphasis>
 component of a keyboard mapping specifies the range and interpretation of the
raw keycodes reported by the device. It sets the <emphasis>
keycodes</emphasis>
 symbolic name, the minimum and maximum legal keycodes for the keyboard, and
the symbolic name for each key. The keycodes component might also contain
aliases for some keys, symbolic names for some indicators, and a description of
which indicators are physically present.
</para>


<para>
The special keycodes component named "computed" indicates that XKB should
assign unused keycodes to any unknown keys referenced by name by any of the
other components. The computed keycodes component is useful primarily when
browsing keymaps because it makes it possible to use the symbols and geometry
components without having to find a set of keycodes that includes keycode
definitions for all of the keys listed in the two components.
</para>


<para>
XKB defines no hints that are specific to the keycodes component.
</para>


<sect2 id='the_types_component'>
<title>The Types Component</title>

<para>
The <emphasis>
types</emphasis>
 component of a keyboard mapping specifies the key types that can be associated
with the various keyboard keys. It affects the <emphasis>
types</emphasis>
 symbolic name and the list of types associated with the keyboard (see
<link linkend='key_types'>Key Types</link>). The types component
of a keyboard mapping can also optionally contain real modifier bindings and
symbolic names for one or more virtual modifiers.
</para>


<para>
The special types component named "canonical" always contains the types and
definitions listed in <link linkend="canonical_key_types">Canonical Key Types</link> of this document.
</para>


<para>
XKB defines no hints that are specific to the types component.
</para>


</sect2>
<sect2 id='the_compatibility_map_component'>
<title>The Compatibility Map Component</title>

<para>
The <emphasis>
compatibility map</emphasis>
 component of a keyboard mapping primarily specifies the rules used to assign
actions to keysyms. It affects the <emphasis>
compat</emphasis>
 symbolic name, the symbol compatibility map and the group compatibility map.
The compat component might also specify maps for some indicators and the real
modifier bindings and symbolic names of some virtual modifiers.
</para>


<para>
XKB defines no hints that are specific to the compatibility map component.
</para>


</sect2>
<sect2 id='the_symbols_component'>
<title>The Symbols Component</title>

<para>
The <emphasis>
symbols</emphasis>
 component of a keyboard mapping specifies primarily the symbols bound to each
keyboard key. It affects the <emphasis>
symbols</emphasis>
 symbolic name, a key symbol mapping for each key, they keyboard modifier
mapping, and the symbolic names for the keyboard symbol groups. Optionally, the
<emphasis>
symbols</emphasis>
 component can contain explicit actions and behaviors for some keys, or the
real modifier bindings and symbolic names for some virtual modifiers.
</para>


<para>
XKB defines the following additional hints for the symbols component:
</para>

<informaltable frame='none'>
<tgroup cols='2'>
<colspec align="left" colsep="0"/>
<colspec align="left" colsep="0"/>
<thead>
  <row rowsep='1'>
    <entry>Flag</entry>
    <entry>Meaning</entry>
  </row>
</thead>
<tbody>
  <row rowsep='0'>
    <entry><emphasis>
LC_AlphanumericKeys</emphasis>
</entry>
    <entry>Indicates a symbol component that contains bindings primarily for an
alphanumeric section of the keyboard.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
LC_ModifierKeys</emphasis>
</entry>
    <entry>Indicates a symbol component that contains bindings primarily for
modifier keys.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
LC_KeypadKeys</emphasis>
</entry>
    <entry>Indicates a symbol component that contains bindings primarily for
numeric keypad keys.</entry>
  </row>
  <row rowsep='0'>
    <entry>LC_FunctionKeys</entry>
    <entry>Indicates a symbol component that contains bindings primarily for
function keys.</entry>
  </row>
  <row rowsep='0'>
    <entry>LC_AlternateGroup</entry>
    <entry>Indicates a symbol component that contains bindings for an alternate
keyboard group.</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
These hints only apply to partial symbols components; full symbols components
are assumed to specify all of the pieces listed above.
</para>

<note><para>The alphanumeric, modifier, keypad or function keys hints should
describe the primary intent of the component designer and should not simply an
exhaustive list of the kinds of keys that are affected. For example, national
keyboard layouts affect primarily alphanumeric keys, but many affect a few
modifier keys too; such mappings should set only <emphasis>
LC_AlphanumericKeys</emphasis>
 hint. In general, symbol components should set only one of those four flags
(though <emphasis>
LC_AlternateGroup</emphasis>
 may be combined with any of the other flags).</para></note>

</sect2>
<sect2 id='the_geometry_component'>
<title>The Geometry Component</title>

<para>
The <emphasis>
geometry</emphasis>
 component of a keyboard mapping specifies primarily the geometry of the
keyboard. It contains the geometry symbolic name and the keyboard geometry
description. The geometry component might also contain aliases for some keys or
symbolic names for some indicators and might affect the set of indicators that
are physically present. Key aliases defined in the geometry component of a
keyboard mapping override those defined in the keycodes component.
</para>


<para>
XKB defines no hints that are specific to the geometry component.
</para>


</sect2>
</sect1>
<sect1 id='complete_keymaps'>
<title>Complete Keymaps</title>

<para>
The X server also reports a set of fully specified keymaps. The keymaps
specified in this list are usually assembled from the components stored in the
rest of the database and typically represent the most commonly used keymaps for
a particular system.
</para>


<para>
XKB defines no hints that are specific to complete keymaps.
</para>
</sect1>
</chapter>