aboutsummaryrefslogtreecommitdiff
path: root/libX11/specs/XKB/ch11.xml
blob: 52f089775d4a52bf13e0571a453a0f47f01bfd09 (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
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
<chapter id='X_Library_Controls'>
<title>X Library Controls</title>

<para>
The Xkb extension is composed of two parts: a server extension, and a
client-side X library extension. Chapter 10 discusses functions used to modify
controls affecting the behavior of the server portion of the Xkb extension.
This chapter discusses functions used to modify controls that affect only the
behavior of the client portion of the extension; these controls are known as
Library Controls.
</para>


<para>
All of the Library Controls are boolean flags that may be enabled and disabled.
The controls can be divided into several categories:
</para>

<itemizedlist>
<listitem>
  <para>
Controls affecting general string lookups
  </para>
</listitem>
<listitem>
  <para>
Controls affecting compose processing
  </para>
</listitem>
<listitem>
  <para>
Controls affecting event delivery
  </para>
</listitem>
</itemizedlist>

<para>
There are two types of string lookups performed by <emphasis>
XLookupString</emphasis>
. The first type involves translating a single keycode into a string; the
controls in the first category affect this type of lookup. The second type
involves translating a series of keysyms into a string; the controls in the
second category affect this type of lookup.
</para>


<para>
An Xkb implementation is required to support the programming interface for all
of the controls. However, an implementation may choose not to support the
semantics associated with the controls that deal with compose processing. In
this case, a program that accesses these controls should still function
normally; however, the feedback that would normally occur with the controls
enabled may be missing.
</para>

<sect1 id='Controls_Affecting_Keycode_to_String_Translation'>
<title>Controls Affecting Keycode-to-String Translation</title>

<para>
The first type of string lookups, which are here called <emphasis>
simple string lookups</emphasis>
, involves translating a single keycode into a string. Because these simple
lookups involve only a single keycode, all of the information needed to do the
translation is contained in the keyboard state in a single event. The controls
affecting simple string lookups are:
</para>

<para><programlisting>
     <emphasis>ForceLatin1Lookup</emphasis>
     <emphasis>ConsumeLookupMods</emphasis>
     <emphasis>LevelOneUsesShiftAndLock</emphasis>
</programlisting></para>

<sect2 id='ForceLatin1Lookup'>
<title>ForceLatin1Lookup</title>

<para>
If the <emphasis>
ForceLatin1Lookup</emphasis>
 control is enabled, <emphasis>
XLookupString</emphasis>
 only returns strings using the Latin1 character set. If <emphasis>
ForceLatin1Lookup</emphasis>
 is not enabled, <emphasis>
XLookupString</emphasis>
 can return characters that are not in the Latin1 set. By default, this control
is disabled, allowing characters outside of the Latin1 set to be returned.
</para>


</sect2>
<sect2 id='ConsumeLookupMods'>
<title>ConsumeLookupMods</title>

<para>
Simple string lookups in <emphasis>
XLookupString</emphasis>
 involve two different translation phases. The first phase translates raw
device keycodes to individual keysyms. The second phase attempts to map the
resulting keysym into a string of one or more characters. In the first phase,
some of the modifiers are normally used to determine the appropriate shift
level for a key.
</para>


<para>
The <emphasis>
ConsumeLookupMods</emphasis>
 control determines whether or not <emphasis>
XLookupString</emphasis>
 <emphasis>
consumes</emphasis>
 the modifiers it uses during the first phase of processing (mapping a keycode
to a keysym). When a modifier is consumed, it is effectively removed from the
working copy of the keyboard state information <emphasis>
XLookupString</emphasis>
 is using and appears to be unset for the remainder of the processing.
</para>


<para>
If the <emphasis>
ConsumeLookupMods</emphasis>
 control is enabled, <emphasis>
XLookupString</emphasis>
 does not use the modifiers used to translate the keycode of the event to a
keysym when it is determining the string associated with a keysym. For example,
assume the keymap for the ‘A’ key only contains the shift modifier and the
<emphasis>
ConsumeLookupMods</emphasis>
 control is enabled. If a user presses the <emphasis>
Shift</emphasis>
 key and the <emphasis>
A</emphasis>
 key while the <emphasis>
Num_Lock</emphasis>
 key is locked, <emphasis>
XLookupString</emphasis>
 uses the <emphasis>
Shift</emphasis>
 modifier when mapping the keycode for the ‘a’ key to the keysym for
‘A’; subsequently, it only uses the <emphasis>
NumLock</emphasis>
 modifier when determining the string associated with the keysym ‘A’.
</para>


<para>
If the <emphasis>
ConsumeLookupMods</emphasis>
 control is not enabled, <emphasis>
XLookupString</emphasis>
 uses all of the event modifiers to determine the string associated with a
keysym. This behavior mirrors the behavior of <emphasis>
XLookupString</emphasis>
 in the core implementation.
</para>


<para>
The <emphasis>
ConsumeLookupMods</emphasis>
 control is unset by default. For more information on modifier consumption,
refer to Chapter 12.
</para>


</sect2>
<sect2 id='AlwaysConsumeShiftAndLock'>
<title>AlwaysConsumeShiftAndLock</title>

<para>
The <emphasis>
AlwaysConsumeShiftAndLock</emphasis>
 control, if enabled, forces <emphasis>
XLookupString</emphasis>
 to consume the <emphasis>
Shift</emphasis>
 and <emphasis>
Lock</emphasis>
 modifiers when processing all keys, even if the definition for the key type
does not specify these modifiers. The <emphasis>
AlwaysConsumeShiftAndLock</emphasis>
 control is unset by default. See section 15.2 for a discussion of key types.
</para>


</sect2>
</sect1>
<sect1 id='Controls_Affecting_Compose_Processing'>
<title>Controls Affecting Compose Processing</title>

<para>
The second type of string lookup performed by <emphasis>
XLookupString</emphasis>
 involves translating a series of keysyms into a string. Because these lookups
can involve more than one key event, they require <emphasis>
XLookupString</emphasis>
 to retain some state information between successive calls. The process of
mapping a series of keysyms to a string is known as <emphasis>
compose processing</emphasis>
. The controls affecting compose processing are:
</para>

<para><programlisting>
<emphasis>ConsumeKeysOnComposeFail</emphasis>
<emphasis>ComposeLED</emphasis>
<emphasis>BeepOnComposeFail</emphasis>
</programlisting></para>

<para>
Because different vendors have historically used different algorithms to
implement compose processing, and these algorithms may be incompatible with the
semantics required by the Xkb compose processing controls, implementation of
the compose processing controls is optional in an Xkb implementation.
</para>


<sect2 id='ConsumeKeysOnComposeFail'>
<title>ConsumeKeysOnComposeFail</title>

<para>
Some compose processing algorithms signal the start of a compose sequence by a
key event meaning "start compose".
<footnote><para>
Another possibility is to have the compose processing simply be the result of a finite state acceptor; a compose sequence would never fail for a properly written finite state acceptor.
</para></footnote>
The subsequent key events should normally result in a valid composition yielding a
valid translation to a string. If the subsequent key events do not have a valid
translation, some decision must be made about what to do with the key events
that were processed while attempting the compose. The <emphasis>
ConsumeKeysOnComposeFail</emphasis>
 control allows a client to specify what happens with the key events <emphasis>
XLookupString</emphasis>
 has been considering when it reaches a dead end in a compose sequence.
</para>


<para>
If the <emphasis>
ConsumeKeysOnComposeFail</emphasis>
 control is set, all keys associated with a failed compose sequence should be
consumed (discarded). If the <emphasis>
ConsumeKeysOnComposeFail</emphasis>
 control is not set, the key events associated with a failed compose sequence
should be processed as a normal sequence of key events.
</para>


<para>
The <emphasis>
ConsumeKeysOnComposeFail</emphasis>
 control is disabled by default.
</para>


</sect2>
<sect2 id='ComposeLED'>
<title>ComposeLED</title>

<para>
The <emphasis>
ComposeLED</emphasis>
 control allows a client to specify whether or not an indicator should be set
and cleared to provide feedback when compose processing is in progress. The
control does not specify which indicator should be used; the mapping for this
is up to the individual implementation. If the <emphasis>
ComposeLED</emphasis>
 control is enabled, it specifies that an indicator should be set when a
compose sequence is in progress and cleared when one is not in progress. The
<emphasis>
ComposeLED</emphasis>
 control is disabled by default.
</para>


<para>
While the Xkb extension does not specify the type of type of indicator to be
used when the <emphasis>
ComposeLED</emphasis>
 control is implemented, a consistent convention between implementations is to
everyone’s benefit. If a named indicator is used for this purpose, the
recommended name is "<emphasis>
Compose</emphasis>
". Note that some implementations may use an unnamed, custom hardware LED for
this purpose.
</para>


</sect2>
<sect2 id='BeepOnComposeFail'>
<title>BeepOnComposeFail</title>

<para>
The <emphasis>
BeepOnComposeFail</emphasis>
 control allows a client to specify whether or not a bell should be activated
to provide feedback when a compose sequence fails. The control does not specify
the type of bell that should be used; the mapping for this is up to the
individual implementation. If the <emphasis>
BeepOnComposeFail</emphasis>
 control is enabled, it specifies that a bell should be activated when a
compose sequence fails. The <emphasis>
BeepOnComposeFail</emphasis>
 control is disabled by default. If implemented, the bell should be activated
using <emphasis>
XkbBell</emphasis>
 or <emphasis>
XkbDeviceBell</emphasis>
.
</para>


<para>
While the Xkb extension does not specify the type of bell to be used when the
<emphasis>
BeepOnComposeFail</emphasis>
 control is implemented, a consistent convention between implementations is to
everyone’s benefit. If a named bell is used for this purpose, the recommended
name is "<emphasis>
ComposeFail</emphasis>
".
</para>


</sect2>
</sect1>
<sect1 id='Controls_Effecting_Event_Delivery'>
<title>Controls Effecting Event Delivery</title>

<sect2 id='IgnoreNewKeyboards'>
<title>IgnoreNewKeyboards</title>

<para>
When Xkb is initialized, it implicitly forces requests for <emphasis>
NewKeyboardNotify</emphasis>
 events. These events may be used by the Xkb library extension internally; they
are normally translated into core protocol <emphasis>
MappingNotify</emphasis>
 events before being passed to the client. While delivering the event to the
client is appropriate in most cases, it is not appropriate for some clients
that maintain per-key data structures. This is because once the server has sent
a <emphasis>
NewKeyboardNotify</emphasis>
 event, it is free to send the client events for all keys in the new range and
that range may be outside of the per-key data structures the client is
maintaining.
</para>


<para>
The <emphasis>
IgnoreNewKeyboards</emphasis>
 control, if enabled, prevents Xkb from mapping <emphasis>
NewKeyboardNotify</emphasis>
 events to core <emphasis>
MappingNotify</emphasis>
 events and passing them to the client. The control is initially disabled.
</para>


</sect2>
</sect1>
<sect1 id='Manipulating_the_Library_Controls'>
<title>Manipulating the Library Controls</title>

<para>
The Library Controls are manipulated using functions that deal with bitmasks to
indicate which controls to manipulate. The controls are identified by the masks
defined in Table 11.1. <!-- xref -->
</para>

<table frame='topbot'>
<title>Library Control Masks</title>
<?dbfo keep-together="always" ?>
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<colspec colname='c2' colwidth='1.0*'/>
<thead>
<row rowsep='1'>
  <entry>Library Control Mask</entry>
  <entry>Value</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>XkbLC_ForceLatin1Lookup</entry>
    <entry>(1 &lt;&lt; 0)</entry>
  </row>
  <row>
    <entry>XkbLC_ConsumeLookupMods</entry>
    <entry>(1 &lt;&lt; 1)</entry>
  </row>
  <row>
    <entry>XkbLC_AlwaysConsumeShiftAndLock</entry>
    <entry>(1 &lt;&lt; 2)</entry>
  </row>
  <row>
    <entry>XkbLC_IgnoreNewKeyboards</entry>
    <entry>(1 &lt;&lt; 3)</entry>
  </row>
  <row>
    <entry>XkbLC_ConsumeKeysOnComposeFail</entry>
    <entry>(1 &lt;&lt; 29)</entry>
  </row>
  <row>
    <entry>XkbLC_ComposeLED</entry>
    <entry>(1 &lt;&lt; 30)</entry>
  </row>
  <row>
    <entry>XkbLC_BeepOnComposeFail</entry>
    <entry>(1 &lt;&lt; 31)</entry>
  </row>
  <row>
    <entry>XkbLC_AllControls</entry>
    <entry>(0xc0000007)</entry>
  </row>
</tbody>
</tgroup>
</table>

<sect2 id='Determining_Which_Library_Controls_are_Implemented'>
<title>Determining Which Library Controls are Implemented</title>

<para>
To determine which Library Controls are actually
implemented, use <emphasis>XkbXlibControlsImplemented</emphasis>.
</para>

<informaltable frame='none'>
<?dbfo keep-together="always" ?>
<tgroup cols='1' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<tbody>
  <row>
    <entry role='functiondecl'>
unsigned int <emphasis>
XkbXlibControlsImplemented</emphasis>
(<emphasis>
display</emphasis>
)
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
Display *<emphasis>
            display</emphasis>
;                  /* connection to X server */
    </entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
<emphasis>
XkbXlibControlsImplemented</emphasis>
 returns a bitmask indicating the controls actually implemented in the Xkb
library and is composed of an inclusive OR of bits from Table 11.1.
</para>


</sect2>
<sect2 id='Determining_the_State_of_the_Library_Controls'>
<title>Determining the State of the Library Controls</title>

<para>
To determine the current state of the Library Controls, use <emphasis>
XkbGetXlibControls</emphasis>
.
</para>

<informaltable frame='none'>
<?dbfo keep-together="always" ?>
<tgroup cols='1' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<tbody>
  <row>
    <entry role='functiondecl'>
unsigned int <emphasis>
XkbGetXlibControls</emphasis>
(<emphasis>
display</emphasis>
)
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
Display *<emphasis>
            display</emphasis>
;                  /* connection to X server */
    </entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
<emphasis>
XkbGetXlibControls</emphasis>
 returns the current state of the Library Controls as a bit mask that is an
inclusive OR of the control masks from Table 11.1 for the controls that are
enabled. For the optional compose processing controls, the fact that a control
is enabled does not imply that it is actually implemented.
</para>

</sect2>
<sect2 id='Changing_the_State_of_the_Library_Controls'>
<title>Changing the State of the Library Controls</title>

<para>
To change the state of the Library Controls, use
<emphasis>XkbSetXlibControls</emphasis>.
</para>

<informaltable frame='none'>
<?dbfo keep-together="always" ?>
<tgroup cols='1' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<tbody>
  <row>
    <entry role='functiondecl'>
Bool <emphasis>
XkbSetXlibControls</emphasis>
(<emphasis>
display, bits_to_change, values_for_bits</emphasis>
)
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
Display *<emphasis>
            display</emphasis>
;                  /* connection to X server */
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
unsigned long            <emphasis>
bits_to_change</emphasis>
;                  /* selects controls to be modified */
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
unsigned long            <emphasis>
values_for_bits</emphasis>
;                  /* turns selected controls on (1) or off (0) */
    </entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
<emphasis>
XkbSetXlibControls</emphasis>
 modifies the state of the controls selected by <emphasis>
bits_to_change</emphasis>
; only the controls selected by <emphasis>
bits_to_change</emphasis>
 are modified. If the bit corresponding to a control is on in <emphasis>
bits_to_change</emphasis>
 and also on in values_for_bits, the control is enabled. If the bit
corresponding to a control is on in <emphasis>
bits_to_change</emphasis>
 but off in <emphasis>
values_for_bits</emphasis>
, the control is disabled. <emphasis>
bits_to_change</emphasis>
 should be an inclusive OR of bits from Table 11.1.
</para>

</sect2>
</sect1>
</chapter>