diff options
Diffstat (limited to 'libX11/specs/XKB/ch19.xml')
| -rw-r--r-- | libX11/specs/XKB/ch19.xml | 351 |
1 files changed, 177 insertions, 174 deletions
diff --git a/libX11/specs/XKB/ch19.xml b/libX11/specs/XKB/ch19.xml index 4b4b0a023..faa62a278 100644 --- a/libX11/specs/XKB/ch19.xml +++ b/libX11/specs/XKB/ch19.xml @@ -1,8 +1,12 @@ +<?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 "On the Fly"</title> +<title>Replacing a Keyboard <quote>On the Fly</quote></title> <para> -Some operating system and X server implementations allow "hot plugging" of +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 @@ -18,11 +22,11 @@ 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 +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> @@ -37,77 +41,75 @@ for the client. <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 +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 <emphasis> -XkbNewKeyboardNotify</emphasis> - events, the server compares the range of keycodes for the current keyboard to +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 <emphasis> -XkbNewKeyboardNotify</emphasis> - event. Even if the "new" keyboard is not new to the server, it is new to this -particular client. +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 <emphasis> -XkbNewKeyboardNotify</emphasis> - event to a client to inform it of a new keycode range, it resets the stored +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 -<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 +<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 <emphasis> -XkbNewKeyboardNotify</emphasis> - events do, however, receive the <emphasis> -XkbNewKeyboardNotify</emphasis> - event when a keyboard change occurs. Clients that have not selected to receive +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 <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. +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> @@ -118,34 +120,34 @@ In addition to filtering out-of-range key events, Xkb: <itemizedlist> <listitem> <para> -Adjusts core protocol <emphasis> -MappingNotify</emphasis> - events to refer only to keys that match the stored legal range. +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 <emphasis> -GetKeyboardMapping</emphasis> - request. +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 <emphasis> -GetModifierMapping</emphasis> - request. +clients that issue a core protocol +<systemitem>GetModifierMapping</systemitem> +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. +Restricts the core protocol +<systemitem>ChangeKeyboardMapping</systemitem> +and +<systemitem>SetModifierMapping</systemitem> +requests to keys that fall inside the stored legal range. </para> </listitem> </itemizedlist> @@ -158,57 +160,60 @@ 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 <emphasis> -XkbNewKeyboardNotify</emphasis> - event is defined as follows: -</para> +The structure for the +<symbol>XkbNewKeyboardNotify</symbol> +event is defined as follows: -<para><programlisting> +<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>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ 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 <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. +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 frame='topbot'> +<table id='table19.1' frame='topbot'> <title>XkbNewKeyboardNotifyEvent Details</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -224,22 +229,22 @@ and<emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbNKN_KeycodesMask</emphasis></entry> + <entry><symbol>XkbNKN_KeycodesMask</symbol></entry> <entry>(1L<<0)</entry> <entry>Notification of keycode range changes wanted</entry> </row> <row> - <entry><emphasis>XkbNKN_GeometryMask</emphasis></entry> + <entry><symbol>XkbNKN_GeometryMask</symbol></entry> <entry>(1L<<1)</entry> <entry>Notification of geometry changes wanted</entry> </row> <row> - <entry>XkbNKN_DeviceIDMask</entry> + <entry><symbol>XkbNKN_DeviceIDMask</symbol></entry> <entry>(1L<<2)</entry> <entry>Notification of device ID changes wanted</entry> </row> <row> - <entry><emphasis>XkbNKN_AllChangesMask</emphasis></entry> + <entry><symbol>XkbAllNewKeyboardEventsMask</symbol></entry> <entry>(0x7)</entry> <entry>Includes all of the above masks</entry> </row> @@ -248,36 +253,35 @@ and<emphasis> </table> <para> -The <emphasis> -req_major</emphasis> - and <emphasis> -req_minor</emphasis> - fields indicate what type of keyboard change has occurred. +The +<structfield>req_major</structfield> +and +<structfield>req_minor</structfield> +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 +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, <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 +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). @@ -285,45 +289,44 @@ of a key). <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. +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 <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. +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> |