diff options
Diffstat (limited to 'libX11/specs/XKB/ch19.xml')
| -rw-r--r-- | libX11/specs/XKB/ch19.xml | 328 |
1 files changed, 328 insertions, 0 deletions
diff --git a/libX11/specs/XKB/ch19.xml b/libX11/specs/XKB/ch19.xml new file mode 100644 index 000000000..9e675b358 --- /dev/null +++ b/libX11/specs/XKB/ch19.xml @@ -0,0 +1,328 @@ +<chapter id='replacing_a_keyboard_on_the_fly'> +<title>Replacing a Keyboard "On the Fly"</title> + +<para> +Some operating system and X server implementations allow "hot plugging" 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 <emphasis> +XMappingNotify</emphasis> + and input extension <emphasis> +XChangeDeviceNotify</emphasis> + 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 <emphasis> +XkbNewKeyboardNotify</emphasis> + event that reports a change in keyboard geometry and/or the range of supported +keycodes. The server can generate an <emphasis> +XkbNewKeyboardNotify</emphasis> + event when it detects a new keyboard or in response to an <emphasis> +XkbGetKeyboardByName</emphasis> + request that loads a new keyboard description. Selecting for <emphasis> +XkbNewKeyboardNotify</emphasis> + events allows Xkb-aware clients to be notified whenever a keyboard change +occurs that may affect the keymap. +</para> + + +<para> +When a client requests <emphasis> +XkbNewKeyboardNotify</emphasis> + 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 <emphasis> +XkbNewKeyboardNotify</emphasis> + event. Even if the "new" keyboard is not new to the server, it is new to this +particular client. +</para> + + +<para> +When the server sends an <emphasis> +XkbNewKeyboardNotify</emphasis> + 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 +<emphasis> +XkbNewKeyboardNotify</emphasis> + event to a client. Because Xkb-unaware clients and Xkb-aware clients that do +not request <emphasis> +XkbNewKeyboardNotify</emphasis> + 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 <emphasis> +XkbNewKeyboardNotify</emphasis> + events do, however, receive the <emphasis> +XkbNewKeyboardNotify</emphasis> + 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 <emphasis> +min_key_code</emphasis> + and <emphasis> +max_key_code</emphasis> + must watch for both <emphasis> +XkbNewKeyboardNotify</emphasis> + and <emphasis> +XkbMapNotify</emphasis> + events, because a simple mapping change causes an <emphasis> +XkbMapNotify</emphasis> + event and may change the range of valid keycodes, but does not cause an +<emphasis> +XkbNewKeyboardNotify</emphasis> + event. If a client does not select for <emphasis> +XkbNewKeyboardNotify</emphasis> + 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 <emphasis> +MappingNotify</emphasis> + 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 <emphasis> +GetKeyboardMapping</emphasis> + request. + </para> +</listitem> +<listitem> + <para> +Reports modifier mappings only for keys that match the stored legal range to +clients that issue a core protocol <emphasis> +GetModifierMapping</emphasis> + request. + </para> +</listitem> +<listitem> + <para> +Restricts the core protocol <emphasis> +ChangeKeyboardMapping</emphasis> + and <emphasis> +SetModifierMapping</emphasis> + 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> + + +<para> +The structure for the <emphasis> +XkbNewKeyboardNotify</emphasis> + event is defined as follows: +</para> + +<para><programlisting> +typedef struct _XkbNewKeyboardNotify { + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event*/ + Bool send_event; /* <emphasis>True</emphasis> + => synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <emphasis>XkbNewKeyboardNotify</emphasis> */ + 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 */ +} <emphasis>XkbNewKeyboardNotifyEvent</emphasis>; +</programlisting></para> + +<para> +To receive name notify events, use <emphasis> +XkbSelectEvents</emphasis> + (see section 4.3) with <emphasis> +XkbNewKeyboardNotifyMask</emphasis> + in both the <emphasis> +bits_to_change</emphasis> + and <emphasis> +values_for_bits</emphasis> + parameters. To receive events for only specific names, use <emphasis> +XkbSelectEventDetails</emphasis> +. Set the <emphasis> +event_type</emphasis> + parameter to <emphasis> +XkbNewKeyboardNotify</emphasis> +, and set both the <emphasis> +bits_to_change </emphasis> +and<emphasis> + values_for_bits</emphasis> + detail parameter to a mask composed of a bitwise OR of masks in Table 19.1. +</para> + +<table frame='none'> +<title>XkbNewKeyboardNotifyEvent Details</title> +<tgroup cols='3'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='1'> + <entry>XkbNewKeyboardNotify Event Details</entry> + <entry>Value</entry> + <entry>Circumstances</entry> + </row> +</thead> +<tbody> + <row rowsep='1'> + <entry><emphasis>XkbNKN_KeycodesMask</emphasis></entry> + <entry>(1L<<0)</entry> + <entry>Notification of keycode range changes wanted</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbNKN_GeometryMask</emphasis></entry> + <entry>(1L<<1)</entry> + <entry>Notification of geometry changes wanted</entry> + </row> + <row rowsep='0'> + <entry>XkbNKN_DeviceIDMask</entry> + <entry>(1L<<2)</entry> + <entry>Notification of device ID changes wanted</entry> + </row> + <row rowsep='0'> + <entry><emphasis>XkbNKN_AllChangesMask</emphasis></entry> + <entry>(0x7)</entry> + <entry>Includes all of the above masks</entry> + </row> +</tbody> +</tgroup> +</table> + +<para> +The <emphasis> +req_major</emphasis> + and <emphasis> +req_minor</emphasis> + fields indicate what type of keyboard change has occurred. +</para> + + +<para> +If <emphasis> +req_major</emphasis> + and <emphasis> +req_minor</emphasis> + 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, <emphasis> +device</emphasis> + is the device identifier for the new, current X keyboard device, but no +implementation-independent guarantee can be made about <emphasis> +old_device</emphasis> +. <emphasis> +old_device</emphasis> + may be identical to <emphasis> +device</emphasis> + (an implementor is permitted to reuse the device specifier when the device +changes); or it may be different. Note that <emphasis> +req_major</emphasis> + and <emphasis> +req_minor</emphasis> + 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 <emphasis> +ChangeKeyboardDevice</emphasis> + request, <emphasis> +req_major</emphasis> + contains the input extension major opcode, and <emphasis> +req_minor</emphasis> + contains the input extension request number for <emphasis> +X_ChangeKeyboardDevice</emphasis> +. In this case, <emphasis> +device</emphasis> + and <emphasis> +old_device</emphasis> + are different, with <emphasis> +device</emphasis> + being the identifier for the new, current X keyboard device, and <emphasis> +old_device</emphasis> + being the identifier for the former device. +</para> + + +<para> +If the keyboard change is the result of an <emphasis> +XkbGetKeyboardByName</emphasis> + function call, which generates an <emphasis> +X_kbGetKbdByName</emphasis> + request, <emphasis> +req_major</emphasis> + contains the Xkb extension base event code (see section 2.4), and <emphasis> +req_minor</emphasis> + contains the event code for the Xkb extension request <emphasis> +X_kbGetKbdByName</emphasis> +. <emphasis> +device</emphasis> + contains the device identifier for the new device, but nothing definitive can +be said for <emphasis> +old_device</emphasis> +; it may be identical to <emphasis> +device</emphasis> +, or it may be different, depending on the implementation. +</para> + +</chapter> |