diff options
Diffstat (limited to 'libX11/specs/XKB/ch04.xml')
| -rw-r--r-- | libX11/specs/XKB/ch04.xml | 825 |
1 files changed, 825 insertions, 0 deletions
diff --git a/libX11/specs/XKB/ch04.xml b/libX11/specs/XKB/ch04.xml new file mode 100644 index 000000000..dc9065d79 --- /dev/null +++ b/libX11/specs/XKB/ch04.xml @@ -0,0 +1,825 @@ +<chapter id='xkb_events'> +<title>Xkb Events</title> + +<para> +The primary way the X server communicates with clients is by sending X events +to them. Some events are sent to all clients, while others are sent only to +clients that have requested them. Some of the events that can be requested are +associated with a particular window and are only sent to those clients who have +both requested the event and specified the window in which the event occurred. +</para> + + +<para> +The Xkb extension uses events to communicate the keyboard status to interested +clients. These events are not associated with a particular window. Instead, all +Xkb keyboard status events are reported to all interested clients, regardless +of which window currently has the keyboard focus and regardless of the grab +state of the keyboard.<footnote><para>The one exception to this rule is the +XkbExtensionDeviceNotify event report that is sent when a client attempts to +use an unsupported feature of an X Input Extension device (see section 21.4). +</para></footnote> <!-- xref --> +</para> + + +<para> +The X server reports the events defined by the Xkb extension to your client +application only if you have requested them. You may request Xkb events by +calling either <emphasis> +XkbSelectEvents</emphasis> + or <emphasis> +XkbSelectEventDetails</emphasis> +. <emphasis> +XkbSelectEvents</emphasis> + requests Xkb events by their event type and causes them to be reported to your +client application under all circumstances. You can specify a finer granularity +for event reporting by using <emphasis> +XkbSelectEventDetails</emphasis> +; in this case events are reported only when the specific detail conditions you +specify have been met. +</para> + +<sect1 id='xkb_event_types'> +<title>Xkb Event Types</title> + +<para> +The Xkb Extension adds new event types to the X protocol definition. An Xkb +event type is defined by two fields in the X event data structure. One is the +<emphasis> +type</emphasis> + field, containing the <emphasis> +base event code.</emphasis> + This base event code is a value the X server assigns to each X extension at +runtime and thatidentifies the extension that generated the event; thus, the +event code in the <emphasis> +type</emphasis> + field identifies the event as an Xkb extension event, rather than an event +from another extension or a core X protocol event. You can obtain the base +event code via a call to <emphasis> +XkbQueryExtension</emphasis> + or <emphasis> +XkbOpenDisplay</emphasis> +. The second field is the Xkb event type, which contains a value uniquely +identifying each different Xkb event type. Possible values are defined by +constants declared in the header file <X11/extensions/Xkb.h>. +</para> + + +<para> +Table 4.1 lists the categories of events defined by Xkb and their associated +event types, as defined in <emphasis> +Xkb.h</emphasis> +. Each event is described in more detail in the section referenced for that +event. +</para> + +<table frame='none'> +<title>Xkb Event Types</title> +<tgroup cols='4'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Event Type</entry> + <entry>Conditions Generating Event</entry> + <entry>Section</entry> + <entry>Page</entry> +</row> +</thead> +<tbody> +<row rowsep='0'> + <entry> + <para><emphasis>XkbNewKeyboardNotify</emphasis></para> + </entry> + <entry> + <para>Keyboard geometry; keycode range change</para> + </entry> + <entry> + <para>19</para> + </entry> + <entry> + <para>187</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para> + <emphasis>XkbMapNotify</emphasis> + </para> + </entry> + <entry> + <para>Keyboard mapping change</para> + </entry> + <entry> + <para>14.4</para> + </entry> + <entry> + <para>122</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbStateNotify</emphasis></para> + </entry> + <entry> + <para>Keyboard state change</para> + </entry> + <entry> + <para>5.4</para> + </entry> + <entry> + <para>25</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbControlsNotify</emphasis></para> + </entry> + <entry> + <para>Keyboard controls state change</para> + </entry> + <entry> + <para>10.11</para> + </entry> + <entry> + <para>79</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbIndicatorStateNotify</emphasis></para> + </entry> + <entry> + <para>Keyboard indicators state change</para> + </entry> + <entry> + <para>8.5</para> + </entry> + <entry> + <para>45</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbIndicatorMapNotify</emphasis></para> + </entry> + <entry> + <para>Keyboard indicators map change</para> + </entry> + <entry> + <para>8.5</para> + </entry> + <entry> + <para>45</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbNamesNotify</emphasis></para> + </entry> + <entry> + <para>Keyboard name change</para> + </entry> + <entry> + <para>18.5</para> + </entry> + <entry> + <para>185</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbCompatMapNotify</emphasis></para> + </entry> + <entry> + <para>Keyboard compatibility map change</para> + </entry> + <entry> + <para>17.5</para> + </entry> + <entry> + <para>178</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbBellNotify</emphasis></para> + </entry> + <entry> + <para>Keyboard bell generated</para> + </entry> + <entry> + <para>9.4</para> + </entry> + <entry> + <para>52</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbActionMessage</emphasis></para> + </entry> + <entry> + <para>Keyboard action message</para> + </entry> + <entry> + <para>16.1.11</para> + </entry> + <entry> + <para>155</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbAccessXNotify</emphasis></para> + </entry> + <entry> + <para>AccessX state change</para> + </entry> + <entry> + <para>10.6.4</para> + </entry> + <entry> + <para>65</para> + </entry> +</row> +<row rowsep='0'> + <entry> + <para><emphasis>XkbExtensionDeviceNotify</emphasis></para> + </entry> + <entry> + <para>Extension device change</para> + </entry> + <entry> + <para>21.6</para> + </entry> + <entry> + <para>207</para> + </entry> +</row> +</tbody> +</tgroup> +</table> + +</sect1> +<sect1 id='xkb_event_data_structures'> +<title>Xkb Event Data Structures</title> + +<para> +Xkb reports each event it generates in a unique structure holding the data +values needed to describe the conditions the event is reporting. However, all +Xkb events have certain things in common. These common features are contained +in the same fields at the beginning of all Xkb event structures and are +described in the <emphasis> +XkbAnyEvent</emphasis> + structure: +</para> + +<para><programlisting> +typedef struct { + 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; /* Xkb minor event code */ + unsigned int device; /* Xkb device ID, will not be + <emphasis>XkbUseCoreKbd</emphasis> */ +} <emphasis>XkbAnyEvent</emphasis> +; +</programlisting></para> + +<para> +For any Xkb event, the <emphasis> +type</emphasis> + field is set to the base event code for the Xkb extension, assigned by the +server to all Xkb extension events. The <emphasis> +serial</emphasis> +, <emphasis> +send_event</emphasis> +, and <emphasis> +display</emphasis> + fields are as described for all X11 events. The <emphasis> +time</emphasis> + field is set to the time when the event was generated and is expressed in +milliseconds. The <emphasis> +xkb_type</emphasis> + field contains the minor extension event code, which is the extension event +type, and is one of the values listed in Table 4.1. The <emphasis> +device</emphasis> + field contains the keyboard device identifier associated with the event. This +is never <emphasis> +XkbUseCoreKbd</emphasis> +, even if the request that generated the event specified a device of <emphasis> +XkbUseCoreKbd</emphasis> +. If the request that generated the event specified <emphasis> +XkbUseCoreKbd</emphasis> +, <emphasis> +device</emphasis> + contains a value assigned by the server to specify the core keyboard. If the +request that generated the event specified an X input extension device, +<emphasis> +device</emphasis> + contains that same identifier. +</para> + + +<para> +Other data fields specific to individual Xkb events are described in subsequent +chapters where the events are described. +</para> + + +</sect1> +<sect1 id='selecting_xkb_events'> +<title>Selecting Xkb Events</title> + +<para> +Xkb events are selected using an event mask, much the same as normal core X +events are selected. However, unlike selecting core X events, where you must +specify the selection status (on or off) for all possible event types whenever +you wish to change the selection criteria for any one event, Xkb allows you to +restrict the specification to only the event types you wish to change. This +means that you do not need to remember the event selection values for all +possible types each time you want to change one of them. +</para> + + +<para> +Many Xkb event types are generated under several different circumstances. When +selecting to receive an Xkb event, you may specify either that you want it +delivered under all circumstances, or that you want it delivered only for a +subset of the possible circumstances. +</para> + +<para> +You can also deselect an event type that was previously selected for, using the +same granularity. +</para> + +<para> +Xkb provides two functions to select and deselect delivery of Xkb events. +<emphasis> +XkbSelectEvents</emphasis> + allows you to select or deselect delivery of more than one Xkb event type at +once. Events selected using <emphasis> +XkbSelectEvents</emphasis> + are delivered to your program under all circumstances that generate the +events. To restrict delivery of an event to a subset of the conditions under +which it occurs, use <emphasis> +XkbSelectEventDetails</emphasis> +. <emphasis> +XkbSelectEventDetails</emphasis> + only allows you to change the selection conditions for a single event at a +time, but it provides a means of fine-tuning the conditions under which the +event is delivered. +</para> + + +<para> +To select and / or deselect for delivery of one or more Xkb events and have +them delivered under all conditions, use <emphasis> +XkbSelectEvents</emphasis> +. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool <emphasis> +XkbSelectEvents</emphasis> +(<emphasis> +display, device_spec, bits_to_change, values_for_bits</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> +display</emphasis> +; /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +device_spec</emphasis> +; /* device ID, or <emphasis> +XkbUseCoreKbd</emphasis> + */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned long int <emphasis> +bits_to_change; </emphasis> +/* determines events to be selected / deselected */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned long int <emphasis> +values_for_bits</emphasis> +; /* 1=>select, 0->deselect; for events in <emphasis> +bits_to_change</emphasis> + */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +This request changes the Xkb event selection mask for the keyboard specified by +<emphasis> +device_spec</emphasis> +. +</para> + + +<para> +Each Xkb event that can be selected is represented by a bit in the <emphasis> +bits_to_change</emphasis> + and <emphasis> +values_for_bits</emphasis> + masks. Only the event selection bits specified by the <emphasis> +bits_to_change</emphasis> + parameter are affected; any unspecified bits are left unchanged. To turn on +event selection for an event, set the bit for the event in the <emphasis> +bits_to_change</emphasis> + parameter and set the corresponding bit in the <emphasis> +values_for_bits</emphasis> + parameter. To turn off event selection for an event, set the bit for the event +in the <emphasis> +bits_to_change</emphasis> + parameter and do not set the corresponding bit in the <emphasis> +values_for_bits</emphasis> + parameter. The valid values for both of these parameters are an inclusive +bitwise OR of the masks shown in Table 4.2. There is no interface to return +your client’s current event selection mask. Clients cannot set other +clients’ event selection masks. +</para> + + +<para> +If a bit is not set in the <emphasis> +bits_to_change</emphasis> + parameter, but the corresponding bit is set in the <emphasis> +values_for_bits</emphasis> + parameter, a <emphasis> +BadMatch</emphasis> + protocol error results. If an undefined bit is set in either the <emphasis> +bits_to_change</emphasis> + or the <emphasis> +values_for_bits</emphasis> + parameter, a <emphasis> +BadValue</emphasis> + protocol error results. +</para> + + +<para> +All event selection bits are initially zero for clients using the Xkb +extension. Once you set some bits, they remain set for your client until you +clear them via another call to <emphasis> +XkbSelectEvents</emphasis> +. +</para> + + +<para> +<emphasis> +XkbSelectEvents</emphasis> + returns <emphasis> +False</emphasis> + if the Xkb extension has not been initilialized and <emphasis> +True</emphasis> + otherwise. +</para> + + +<para> +To select or deselect for a specific Xkb event and optionally place conditions +on when events of that type are reported to your client, use <emphasis> +XkbSelectEventDetails</emphasis> +. This allows you to exercise a finer granularity of control over delivery of +Xkb events with <emphasis> +XkbSelectEvents</emphasis> +. +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool <emphasis> +XkbSelectEventDetails</emphasis> +(<emphasis> +display, device_spec, event_type, bits_to_change</emphasis> +, <emphasis> +values_for_bits</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> +display</emphasis> +; /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +device_spec</emphasis> +; /* device ID, or <emphasis> +XkbUseCoreKbd</emphasis> + */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +event_type</emphasis> +; /* Xkb event type of interest */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned long int <emphasis> +bits_to_change</emphasis> +; /* event selection details */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned long int <emphasis> +values_for_bits</emphasis> +; /* values for bits selected by <emphasis> +bits_to_change</emphasis> + */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +While <emphasis> +XkbSelectEvents</emphasis> + allows multiple events to be selected, <emphasis> +XkbSelectEventDetails</emphasis> + changes the selection criteria for a single type of Xkb event. The +interpretation of the <emphasis> +bits_to_change</emphasis> + and <emphasis> +values_for_bits</emphasis> + masks depends on the event type in question. +</para> + + +<para> +<emphasis> +XkbSelectEventDetails</emphasis> + changes the Xkb event selection mask for the keyboard specified by <emphasis> +device_spec</emphasis> + and the Xkb event specified by <emphasis> +event_type</emphasis> +. To turn on event selection for an event detail, set the bit for the detail in +the <emphasis> +bits_to_change</emphasis> + parameter and set the corresponding bit in the <emphasis> +values_for_bits</emphasis> + parameter. To turn off event detail selection for a detail, set the bit for +the detail in the <emphasis> +bits_to_change</emphasis> + parameter and do not set the corresponding bit in the <emphasis> +values_for_bits</emphasis> + parameter. +</para> + + +<para> +If an invalid event type is specified, a <emphasis> +BadValue</emphasis> + protocol error results. If a bit is not set in the <emphasis> +bits_to_change</emphasis> + parameter, but the corresponding bit is set in the <emphasis> +values_for_bits</emphasis> + parameter, a <emphasis> +BadMatch</emphasis> + protocol error results. If an undefined bit is set in either the <emphasis> +bits_to_change</emphasis> + or the <emphasis> +values_for_bits</emphasis> + parameter, a <emphasis> +BadValue</emphasis> + protocol error results. +</para> + + +<para> +For each type of Xkb event, the legal event details that you can specify in the +<emphasis> +XkbSelectEventDetails</emphasis> + request are listed in the chapters that describe each event in detail. +</para> + + +<sect2 id='event_masks'> +<title>Event Masks</title> + +<para> +The X server reports the events defined by Xkb to your client application only +if you have requested them via a call to <emphasis> +XkbSelectEvents</emphasis> + or <emphasis> +XkbSelectEventDetails</emphasis> +. Specify the event types in which you are interested in a mask, as described +in section 4.3. +</para> + + +<para> +Table 4.2 lists the event mask constants that can be specified with the <!-- xref --> +<emphasis> +XkbSelectEvents</emphasis> + request and the circumstances in which the mask should be specified. +</para> + +<table frame='none'> +<title>XkbSelectEvents Mask Constants</title> +<tgroup cols='3'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Event Mask</entry> + <entry>Value</entry> + <entry>Notification Wanted</entry> +</row> +</thead> +<tbody> + <row rowsep='0'> + <entry> +<emphasis>XkbNewKeyboardNotifyMask</emphasis> + </entry> + <entry>(1L<<0)</entry> + <entry>Keyboard geometry change</entry> + </row> + <row rowsep='0'> + <entry> + <emphasis>XkbMapNotifyMask</emphasis> + </entry> + <entry>(1L<<1)</entry> + <entry>Keyboard mapping change</entry> + </row> + <row rowsep='0'> + <entry> +<para><emphasis>XkbStateNotifyMask</emphasis></para> + </entry> + <entry>(1L<<2)</entry> + <entry><para>Keyboard state change</para></entry> + </row> + <row rowsep='0'> + <entry> +<para><emphasis>XkbControlsNotifyMask</emphasis></para> + </entry> + <entry>(1L<<3)</entry> + <entry>Keyboard control change</entry> + </row> + <row rowsep='0'> + <entry> +<emphasis>XkbIndicatorStateNotifyMask</emphasis> + </entry> + <entry>(1L<<4)</entry> + <entry>Keyboard indicator state change</entry> + </row> + <row rowsep='0'> + <entry> +<emphasis>XkbIndicatorMapNotifyMask</emphasis> + </entry> + <entry>(1L<<5)</entry> + <entry>Keyboard indicator map change</entry> + </row> + <row rowsep='0'> + <entry> +<emphasis>XkbNamesNotifyMask</emphasis> + </entry> + <entry>(1L<<6)</entry> + <entry>Keyboard name change</entry> + </row> + <row rowsep='0'> + <entry> +<emphasis>XkbCompatMapNotifyMask</emphasis> + </entry> + <entry>(1L<<7)</entry> + <entry>Keyboard compat map change</entry> + </row> + <row rowsep='0'> + <entry> +<emphasis>XkbBellNotifyMask</emphasis> + </entry> + <entry>(1L<<8)</entry> + <entry>Bell</entry> + </row> + <row rowsep='0'> + <entry> +<emphasis>XkbActionMessageMask</emphasis> + </entry> + <entry>(1L<<9)</entry> + <entry>Action message</entry> + </row> + <row rowsep='0'> + <entry> +<emphasis>XkbAccessXNotifyMask</emphasis> + </entry> + <entry>(1L<<10)</entry> + <entry>AccessX features</entry> + </row> + <row rowsep='0'> + <entry> +<emphasis>XkbExtensionDeviceNotifyMask</emphasis> + </entry> + <entry>(1L<<11)</entry> + <entry>Extension device</entry> + </row> + <row rowsep='0'> + <entry> +<emphasis>XkbAllEventsMask</emphasis> + </entry> + <entry>(0xFFF)</entry> + <entry>All Xkb events</entry> + </row> +</tbody> +</tgroup> +</table> + +</sect2> +</sect1> +<sect1 id='unified_xkb_event_type'> +<title>Unified Xkb Event Type</title> + +<para> +The <emphasis> +XkbEvent</emphasis> + structure is a union of the individual structures declared for each Xkb event +type and for the core protocol <emphasis> +XEvent</emphasis> + type. Given an <emphasis> +XkbEvent</emphasis> + structure, you may use the <emphasis> +type</emphasis> + field to determine if the event is an Xkb event (<emphasis> +type</emphasis> + equals the Xkb base event code; see section 2.4). If the event is an Xkb +event, you may then use the <emphasis> +any.xkb_type</emphasis> + field to determine the type of Xkb event and thereafter access the +event-dependent components using the union member corresponding to the +particular Xkb event type. +</para> + +<para><programlisting> +typedef union _XkbEvent { + int type; + XkbAnyEvent any; + XkbStateNotifyEvent state; + XkbMapNotifyEvent map; + XkbControlsNotifyEvent ctrls; + XkbIndicatorNotifyEvent indicators; + XkbBellNotifyEvent bell; + XkbAccessXNotifyEvent accessx; + XkbNamesNotifyEvent names; + XkbCompatMapNotifyEvent compat; + XkbActionMessageEvent message; + XkbExtensionDeviceNotifyEvent device; + XkbNewKeyboardNotifyEvent new_kbd; + XEvent core; +} <emphasis>XkbEvent</emphasis>; +</programlisting></para> + +<para> +This unified Xkb event type includes a normal <emphasis> +XEvent</emphasis> + as used by the core protocol, so it is straightforward for applications that +use Xkb events to call the X library event functions without having to cast +every reference. For example, to get the next event, you can simply declare a +variable of type <emphasis> +XkbEvent</emphasis> + and call: +</para> + +<para>XNextEvent(dpy,&xkbev.core);</para> +</sect1> +</chapter> |