ch14.xml revision ea1d6981 
1<chapter id='Replacing_the_Keyboard_On_the_Fly'>
2<title>Replacing the Keyboard "On-the-Fly"</title>
3
4<para>
5XKB supports the <emphasis>
6XkbNewKeyboardNotify</emphasis>
7 event, which reports a change in keyboard geometry or the range of supported
8keycodes. The server can generate an <emphasis>
9XkbNewKeyboardNotify</emphasis>
10 event when it detects a new keyboard, or in response to an <emphasis>
11XkbGetKeyboardByName</emphasis>
12 request (see <link linkend='Using_the_Servers_Database_of_Keyboard_Components'>Using the Server’s
13Database of Keyboard Components</link>) which loads a new keyboard description.
14</para>
15
16
17<para>
18When a client opens a connection to the X server, the server reports the
19minimum and maximum keycodes. If the range of supported keycodes is changed,
20XKB keeps track of the minimum and maximum keycodes that were reported to each
21client and filters out any events that fall outside of that range. Note that
22these events are simply ignored; they are not delivered to some other client.
23</para>
24
25
26<para>
27When the server sends an <emphasis>
28XkbNewKeyboardNotify</emphasis>
29 event to a client to inform it of the new keycode range, XKB resets the stored
30range of legal keycodes to the keycode range reported in the event. Non-XKB
31clients and XKB-aware clients that do not request <emphasis>
32XkbNewKeyboardNotify</emphasis>
33 events never receive events from keys that fall outside of the legal range
34that XKB maintains for that client.
35</para>
36
37
38<para>
39When a client requests <emphasis>
40XkbNewKeyboardNotify</emphasis>
41 events, the server compares the range of keycodes for the current keyboard to
42the range of keycodes that are valid for the client. If they are not the same,
43the server immediately sends that client an <emphasis>
44XkbNewKeyboardNotify</emphasis>
45 event. Even if the "new" keyboard is not new to the server, it is new to this
46particular client.
47</para>
48
49
50<para>
51In addition to filtering out-of-range key events, XKB:
52</para>
53
54<itemizedlist>
55<listitem>
56  <para>Adjusts core protocol <emphasis>
57MappingNotify</emphasis>
58 events to refer only to keys that match the stored legal range.
59  </para>
60</listitem>
61<listitem>
62  <para>Reports keyboard mappings for keys that match the stored legal range to
63clients that issue a core protocol <emphasis>
64GetKeyboardMapping</emphasis>
65 request.
66  </para>
67</listitem>
68<listitem>
69  <para>Reports modifier mappings only for keys that match the stored legal
70range to clients that issue a core protocol <emphasis>
71GetModifierMapping</emphasis>
72 request.
73  </para>
74</listitem>
75<listitem>
76  <para>Restricts the core protocol <emphasis>
77ChangeKeyboardMapping</emphasis>
78 and <emphasis>
79SetModifierMapping</emphasis>
80 requests to keys that fall inside the stored legal range.
81  </para>
82</listitem>
83</itemizedlist>
84
85<para>
86In short, XKB does everything possible to hide the fact that the range of legal
87keycodes has changed from clients non-XKB clients, which cannot be expected to
88deal with it. The corresponding XKB events and requests do <emphasis>
89not</emphasis>
90 pay attention to the legal keycode range in the same way because XKB makes it
91possible for clients to track changes to the keycode range for a device and
92respond to them.
93</para>
94</chapter>
95