specs/ch14.xml

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