aboutsummaryrefslogtreecommitdiff
path: root/libX11/specs/XKB/ch19.xml
blob: faa62a2784ea23c873aba3b0bbe2aca1f6fd33af (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
<?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='Replacing_a_Keyboard_On_the_Fly'>
<title>Replacing a Keyboard <quote>On the Fly</quote></title>

<para>
Some operating system and X server implementations allow
<quote>hot plugging</quote> of
input devices. When using these implementations, input devices can be unplugged
and new ones plugged in without restarting the software that is using those
devices. There is no provision in the standard X server for notification of
client programs if input devices are unplugged and/or new ones plugged in. In
the case of the X keyboard, this could result in the X server having a keymap
that does not match the new keyboard.
</para>


<para>
If the X server implementation supports the X input device extension, a client
program may also change the X keyboard programmatically. The
XChangeKeyboardDevice input extension request allows a client to designate an
input extension keyboard device as the X keyboard, in which case the old X
keyboard device becomes inaccessible except via the input device extension. In
this case, core protocol
<symbol>MappingNotify</symbol>
and input extension
<symbol>XChangeDeviceNotify</symbol>
events are generated to notify all clients that a new keyboard with a new
keymap has been designated.
</para>


<para>
When a client opens a connection to the X server, the server reports the
minimum and maximum keycodes. The server keeps track of the minimum and maximum
keycodes last reported to each client. When delivering events to a particular
client, the server filters out any events that fall outside of the valid range
for the client.
</para>


<para>
Xkb provides an
<symbol>XkbNewKeyboardNotify</symbol>
event that reports a change in keyboard geometry and/or the range of supported
keycodes. The server can generate an
<symbol>XkbNewKeyboardNotify</symbol>
event when it detects a new keyboard or in response to an
<function>XkbGetKeyboardByName</function>
request that loads a new keyboard description. Selecting for
<symbol>XkbNewKeyboardNotify</symbol>
events allows Xkb-aware clients to be notified whenever a keyboard change
occurs that may affect the keymap.
</para>


<para>
When a client requests
<symbol>XkbNewKeyboardNotify</symbol>
events, the server compares the range of keycodes for the current keyboard to
the range of keycodes that are valid for the client. If they are not the same,
the server immediately sends the client an
<symbol>XkbNewKeyboardNotify</symbol>
event. Even if the <quote>new</quote> keyboard is not new to the server,
it is new to this particular client.
</para>


<para>
When the server sends an
<symbol>XkbNewKeyboardNotify</symbol>
event to a client to inform it of a new keycode range, it resets the stored
range of legal keycodes for the client to the keycode range reported in the
event; it does not reset this range for the client if it does not sent an
<symbol>XkbNewKeyboardNotify</symbol>
event to a client. Because Xkb-unaware clients and Xkb-aware clients that do
not request
<symbol>XkbNewKeyboardNotify</symbol>
events are never sent these events, the server’s notion of the legal keycode
range never changes, and these clients never receive events from keys that fall
outside of their notion of the legal keycode range.
</para>


<para>
Clients that have not selected to receive
<symbol>XkbNewKeyboardNotify</symbol>
events do, however, receive the
<symbol>XkbNewKeyboardNotify</symbol>
event when a keyboard change occurs. Clients that have not selected to receive
this event also receive numerous other events detailing the individual changes
that occur when a keyboard change occurs.
</para>


<para>
Clients wishing to track changes in
<structfield>min_key_code</structfield>
and
<structfield>max_key_code</structfield>
must watch for both
<symbol>XkbNewKeyboardNotify</symbol>
and
<symbol>XkbMapNotify</symbol>
events, because a simple mapping change causes an
<symbol>XkbMapNotify</symbol>
event and may change the range of valid keycodes, but does not cause an
<symbol>XkbNewKeyboardNotify</symbol>
event. If a client does not select for
<symbol>XkbNewKeyboardNotify</symbol>
events, the server restricts the range of keycodes reported to the client.
</para>


<para>
In addition to filtering out-of-range key events, Xkb:
</para>

<itemizedlist>
<listitem>
  <para>
Adjusts core protocol
<symbol>MappingNotify</symbol>
events to refer only to keys that match the stored legal range.
  </para>
</listitem>
<listitem>
  <para>
Reports keyboard mappings for keys that match the stored legal range to clients
that issue a core protocol
<systemitem>GetKeyboardMapping</systemitem>
request.
  </para>
</listitem>
<listitem>
  <para>
Reports modifier mappings only for keys that match the stored legal range to
clients that issue a core protocol
<systemitem>GetModifierMapping</systemitem>
request.
  </para>
</listitem>
<listitem>
  <para>
Restricts the core protocol
<systemitem>ChangeKeyboardMapping</systemitem>
and
<systemitem>SetModifierMapping</systemitem>
requests to keys that fall inside the stored legal range.
  </para>
</listitem>
</itemizedlist>

<para>
In short, Xkb does everything possible to hide from Xkb-unaware clients the
fact that the range of legal keycodes has changed, because such clients cannot
be expected to deal with them. Xkb events and requests are not modified in this
manner; all Xkb events report the full range of legal keycodes. No requested
Xkb events are discarded, and no Xkb requests have their keycode range clamped.
</para>

<indexterm significance="preferred" zone="Replacing_a_Keyboard_On_the_Fly">
<primary>events</primary><secondary><symbol>XkbNewKeyboardNotify</symbol></secondary></indexterm>
<indexterm significance="preferred" zone="Replacing_a_Keyboard_On_the_Fly">
<primary><structname>XkbNewKeyboardNotifyEvent</structname></primary></indexterm>

<para>
The structure for the
<symbol>XkbNewKeyboardNotify</symbol>
event is defined as follows:

<programlisting>
typedef struct _XkbNewKeyboardNotify {
    int            type;         /* Xkb extension base event code */
    unsigned long  serial;       /* X server serial number for event */
    Bool           send_event;   /* <symbol>True</symbol> &rArr; synthetically generated */
    Display *      display;      /* server connection where event generated */
    Time           time;         /* server time when event generated */
    int            xkb_type;     /* <symbol>XkbNewKeyboardNotify</symbol> */
    int            device;       /* device ID of new keyboard */
    int            old_device;   /* device ID of old keyboard */
    int            min_key_code; /* min keycode of new keyboard */
    int            max_key_code; /* max keycode of new keyboard */
    int            old_min_key_code; /* min keycode of old keyboard */
    int            old_max_key_code; /* max keycode of old keyboard */
    unsigned int   changed;      /* changed aspects - see masks below */
    char           req_major;    /* major request that caused change */
    char           req_minor;    /* minor request that caused change */
} <structname>XkbNewKeyboardNotifyEvent</structname>;
</programlisting></para>

<para>
To receive name notify events, use
<function>XkbSelectEvents</function>
(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) with
<symbol>XkbNewKeyboardNotifyMask</symbol>
in both the
<parameter>bits_to_change</parameter>
and
<parameter>values_for_bits</parameter>
parameters. To receive events for only specific names, use
<function>XkbSelectEventDetails</function>.
Set the
<structfield>event_type</structfield>
parameter to
<symbol>XkbNewKeyboardNotify</symbol>,
and set both the
<parameter>bits_to_change</parameter>
and
<parameter>values_for_bits</parameter>
detail parameter to a mask composed of a bitwise OR of masks in
<link linkend="table19.1">Table 19.1</link>.
</para>

<table id='table19.1' frame='topbot'>
<title>XkbNewKeyboardNotifyEvent Details</title>
<?dbfo keep-together="always" ?>
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='2.0*'/>
<colspec colname='c2' colwidth='1.0*'/>
<colspec colname='c3' colwidth='2.0*'/>
<thead>
<row rowsep='1'>
  <entry>XkbNewKeyboardNotify Event Details</entry>
  <entry>Value</entry>
  <entry>Circumstances</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry><symbol>XkbNKN_KeycodesMask</symbol></entry>
    <entry>(1L&lt;&lt;0)</entry>
    <entry>Notification of keycode range changes wanted</entry>
  </row>
  <row>
    <entry><symbol>XkbNKN_GeometryMask</symbol></entry>
    <entry>(1L&lt;&lt;1)</entry>
    <entry>Notification of geometry changes wanted</entry>
  </row>
  <row>
    <entry><symbol>XkbNKN_DeviceIDMask</symbol></entry>
    <entry>(1L&lt;&lt;2)</entry>
    <entry>Notification of device ID changes wanted</entry>
  </row>
  <row>
    <entry><symbol>XkbAllNewKeyboardEventsMask</symbol></entry>
    <entry>(0x7)</entry>
    <entry>Includes all of the above masks</entry>
  </row>
</tbody>
</tgroup>
</table>

<para>
The
<structfield>req_major</structfield>
and
<structfield>req_minor</structfield>
fields indicate what type of keyboard change has occurred.
</para>


<para>
If
<structfield>req_major</structfield>
and
<structfield>req_minor</structfield>
are zero, the device change was not caused by a software request to the server
— a spontaneous change has occurred, such as hot-plugging a new device. In
this case,
<structfield>device</structfield>
is the device identifier for the new, current X keyboard device, but no
implementation-independent guarantee can be made about
<structfield>old_device</structfield>.
<structfield>old_device</structfield>
may be identical to
<structfield>device</structfield>
(an implementor is permitted to reuse the device specifier when the device
changes); or it may be different. Note that
<structfield>req_major</structfield>
and
<structfield>req_minor</structfield>
being zero do not necessarily mean that the physical keyboard device has
changed; rather, they only imply a spontaneous change outside of software
control (some systems have keyboards that can change personality at the press
of a key).
</para>


<para>
If the keyboard change is the result of an X Input Extension
<systemitem>ChangeKeyboardDevice</systemitem>
request,
<structfield>req_major</structfield>
contains the input extension major opcode, and
<structfield>req_minor</structfield>
contains the input extension request number for
<symbol>X_ChangeKeyboardDevice</symbol>.
In this case,
<structfield>device</structfield>
and
<structfield>old_device</structfield>
are different, with
<structfield>device</structfield>
being the identifier for the new, current X keyboard device, and
<structfield>old_device</structfield>
being the identifier for the former device.
</para>


<para>
If the keyboard change is the result of an
<function>XkbGetKeyboardByName</function>
function call, which generates an
<symbol>X_kbGetKbdByName</symbol>
request,
<structfield>req_major</structfield>
contains the Xkb extension base event code (see <link linkend="Initializing_the_Keyboard_Extension">section 2.4</link>), and
<structfield>req_minor</structfield>
contains the event code for the Xkb extension request
<symbol>X_kbGetKbdByName</symbol>.
<structfield>device</structfield>
contains the device identifier for the new device, but nothing definitive can
be said for
<structfield>old_device</structfield>;
it may be identical to
<structfield>device</structfield>,
or it may be different, depending on the implementation.
</para>

</chapter>