diff options
Diffstat (limited to 'libX11/specs/libX11/CH11.xml')
| -rw-r--r-- | libX11/specs/libX11/CH11.xml | 2539 |
1 files changed, 2539 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH11.xml b/libX11/specs/libX11/CH11.xml new file mode 100644 index 000000000..1a9bfc139 --- /dev/null +++ b/libX11/specs/libX11/CH11.xml @@ -0,0 +1,2539 @@ +<chapter id="event_handling_functions">
+<title>Event Handling Functions</title>
+
+<para>
+This chapter discusses the Xlib functions you can use to:
+</para>
+<itemizedlist>
+ <listitem><para>Select events</para></listitem>
+ <listitem><para>Handle the output buffer and the event queue</para></listitem>
+ <listitem><para>Select events from the event queue</para></listitem>
+ <listitem><para>Send and get events</para></listitem>
+ <listitem><para>Handle protocol errors</para></listitem>
+</itemizedlist>
+<note><para>
+Some toolkits use their own event-handling functions and do not allow you to
+interchange these event-handling functions with those in Xlib. For further
+information, see the documentation supplied with the toolkit.
+</para></note>
+
+<para>
+Most applications simply are event loops: they wait for an event, decide what to do with it,
+execute some amount of code that results in changes to the display, and then wait for the next
+event.
+</para>
+
+<sect1 id="Selecting_Events">
+<title>Selecting Events</title>
+<!-- .XS -->
+<!-- (SN Selecting Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+There are two ways to select the events you want reported to your client
+application.
+One way is to set the event_mask member of the
+<function>XSetWindowAttributes</function>
+structure when you call
+<function>XCreateWindow</function>
+and
+<function>XChangeWindowAttributes</function>.
+Another way is to use
+<function>XSelectInput</function>.
+<indexterm significance="preferred"><primary>XSelectInput</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSelectInput</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSelectInput</function>
+function requests that the X server report the events associated with the
+specified event mask.
+Initially, X will not report any of these events.
+Events are reported relative to a window.
+If a window is not interested in a device event, it usually propagates to
+the closest ancestor that is interested,
+unless the do_not_propagate mask prohibits it.
+<indexterm><primary>Event</primary><secondary>propagation</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Setting the event-mask attribute of a window overrides any previous call
+for the same window but not for other clients.
+Multiple clients can select for the same events on the same window
+with the following restrictions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Multiple clients can select events on the same window because their event masks
+are disjoint.
+When the X server generates an event, it reports it
+to all interested clients.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Only one client at a time can select
+<function>CirculateRequest</function>,
+<function>ConfigureRequest</function>,
+or
+<function>MapRequest</function>
+events, which are associated with
+the event mask
+<function>SubstructureRedirectMask</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Only one client at a time can select
+a
+<function>ResizeRequest</function>
+event, which is associated with
+the event mask
+<function>ResizeRedirectMask</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Only one client at a time can select a
+<function>ButtonPress </function>
+event, which is associated with
+the event mask
+<function>ButtonPressMask</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The server reports the event to all interested clients.
+</para>
+<para>
+<!-- .LP -->
+<function>XSelectInput</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Handling_the_Output_Buffer">
+<title>Handling the Output Buffer</title>
+<!-- .XS -->
+<!-- (SN Handling the Output Buffer -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The output buffer is an area used by Xlib to store requests.
+The functions described in this section flush the output buffer
+if the function would block or not return an event.
+That is, all requests residing in the output buffer that
+have not yet been sent are transmitted to the X server.
+These functions differ in the additional tasks they might perform.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To flush the output buffer, use
+<function>XFlush</function>.
+<indexterm significance="preferred"><primary>XFlush</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XFlush</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFlush</function>
+function
+flushes the output buffer.
+Most client applications need not use this function because the output
+buffer is automatically flushed as needed by calls to
+<function>XPending</function>,
+<function>XNextEvent</function>,
+and
+<function>XWindowEvent</function>.
+<indexterm><primary>XPending</primary></indexterm>
+<indexterm><primary>XNextEvent</primary></indexterm>
+<indexterm><primary>XWindowEvent</primary></indexterm>
+Events generated by the server may be enqueued into the library's event queue.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To flush the output buffer and then wait until all requests have been processed,
+use
+<function>XSync</function>.
+<indexterm significance="preferred"><primary>XSync</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSync</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Bool<parameter> discard</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>discard</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether
+<function>XSync</function>
+discards all events on the event queue.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSync</function>
+function
+flushes the output buffer and then waits until all requests have been received
+and processed by the X server.
+Any errors generated must be handled by the error handler.
+For each protocol error received by Xlib,
+<function>XSync</function>
+calls the client application's error handling routine (see section 11.8.2).
+Any events generated by the server are enqueued into the library's
+event queue.
+</para>
+<para>
+<!-- .LP -->
+Finally, if you passed
+<function>False</function>,
+<function>XSync</function>
+does not discard the events in the queue.
+If you passed
+<function>True</function>,
+<function>XSync </function>
+discards all events in the queue,
+including those events that were on the queue before
+<function>XSync</function>
+was called.
+Client applications seldom need to call
+<function>XSync</function>.
+</para>
+</sect1>
+<sect1 id="Event_Queue_Management">
+<title>Event Queue Management</title>
+<!-- .XS -->
+<!-- (SN Event Queue Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib maintains an event queue.
+However, the operating system also may be buffering data
+in its network connection that is not yet read into the event queue.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the number of events in the event queue, use
+<function>XEventsQueued</function>.
+<indexterm significance="preferred"><primary>XEventsQueued</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XEventsQueued</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mode.
+You can pass
+<function>QueuedAlready</function>,
+<function>QueuedAfterFlush</function>,
+or
+<function>QueuedAfterReading</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If mode is
+<function>QueuedAlready</function>,
+<function>XEventsQueued </function>
+returns the number of events
+already in the event queue (and never performs a system call).
+If mode is
+<function>QueuedAfterFlush</function>,
+<function>XEventsQueued</function>
+returns the number of events already in the queue if the number is nonzero.
+If there are no events in the queue,
+<function>XEventsQueued</function>
+flushes the output buffer,
+attempts to read more events out of the application's connection,
+and returns the number read.
+If mode is
+<function>QueuedAfterReading</function>,
+<function>XEventsQueued</function>
+returns the number of events already in the queue if the number is nonzero.
+If there are no events in the queue,
+<function>XEventsQueued</function>
+attempts to read more events out of the application's connection
+without flushing the output buffer and returns the number read.
+</para>
+<para>
+<!-- .LP -->
+<function>XEventsQueued</function>
+always returns immediately without I/O if there are events already in the
+queue.
+<function>XEventsQueued</function>
+with mode
+<function>QueuedAfterFlush</function>
+is identical in behavior to
+<function>XPending</function>.
+<function>XEventsQueued</function>
+with mode
+<function>QueuedAlready</function>
+is identical to the
+<function>XQLength</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the number of events that are pending, use
+<function>XPending</function>.
+<indexterm significance="preferred"><primary>XPending</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XPending</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPending</function>
+function returns the number of events that have been received from the
+X server but have not been removed from the event queue.
+<function>XPending</function>
+is identical to
+<function>XEventsQueued</function>
+with the mode
+<function>QueuedAfterFlush</function>
+specified.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Event_Queue">
+<title>Manipulating the Event Queue</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Event Queue -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that let you manipulate the event queue.
+This section discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Obtain events, in order, and remove them from the queue
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Peek at events in the queue without removing them
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Obtain events that match the event mask or the arbitrary
+predicate procedures that you provide
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Returning_the_Next_Event">
+<title>Returning the Next Event</title>
+<!-- .XS -->
+<!-- (SN Returning the Next Event -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To get the next event and remove it from the queue, use
+<function>XNextEvent</function>.
+<indexterm significance="preferred"><primary>XNextEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XNextEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the next event in the queue.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XNextEvent</function>
+function copies the first event from the event queue into the specified
+<function>XEvent</function>
+structure and then removes it from the queue.
+If the event queue is empty,
+<function>XNextEvent</function>
+flushes the output buffer and blocks until an event is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To peek at the event queue, use
+<function>XPeekEvent</function>.
+<indexterm significance="preferred"><primary>XPeekEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XPeekEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a copy of the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPeekEvent</function>
+function returns the first event from the event queue,
+but it does not remove the event from the queue.
+If the queue is empty,
+<function>XPeekEvent</function>
+flushes the output buffer and blocks until an event is received.
+It then copies the event into the client-supplied
+<function>XEvent</function>
+structure without removing it from the event queue.
+</para>
+</sect2>
+<sect2 id="Selecting_Events_Using_a_Predicate_Procedure">
+<title>Selecting Events Using a Predicate Procedure</title>
+<!-- .XS -->
+<!-- (SN Selecting Events Using a Predicate Procedure -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Each of the functions discussed in this section requires you to
+pass a predicate procedure that determines if an event matches
+what you want.
+Your predicate procedure must decide if the event is useful
+without calling any Xlib functions.
+If the predicate directly or indirectly causes the state of the event queue
+to change, the result is not defined.
+If Xlib has been initialized for threads, the predicate is called with
+the display locked and the result of a call by the predicate to any
+Xlib function that locks the display is not defined unless the caller
+has first called
+<function>XLockDisplay</function>.
+</para>
+<para>
+<!-- .LP -->
+The predicate procedure and its associated arguments are:
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> Bool</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XEvent</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument passed in from the
+<function>XIfEvent</function>,
+<function>XCheckIfEvent</function>,
+or
+<function>XPeekIfEvent </function>
+function.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The predicate procedure is called once for each
+event in the queue until it finds a match.
+After finding a match, the predicate procedure must return
+<function>True</function>.
+If it did not find a match, it must return
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event
+and, if found, remove the event from the queue, use
+<function>XIfEvent</function>.
+<indexterm significance="preferred"><primary>XIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XIfEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+ <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIfEvent</function>
+function completes only when the specified predicate
+procedure returns
+<function>True </function>
+for an event,
+which indicates an event in the queue matches.
+<function>XIfEvent</function>
+flushes the output buffer if it blocks waiting for additional events.
+<function>XIfEvent</function>
+removes the matching event from the queue
+and copies the structure into the client-supplied
+<function>XEvent</function>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event without blocking, use
+<function>XCheckIfEvent</function>.
+<indexterm significance="preferred"><primary>XCheckIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckIfEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+ <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a copy of the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When the predicate procedure finds a match,
+<function>XCheckIfEvent</function>
+copies the matched event into the client-supplied
+<function>XEvent</function>
+structure and returns
+<function>True</function>.
+(This event is removed from the queue.)
+If the predicate procedure finds no match,
+<function>XCheckIfEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+All earlier events stored in the queue are not discarded.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event
+without removing the event from the queue, use
+<function>XPeekIfEvent</function>.
+<indexterm significance="preferred"><primary>XPeekIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XPeekIfEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+ <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a copy of the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPeekIfEvent</function>
+function returns only when the specified predicate
+procedure returns
+<function>True</function>
+for an event.
+After the predicate procedure finds a match,
+<function>XPeekIfEvent</function>
+copies the matched event into the client-supplied
+<function>XEvent</function>
+structure without removing the event from the queue.
+<function>XPeekIfEvent</function>
+flushes the output buffer if it blocks waiting for additional events.
+</para>
+</sect2>
+<sect2 id="Selecting_Events_Using_a_Window_or_Event_Mask">
+<title>Selecting Events Using a Window or Event Mask</title>
+<!-- .XS -->
+<!-- (SN Selecting Events Using a Window or Event Mask -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The functions discussed in this section let you select events by window
+or event types, allowing you to process events out of order.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches both a window and an event mask, use
+<function>XWindowEvent</function>.
+<indexterm significance="preferred"><primary>XWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XWindowEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XWindowEvent</function>
+function searches the event queue for an event that matches both the specified
+window and event mask.
+When it finds a match,
+<function>XWindowEvent</function>
+removes that event from the queue and copies it into the specified
+<function>XEvent</function>
+structure.
+The other events stored in the queue are not discarded.
+If a matching event is not in the queue,
+<function>XWindowEvent</function>
+flushes the output buffer and blocks until one is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches both a window and an event mask (if any),
+use
+<function>XCheckWindowEvent</function>.
+<indexterm><primary>XCheckWindowEvent</primary></indexterm>
+This function is similar to
+<function>XWindowEvent </function>
+except that it never blocks and it returns a
+<function>Bool </function>
+indicating if the event was returned.
+<indexterm significance="preferred"><primary>XCheckWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckWindowEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window (Wi.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckWindowEvent</function>
+function searches the event queue and then the events available
+on the server connection for the first event that matches the specified window
+and event mask.
+If it finds a match,
+<function>XCheckWindowEvent</function>
+removes that event, copies it into the specified
+<function>XEvent</function>
+structure, and returns
+<function>True</function>.
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+<function>XCheckWindowEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches an event mask, use
+<function>XMaskEvent</function>.
+<indexterm significance="preferred"><primary>XMaskEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XMaskEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMaskEvent</function>
+function searches the event queue for the events associated with the
+specified mask.
+When it finds a match,
+<function>XMaskEvent</function>
+removes that event and copies it into the specified
+<function>XEvent</function>
+structure.
+The other events stored in the queue are not discarded.
+If the event you requested is not in the queue,
+<function>XMaskEvent</function>
+flushes the output buffer and blocks until one is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event that matches an event mask (if any), use
+<function>XCheckMaskEvent</function>.
+This function is similar to
+<function>XMaskEvent </function>
+except that it never blocks and it returns a
+<function>Bool </function>
+indicating if the event was returned.
+<indexterm significance="preferred"><primary>XCheckMaskEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckMaskEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckMaskEvent</function>
+function searches the event queue and then any events available on the
+server connection for the first event that matches the specified mask.
+If it finds a match,
+<function>XCheckMaskEvent</function>
+removes that event, copies it into the specified
+<function>XEvent</function>
+structure, and returns
+<function>True</function>.
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+<function>XCheckMaskEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event in the queue that matches an event type, use
+<function>XCheckTypedEvent</function>.
+<indexterm significance="preferred"><primary>XCheckTypedEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckTypedEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> event_type</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type to be compared.
+
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckTypedEvent</function>
+function searches the event queue and then any events available
+on the server connection for the first event that matches the specified type.
+If it finds a match,
+<function>XCheckTypedEvent</function>
+removes that event, copies it into the specified
+<function>XEvent</function>
+structure, and returns
+<function>True</function>.
+The other events in the queue are not discarded.
+If the event is not available,
+<function>XCheckTypedEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event in the queue that matches an event type
+and a window, use
+<function>XCheckTypedWindowEvent</function>.
+<indexterm significance="preferred"><primary>XCheckTypedWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool<function> XCheckTypedWindowEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> event_type</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type to be compared.
+
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the matched event's associated structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckTypedWindowEvent</function>
+function searches the event queue and then any events available
+on the server connection for the first event that matches the specified
+type and window.
+If it finds a match,
+<function>XCheckTypedWindowEvent</function>
+removes the event from the queue, copies it into the specified
+<function>XEvent</function>
+structure, and returns
+<function>True</function>.
+The other events in the queue are not discarded.
+If the event is not available,
+<function>XCheckTypedWindowEvent</function>
+returns
+<function>False</function>,
+and the output buffer will have been flushed.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Putting_an_Event_Back_into_the_Queue">
+<title>Putting an Event Back into the Queue</title>
+<!-- .XS -->
+<!-- (SN Putting an Event Back into the Queue -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To push an event back into the event queue, use
+<function>XPutBackEvent</function>.
+<indexterm significance="preferred"><primary>XPutBackEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XPutBackEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPutBackEvent</function>
+function pushes an event back onto the head of the display's event queue
+by copying the event into the queue.
+This can be useful if you read an event and then decide that you
+would rather deal with it later.
+There is no limit to the number of times in succession that you can call
+<function>XPutBackEvent</function>.
+</para>
+</sect1>
+<sect1 id="Sending_Events_to_Other_Applications">
+<title>Sending Events to Other Applications</title>
+<!-- .XS -->
+<!-- (SN Sending Events to Other Applications -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To send an event to a specified window, use
+<function>XSendEvent</function>.
+<indexterm><primary>XSendEvent</primary></indexterm>
+This function is often used in selection processing.
+For example, the owner of a selection should use
+<function>XSendEvent</function>
+to send a
+<function>SelectionNotify</function>
+event to a requestor when a selection has been converted
+and stored as a property.
+<indexterm significance="preferred"><primary>XSendEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XSendEvent</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Bool<parameter> propagate</parameter></paramdef>
+ <paramdef>long<parameter> event_mask</parameter></paramdef>
+ <paramdef>XEvent<parameter> *event_send</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window the event is to be sent to, or
+<function>PointerWindow</function>,
+or
+<function>InputFocus</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>propagate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_send</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event that is to be sent.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSendEvent</function>
+function identifies the destination window,
+determines which clients should receive the specified events,
+and ignores any active grabs.
+This function requires you to pass an event mask.
+For a discussion of the valid event mask names,
+see section 10.3.
+This function uses the w argument to identify the destination window as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If w is
+<function>PointerWindow</function>,
+the destination window is the window that contains the pointer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If w is
+<function>InputFocus </function>
+and if the focus window contains the pointer,
+the destination window is the window that contains the pointer;
+otherwise, the destination window is the focus window.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To determine which clients should receive the specified events,
+<function>XSendEvent</function>
+uses the propagate argument as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If event_mask is the empty set,
+the event is sent to the client that created the destination window.
+If that client no longer exists,
+no event is sent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If propagate is
+<function>False</function>,
+the event is sent to every client selecting on destination any of the event
+types in the event_mask argument.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If propagate is
+<function>True </function>
+and no clients have selected on destination any of
+the event types in event-mask, the destination is replaced with the
+closest ancestor of destination for which some client has selected a
+type in event-mask and for which no intervening window has that type in its
+do-not-propagate-mask.
+If no such window exists or if the window is
+an ancestor of the focus window and
+<function>InputFocus </function>
+was originally specified
+as the destination, the event is not sent to any clients.
+Otherwise, the event is reported to every client selecting on the final
+destination any of the types specified in event_mask.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The event in the
+<function>XEvent</function>
+structure must be one of the core events or one of the events
+defined by an extension (or a
+<function>BadValue</function>
+error results) so that the X server can correctly byte-swap
+the contents as necessary.
+The contents of the event are
+otherwise unaltered and unchecked by the X server except to force send_event to
+<function>True</function>
+in the forwarded event and to set the serial number in the event correctly;
+therefore these fields
+and the display field are ignored by
+<function>XSendEvent</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XSendEvent</function>
+returns zero if the conversion to wire protocol format failed
+and returns nonzero otherwise.
+</para>
+<para>
+<!-- .LP -->
+<function>XSendEvent</function>
+can generate
+<function>BadValue</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect1>
+<sect1 id="Getting_Pointer_Motion_History">
+<title>Getting Pointer Motion History</title>
+<!-- .XS -->
+<!-- (SN Getting Pointer Motion History -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some X server implementations will maintain a more complete
+history of pointer motion than is reported by event notification.
+The pointer position at each pointer hardware interrupt may be
+stored in a buffer for later retrieval.
+This buffer is called the motion history buffer.
+For example, a few applications, such as paint programs,
+want to have a precise history of where the pointer
+traveled.
+However, this historical information is highly excessive for most applications.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine the approximate maximum number of elements in the motion buffer,
+use
+<function>XDisplayMotionBufferSize</function>.
+<indexterm significance="preferred"><primary>XDisplayMotionBufferSize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned<function> long</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The server may retain the recent history of the pointer motion
+and do so to a finer granularity than is reported by
+<function>MotionNotify</function>
+events.
+The
+<function>XGetMotionEvents</function>
+function makes this history available.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the motion history for a specified window and time, use
+<function>XGetMotionEvents</function>.
+<indexterm significance="preferred"><primary>XGetMotionEvents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XTimeCoord<function> *XGetMotionEvents</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Timestart,<parameter> stop</parameter></paramdef>
+ <paramdef>int<parameter> *nevents_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>start</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>stop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the time interval in which the events are returned from the motion
+history buffer.
+You can pass a timestamp or
+<function>CurrentTime</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nevents_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of events from the motion history buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetMotionEvents</function>
+function returns all events in the motion history buffer that fall between the
+specified start and stop times, inclusive, and that have coordinates
+that lie within the specified window (including its borders) at its present
+placement.
+If the server does not support motion history,
+if the start time is later than the stop time,
+or if the start time is in the future,
+no events are returned;
+<function>XGetMotionEvents</function>
+returns NULL.
+If the stop time is in the future, it is equivalent to specifying
+<function>CurrentTime</function>.
+The return type for this function is a structure defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XTimeCoord</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+ Time time;
+ short x, y;
+} XTimeCoord;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The time member is set to the time, in milliseconds.
+The x and y members are set to the coordinates of the pointer and
+are reported relative to the origin
+of the specified window.
+To free the data returned from this call, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetMotionEvents</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect1>
+<sect1 id="Handling_Protocol_Errors">
+<title>Handling Protocol Errors</title>
+<!-- .XS -->
+<!-- (SN Handling Protocol Errors -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to enable or disable synchronization
+and to use the default error handlers.
+</para>
+<sect2 id="Enabling_or_Disabling_Synchronization">
+<title>Enabling or Disabling Synchronization</title>
+<!-- .XS -->
+<!-- (SN Enabling or Disabling Synchronization -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When debugging X applications,
+it often is very convenient to require Xlib to behave synchronously
+so that errors are reported as they occur.
+The following function lets you disable or enable synchronous behavior.
+Note that graphics may occur 30 or more times more slowly when
+synchronization is enabled.
+<indexterm><primary>_Xdebug</primary></indexterm>
+On <acronym>POSIX</acronym>-conformant systems,
+there is also a global variable
+<function>_Xdebug </function>
+that, if set to nonzero before starting a program under a debugger, will force
+synchronous library behavior.
+</para>
+<para>
+<!-- .LP -->
+After completing their work,
+all Xlib functions that generate protocol requests call what is known as
+an after function.
+<function>XSetAfterFunction</function>
+sets which function is to be called.
+<indexterm significance="preferred"><primary>XSetAfterFunction</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> int</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> (*procedure)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>procedure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The specified procedure is called with only a display pointer.
+<function>XSetAfterFunction</function>
+returns the previous after function.
+</para>
+<para>
+<!-- .LP -->
+To enable or disable synchronization, use
+<function>XSynchronize</function>.
+<indexterm><primary>Debugging</primary><secondary>synchronous mode</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSynchronize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> int</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Bool<parameter> onoff</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>onoff</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether to enable
+or disable synchronization.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSynchronize</function>
+function returns
+the previous after function.
+If onoff is
+<function>True</function>,
+<function>XSynchronize</function>
+turns on synchronous behavior.
+If onoff is
+<function>False</function>,
+<function>XSynchronize </function>
+turns off synchronous behavior.
+</para>
+</sect2>
+<sect2 id="Using_the_Default_Error_Handlers">
+<title>Using the Default Error Handlers</title>
+<!-- .XS -->
+<!-- (SN Using the Default Error Handlers -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Debugging</primary><secondary>error handlers</secondary></indexterm>
+<indexterm><primary>Error</primary><secondary>handlers</secondary></indexterm>
+There are two default error handlers in Xlib:
+one to handle typically fatal conditions (for example,
+the connection to a display server dying because a machine crashed)
+and one to handle protocol errors from the X server.
+These error handlers can be changed to user-supplied routines if you
+prefer your own error handling and can be changed as often as you like.
+If either function is passed a NULL pointer, it will
+reinvoke the default handler.
+The action of the default handlers is to print an explanatory
+message and exit.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the error handler, use
+<function>XSetErrorHandler</function>.
+<indexterm significance="preferred"><primary>XSetErrorHandler</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> *XSetErrorHandler</function></funcdef>
+ <paramdef>int <parameter> *handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the program's supplied error handler.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Xlib generally calls the program's
+supplied error handler whenever an error is received.
+It is not called on
+<function>BadName</function>
+errors from
+<function>OpenFont</function>,
+<function>LookupColor</function>,
+or
+<function>AllocNamedColor</function>
+protocol requests or on
+<function>BadFont</function>
+errors from a
+<function>QueryFont</function>
+protocol request.
+These errors generally are reflected back to the program through the
+procedural interface.
+Because this condition is not assumed to be fatal,
+it is acceptable for your error handler to return;
+the returned value is ignored.
+However, the error handler should not
+call any functions (directly or indirectly) on the display
+that will generate protocol requests or that will look for input events.
+The previous error handler is returned.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XErrorEvent</function>
+structure contains:
+<indexterm><primary>Debugging</primary><secondary>error event</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XErrorEvent</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ int type;
+ Display *display; /* Display the event was read from */
+ unsigned long serial; /* serial number of failed request */
+ unsigned char error_code; /* error code of failed request */
+ unsigned char request_code; /* Major op-code of failed request */
+ unsigned char minor_code; /* Minor op-code of failed request */
+ XID resourceid; /* resource id */
+} XErrorEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Serial Number</primary></indexterm>
+The serial member is the number of requests, starting from one,
+sent over the network connection since it was opened.
+It is the number that was the value of
+<function>NextRequest </function>
+immediately before the failing call was made.
+The request_code member is a protocol request
+of the procedure that failed, as defined in
+< X11/Xproto.h .>
+The following error codes can be returned by the functions described in this
+chapter:
+</para>
+<!-- .br -->
+<!-- .ne 13 -->
+<indexterm><primary>Debugging</primary><secondary>error numbers</secondary></indexterm>
+<indexterm><primary>Error</primary><secondary>codes</secondary></indexterm>
+<!-- .\".CP T 3 -->
+<!-- .\"Error Codes -->
+<indexterm significance="preferred"><primary>BadAccess</primary></indexterm>
+<indexterm significance="preferred"><primary>BadAlloc</primary></indexterm>
+<indexterm significance="preferred"><primary>BadAtom</primary></indexterm>
+<indexterm significance="preferred"><primary>BadColor</primary></indexterm>
+<indexterm significance="preferred"><primary>BadCursor</primary></indexterm>
+<indexterm significance="preferred"><primary>BadDrawable</primary></indexterm>
+<indexterm significance="preferred"><primary>BadFont</primary></indexterm>
+<indexterm significance="preferred"><primary>BadGC</primary></indexterm>
+<indexterm significance="preferred"><primary>BadIDChoice</primary></indexterm>
+<informaltable>
+ <tgroup cols='2' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <thead>
+ <row>
+ <entry>Error Code</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>BadAccess</function></entry>
+ <entry>A client attempts to grab a key/button combination already grabbed
+ by another client.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>A client attempts to free a colormap entry that it had not already allocated
+ or to free an entry in a colormap that was created with all entries writable.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>A client attempts to store into a read-only or unallocated colormap entry.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>A client attempts to modify the access control list from other than the local
+ (or otherwise authorized) host.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>A client attempts to select an event type that another client
+ has already selected.</entry>
+ </row>
+ <row>
+ <entry><function>BadAlloc</function></entry>
+ <entry>The server fails to allocate the requested resource.
+ Note that the explicit listing of
+ <function>BadAlloc</function>
+ errors in requests only covers allocation errors at a very coarse level
+ and is not intended to (nor can it in practice hope to) cover all cases of
+ a server running out of allocation space in the middle of service.
+ The semantics when a server runs out of allocation space are left unspecified,
+ but a server may generate a
+ <function>BadAlloc</function>
+ error on any request for this reason,
+ and clients should be prepared to receive such errors and handle or discard
+ them.</entry>
+ </row>
+ <row>
+ <entry><function>BadAtom</function></entry>
+ <entry>A value for an atom argument does not name a defined atom.</entry>
+ </row>
+ <row>
+ <entry><function>BadColor</function></entry>
+ <entry>A value for a colormap argument does not name a defined colormap.</entry>
+ </row>
+ <row>
+ <entry><function>BadCursor</function></entry>
+ <entry>A value for a cursor argument does not name a defined cursor.</entry>
+ </row>
+ <row>
+ <entry><function>BadDrawable</function></entry>
+ <entry>A value for a drawable argument does not name a defined window or pixmap.</entry>
+ </row>
+ <row>
+ <entry><function>BadFont</function></entry>
+ <entry>A value for a font argument does not name a defined font (or, in some cases,
+ <function>GContext</function>).</entry>
+ </row>
+ <row>
+ <entry><function>BadGC</function></entry>
+ <entry>A value for a
+ <function>GContext </function>
+ argument does not name a defined
+ <function>GContext</function>.</entry>
+ </row>
+ <row>
+ <entry><function>BadIDChoice</function></entry>
+ <entry>The value chosen for a resource identifier either is not included in the
+ range assigned to the client or is already in use.
+ Under normal circumstances,
+ this cannot occur and should be considered a server or Xlib error.</entry>
+ </row>
+ <row>
+ <entry><function>BadImplementation</function></entry>
+ <entry>The server does not implement some aspect of the request.
+ A server that generates this error for a core request is deficient.
+ As such, this error is not listed for any of the requests,
+ but clients should be prepared to receive such errors
+ and handle or discard them.</entry>
+ </row>
+ <row>
+ <entry><function>BadLength</function></entry>
+ <entry>The length of a request is shorter or longer than that required to
+ contain the arguments.
+ This is an internal Xlib or server error.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>
+ The length of a request exceeds the maximum length accepted by the server.</entry>
+ </row>
+ <row>
+ <entry><function>BadMatch</function></entry>
+ <entry>In a graphics request,
+ the root and depth of the graphics context do not match those of the drawable.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>An <function>InputOnly </function> window is used as a drawable.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>
+ Some argument or pair of arguments has the correct type and range,
+ but it fails to match in some other way required by the request.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>An <function>InputOnly </function>
+ window lacks this attribute.</entry>
+ </row>
+ <row>
+ <entry><function>BadName</function></entry>
+ <entry>A font or color of the specified name does not exist.</entry>
+ </row>
+ <row>
+ <entry><function>BadPixmap</function></entry>
+ <entry>A value for a pixmap argument does not name a defined pixmap.</entry>
+ </row>
+ <row>
+ <entry><function>BadRequest</function></entry>
+ <entry>The major or minor opcode does not specify a valid request.
+ This usually is an Xlib or server error.</entry>
+ </row>
+ <row>
+ <entry><function>BadValue</function></entry>
+ <entry>Some numeric value falls outside of the range of values accepted
+ by the request.
+ Unless a specific range is specified for an argument,
+ the full range defined by the argument's type is accepted.
+ Any argument defined as a set of alternatives typically can generate
+ this error (due to the encoding).</entry>
+ </row>
+ <row>
+ <entry><function>BadWindow</function></entry>
+ <entry>A value for a window argument does not name a defined window.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<indexterm significance="preferred"><primary>BadImplementation</primary></indexterm>
+<indexterm significance="preferred"><primary>BadLength</primary></indexterm>
+<indexterm significance="preferred"><primary>BadMatch</primary></indexterm>
+<indexterm significance="preferred"><primary>BadName</primary></indexterm>
+<indexterm significance="preferred"><primary>BadPixmap</primary></indexterm>
+<indexterm significance="preferred"><primary>BadRequest</primary></indexterm>
+<indexterm significance="preferred"><primary>BadValue</primary></indexterm>
+<indexterm significance="preferred"><primary>BadWindow</primary></indexterm>
+<!-- .NT Note -->
+
+<note>
+<para>
+The
+<function>BadAtom</function>,
+<function>BadColor</function>,
+<function>BadCursor</function>,
+<function>BadDrawable</function>,
+<function>BadFont</function>,
+<function>BadGC</function>,
+<function>BadPixmap</function>,
+and
+<function>BadWindow</function>
+errors are also used when the argument type is extended by a set of
+fixed alternatives.
+</para>
+</note>
+
+<!-- .NE -->
+<!-- .sp -->
+<para>
+<!-- .LP -->
+To obtain textual descriptions of the specified error code, use
+<function>XGetErrorText</function>.
+<indexterm significance="preferred"><primary>XGetErrorText</primary></indexterm>
+<indexterm><primary>Debugging</primary><secondary>error message strings</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetErrorText</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> code</parameter></paramdef>
+ <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+ <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>code</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the error code for which you want to obtain a description.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the error description.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetErrorText</function>
+function copies a null-terminated string describing the specified error code
+into the specified buffer.
+The returned text is in the encoding of the current locale.
+It is recommended that you use this function to obtain an error description
+because extensions to Xlib may define their own error codes
+and error strings.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain error messages from the error database, use
+<function>XGetErrorDatabaseText</function>.
+<indexterm significance="preferred"><primary>XGetErrorDatabaseText</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XGetErrorDatabaseText</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char*name,<parameter> *message</parameter></paramdef>
+ <paramdef>char<parameter> *default_string</parameter></paramdef>
+ <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+ <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default_string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default error message if none is found in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the error description.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetErrorDatabaseText</function>
+function returns a null-terminated message
+(or the default message) from the error message
+database.
+Xlib uses this function internally to look up its error messages.
+The text in the default_string argument is assumed
+to be in the encoding of the current locale,
+and the text stored in the buffer_return argument
+is in the encoding of the current locale.
+</para>
+<para>
+<!-- .LP -->
+The name argument should generally be the name of your application.
+The message argument should indicate which type of error message you want.
+If the name and message are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Xlib uses three predefined ``application names'' to report errors.
+In these names,
+uppercase and lowercase matter.
+<variablelist>
+ <varlistentry>
+ <term>
+ XProtoError
+ </term>
+ <listitem>
+ <para>
+The protocol error number is used as a string for the message argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ XlibMessage
+ </term>
+ <listitem>
+ <para>
+These are the message strings that are used internally by the library.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ XRequest
+ </term>
+ <listitem>
+ <para>
+For a core protocol request,
+the major request protocol number is used for the message argument.
+For an extension request,
+the extension name (as given by
+<function>InitExtension</function>)
+followed by a period (\.) and the minor request protocol number
+is used for the message argument.
+If no string is found in the error database,
+the default_string is returned to the buffer argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To report an error to the user when the requested display does not exist, use
+<function>XDisplayName</function>.
+<indexterm significance="preferred"><primary>XDisplayName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char<function> *XDisplayName</function></funcdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the character string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayName</function>
+function returns the name of the display that
+<function>XOpenDisplay</function>
+would attempt to use.
+If a NULL string is specified,
+<function>XDisplayName</function>
+looks in the environment for the display and returns the display name that
+<function>XOpenDisplay</function>
+would attempt to use.
+This makes it easier to report to the user precisely which display the
+program attempted to open when the initial connection attempt failed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To handle fatal I/O errors, use
+<function>XSetIOErrorHandler</function>.
+<indexterm significance="preferred"><primary>XSetIOErrorHandler</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> int</function></funcdef>
+ <paramdef>int(*handler)(Display<parameter> *)</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the program's supplied error handler.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetIOErrorHandler</function>
+sets the fatal I/O error handler.
+Xlib calls the program's supplied error handler if any sort of system call
+error occurs (for example, the connection to the server was lost).
+This is assumed to be a fatal condition,
+and the called routine should not return.
+If the I/O error handler does return,
+the client process exits.
+</para>
+<para>
+<!-- .LP -->
+Note that the previous error handler is returned.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
|