libX11 git update 14 sep 2011

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 &lt;X11/extensions/Xkb.h&gt;.
+</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> =&gt; 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=&gt;select, 0-&gt;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&lt;&lt;0)</entry>
+    <entry>Keyboard geometry change</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+      <emphasis>XkbMapNotifyMask</emphasis>
+    </entry>
+    <entry>(1L&lt;&lt;1)</entry>
+    <entry>Keyboard mapping change</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<para><emphasis>XkbStateNotifyMask</emphasis></para>
+    </entry>
+    <entry>(1L&lt;&lt;2)</entry>
+    <entry><para>Keyboard state change</para></entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<para><emphasis>XkbControlsNotifyMask</emphasis></para>
+    </entry>
+    <entry>(1L&lt;&lt;3)</entry>
+    <entry>Keyboard control change</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<emphasis>XkbIndicatorStateNotifyMask</emphasis>
+    </entry>
+    <entry>(1L&lt;&lt;4)</entry>
+    <entry>Keyboard indicator state change</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<emphasis>XkbIndicatorMapNotifyMask</emphasis>
+    </entry>
+    <entry>(1L&lt;&lt;5)</entry>
+    <entry>Keyboard indicator map change</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<emphasis>XkbNamesNotifyMask</emphasis>
+    </entry>
+    <entry>(1L&lt;&lt;6)</entry>
+    <entry>Keyboard name change</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<emphasis>XkbCompatMapNotifyMask</emphasis>
+    </entry>
+    <entry>(1L&lt;&lt;7)</entry>
+    <entry>Keyboard compat map change</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<emphasis>XkbBellNotifyMask</emphasis>
+    </entry>
+    <entry>(1L&lt;&lt;8)</entry>
+    <entry>Bell</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<emphasis>XkbActionMessageMask</emphasis>
+    </entry>
+    <entry>(1L&lt;&lt;9)</entry>
+    <entry>Action message</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<emphasis>XkbAccessXNotifyMask</emphasis>
+    </entry>
+    <entry>(1L&lt;&lt;10)</entry>
+    <entry>AccessX features</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>
+<emphasis>XkbExtensionDeviceNotifyMask</emphasis>
+    </entry>
+    <entry>(1L&lt;&lt;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,&amp;xkbev.core);</para>
+</sect1>
+</chapter>