1
<chapter id='replacing_a_keyboard_on_the_fly'>
2
<title>Replacing a Keyboard "On the Fly"</title>
5
Some operating system and X server implementations allow "hot plugging" of
6
input devices. When using these implementations, input devices can be unplugged
7
and new ones plugged in without restarting the software that is using those
8
devices. There is no provision in the standard X server for notification of
9
client programs if input devices are unplugged and/or new ones plugged in. In
10
the case of the X keyboard, this could result in the X server having a keymap
11
that does not match the new keyboard.
16
If the X server implementation supports the X input device extension, a client
17
program may also change the X keyboard programmatically. The
18
XChangeKeyboardDevice input extension request allows a client to designate an
19
input extension keyboard device as the X keyboard, in which case the old X
20
keyboard device becomes inaccessible except via the input device extension. In
21
this case, core protocol <emphasis>
22
XMappingNotify</emphasis>
23
and input extension <emphasis>
24
XChangeDeviceNotify</emphasis>
25
events are generated to notify all clients that a new keyboard with a new
26
keymap has been designated.
31
When a client opens a connection to the X server, the server reports the
32
minimum and maximum keycodes. The server keeps track of the minimum and maximum
33
keycodes last reported to each client. When delivering events to a particular
34
client, the server filters out any events that fall outside of the valid range
40
Xkb provides an <emphasis>
41
XkbNewKeyboardNotify</emphasis>
42
event that reports a change in keyboard geometry and/or the range of supported
43
keycodes. The server can generate an <emphasis>
44
XkbNewKeyboardNotify</emphasis>
45
event when it detects a new keyboard or in response to an <emphasis>
46
XkbGetKeyboardByName</emphasis>
47
request that loads a new keyboard description. Selecting for <emphasis>
48
XkbNewKeyboardNotify</emphasis>
49
events allows Xkb-aware clients to be notified whenever a keyboard change
50
occurs that may affect the keymap.
55
When a client requests <emphasis>
56
XkbNewKeyboardNotify</emphasis>
57
events, the server compares the range of keycodes for the current keyboard to
58
the range of keycodes that are valid for the client. If they are not the same,
59
the server immediately sends the client an <emphasis>
60
XkbNewKeyboardNotify</emphasis>
61
event. Even if the "new" keyboard is not new to the server, it is new to this
67
When the server sends an <emphasis>
68
XkbNewKeyboardNotify</emphasis>
69
event to a client to inform it of a new keycode range, it resets the stored
70
range of legal keycodes for the client to the keycode range reported in the
71
event; it does not reset this range for the client if it does not sent an
73
XkbNewKeyboardNotify</emphasis>
74
event to a client. Because Xkb-unaware clients and Xkb-aware clients that do
75
not request <emphasis>
76
XkbNewKeyboardNotify</emphasis>
77
events are never sent these events, the server’s notion of the legal keycode
78
range never changes, and these clients never receive events from keys that fall
79
outside of their notion of the legal keycode range.
84
Clients that have not selected to receive <emphasis>
85
XkbNewKeyboardNotify</emphasis>
86
events do, however, receive the <emphasis>
87
XkbNewKeyboardNotify</emphasis>
88
event when a keyboard change occurs. Clients that have not selected to receive
89
this event also receive numerous other events detailing the individual changes
90
that occur when a keyboard change occurs.
95
Clients wishing to track changes in <emphasis>
96
min_key_code</emphasis>
98
max_key_code</emphasis>
99
must watch for both <emphasis>
100
XkbNewKeyboardNotify</emphasis>
102
XkbMapNotify</emphasis>
103
events, because a simple mapping change causes an <emphasis>
104
XkbMapNotify</emphasis>
105
event and may change the range of valid keycodes, but does not cause an
107
XkbNewKeyboardNotify</emphasis>
108
event. If a client does not select for <emphasis>
109
XkbNewKeyboardNotify</emphasis>
110
events, the server restricts the range of keycodes reported to the client.
115
In addition to filtering out-of-range key events, Xkb:
121
Adjusts core protocol <emphasis>
122
MappingNotify</emphasis>
123
events to refer only to keys that match the stored legal range.
128
Reports keyboard mappings for keys that match the stored legal range to clients
129
that issue a core protocol <emphasis>
130
GetKeyboardMapping</emphasis>
136
Reports modifier mappings only for keys that match the stored legal range to
137
clients that issue a core protocol <emphasis>
138
GetModifierMapping</emphasis>
144
Restricts the core protocol <emphasis>
145
ChangeKeyboardMapping</emphasis>
147
SetModifierMapping</emphasis>
148
requests to keys that fall inside the stored legal range.
154
In short, Xkb does everything possible to hide from Xkb-unaware clients the
155
fact that the range of legal keycodes has changed, because such clients cannot
156
be expected to deal with them. Xkb events and requests are not modified in this
157
manner; all Xkb events report the full range of legal keycodes. No requested
158
Xkb events are discarded, and no Xkb requests have their keycode range clamped.
163
The structure for the <emphasis>
164
XkbNewKeyboardNotify</emphasis>
165
event is defined as follows:
168
<para><programlisting>
169
typedef struct _XkbNewKeyboardNotify {
170
int type; /* Xkb extension base event code */
171
unsigned long serial; /* X server serial number for event*/
172
Bool send_event; /* <emphasis>True</emphasis>
173
=> synthetically generated */
174
Display * display; /* server connection where event generated */
175
Time time; /* server time when event generated */
176
int xkb_type; /* <emphasis>XkbNewKeyboardNotify</emphasis> */
177
int device; /* device ID of new keyboard */
178
int old_device; /* device ID of old keyboard */
179
int min_key_code; /* min keycode of new keyboard */
180
int max_key_code; /* max keycode of new keyboard */
181
int old_min_key_code; /* min keycode of old keyboard */
182
int old_max_key_code; /* max keycode of old keyboard */
183
unsigned int changed; /* changed aspects - see masks below */
184
char req_major; /* major request that caused change */
185
char req_minor; /* minor request that caused change */
186
} <emphasis>XkbNewKeyboardNotifyEvent</emphasis>;
187
</programlisting></para>
190
To receive name notify events, use <emphasis>
191
XkbSelectEvents</emphasis>
192
(see section 4.3) with <emphasis>
193
XkbNewKeyboardNotifyMask</emphasis>
194
in both the <emphasis>
195
bits_to_change</emphasis>
197
values_for_bits</emphasis>
198
parameters. To receive events for only specific names, use <emphasis>
199
XkbSelectEventDetails</emphasis>
201
event_type</emphasis>
202
parameter to <emphasis>
203
XkbNewKeyboardNotify</emphasis>
204
, and set both the <emphasis>
205
bits_to_change </emphasis>
207
values_for_bits</emphasis>
208
detail parameter to a mask composed of a bitwise OR of masks in Table 19.1.
212
<title>XkbNewKeyboardNotifyEvent Details</title>
214
<colspec colsep='0'/>
215
<colspec colsep='0'/>
216
<colspec colsep='0'/>
219
<entry>XkbNewKeyboardNotify Event Details</entry>
221
<entry>Circumstances</entry>
226
<entry><emphasis>XkbNKN_KeycodesMask</emphasis></entry>
227
<entry>(1L<<0)</entry>
228
<entry>Notification of keycode range changes wanted</entry>
231
<entry><emphasis>XkbNKN_GeometryMask</emphasis></entry>
232
<entry>(1L<<1)</entry>
233
<entry>Notification of geometry changes wanted</entry>
236
<entry>XkbNKN_DeviceIDMask</entry>
237
<entry>(1L<<2)</entry>
238
<entry>Notification of device ID changes wanted</entry>
241
<entry><emphasis>XkbNKN_AllChangesMask</emphasis></entry>
243
<entry>Includes all of the above masks</entry>
254
fields indicate what type of keyboard change has occurred.
263
are zero, the device change was not caused by a software request to the server
264
— a spontaneous change has occurred, such as hot-plugging a new device. In
265
this case, <emphasis>
267
is the device identifier for the new, current X keyboard device, but no
268
implementation-independent guarantee can be made about <emphasis>
269
old_device</emphasis>
271
old_device</emphasis>
272
may be identical to <emphasis>
274
(an implementor is permitted to reuse the device specifier when the device
275
changes); or it may be different. Note that <emphasis>
279
being zero do not necessarily mean that the physical keyboard device has
280
changed; rather, they only imply a spontaneous change outside of software
281
control (some systems have keyboards that can change personality at the press
287
If the keyboard change is the result of an X Input Extension <emphasis>
288
ChangeKeyboardDevice</emphasis>
291
contains the input extension major opcode, and <emphasis>
293
contains the input extension request number for <emphasis>
294
X_ChangeKeyboardDevice</emphasis>
295
. In this case, <emphasis>
298
old_device</emphasis>
299
are different, with <emphasis>
301
being the identifier for the new, current X keyboard device, and <emphasis>
302
old_device</emphasis>
303
being the identifier for the former device.
308
If the keyboard change is the result of an <emphasis>
309
XkbGetKeyboardByName</emphasis>
310
function call, which generates an <emphasis>
311
X_kbGetKbdByName</emphasis>
314
contains the Xkb extension base event code (see section 2.4), and <emphasis>
316
contains the event code for the Xkb extension request <emphasis>
317
X_kbGetKbdByName</emphasis>
320
contains the device identifier for the new device, but nothing definitive can
321
be said for <emphasis>
322
old_device</emphasis>
323
; it may be identical to <emphasis>
325
, or it may be different, depending on the implementation.
added
removed
specs/XKB/ch19.xml
