diff options
Diffstat (limited to 'libX11/specs/libX11/CH11.xml')
-rw-r--r-- | libX11/specs/libX11/CH11.xml | 5084 |
1 files changed, 2542 insertions, 2542 deletions
diff --git a/libX11/specs/libX11/CH11.xml b/libX11/specs/libX11/CH11.xml index c8031649a..df8a9630a 100644 --- a/libX11/specs/libX11/CH11.xml +++ b/libX11/specs/libX11/CH11.xml @@ -1,2542 +1,2542 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<chapter id="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
-<structname>XSetWindowAttributes</structname>
-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
-<symbol>CirculateRequest</symbol>,
-<symbol>ConfigureRequest</symbol>,
-or
-<symbol>MapRequest</symbol>
-events, which are associated with
-the event mask
-<symbol>SubstructureRedirectMask</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-Only one client at a time can select
-a
-<symbol>ResizeRequest</symbol>
-event, which is associated with
-the event mask
-<symbol>ResizeRedirectMask</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-Only one client at a time can select a
-<symbol>ButtonPress</symbol>
-event, which is associated with
-the event mask
-<symbol>ButtonPressMask</symbol>.
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-The server reports the event to all interested clients.
-</para>
-<para>
-<!-- .LP -->
-<function>XSelectInput</function>
-can generate a
-<errorname>BadWindow</errorname>
-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
-<symbol>False</symbol>,
-<function>XSync</function>
-does not discard the events in the queue.
-If you passed
-<symbol>True</symbol>,
-<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
-<symbol>QueuedAlready</symbol>,
-<symbol>QueuedAfterFlush</symbol>,
-or
-<symbol>QueuedAfterReading</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If mode is
-<symbol>QueuedAlready</symbol>,
-<function>XEventsQueued</function>
-returns the number of events
-already in the event queue (and never performs a system call).
-If mode is
-<symbol>QueuedAfterFlush</symbol>,
-<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
-<symbol>QueuedAfterReading</symbol>,
-<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
-<symbol>QueuedAfterFlush</symbol>
-is identical in behavior to
-<function>XPending</function>.
-<function>XEventsQueued</function>
-with mode
-<symbol>QueuedAlready</symbol>
-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
-<symbol>QueuedAfterFlush</symbol>
-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
-<structname>XEvent</structname>
-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
-<structname>XEvent</structname>
-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><type>Bool</type></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
-<structname>XEvent</structname>
-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
-<symbol>True</symbol>.
-If it did not find a match, it must return
-<symbol>False</symbol>.
-</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
-<symbol>True</symbol>
-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
-<structname>XEvent</structname>
-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
-<structname>XEvent</structname>
-structure and returns
-<symbol>True</symbol>.
-(This event is removed from the queue.)
-If the predicate procedure finds no match,
-<function>XCheckIfEvent</function>
-returns
-<symbol>False</symbol>,
-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
-<symbol>True</symbol>
-for an event.
-After the predicate procedure finds a match,
-<function>XPeekIfEvent</function>
-copies the matched event into the client-supplied
-<structname>XEvent</structname>
-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
-<structname>XEvent</structname>
-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
-<type>Bool</type>
-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
-<structname>XEvent</structname>
-structure, and returns
-<symbol>True</symbol>.
-The other events stored in the queue are not discarded.
-If the event you requested is not available,
-<function>XCheckWindowEvent</function>
-returns
-<symbol>False</symbol>,
-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
-<structname>XEvent</structname>
-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
-<type>Bool</type>
-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
-<structname>XEvent</structname>
-structure, and returns
-<symbol>True</symbol>.
-The other events stored in the queue are not discarded.
-If the event you requested is not available,
-<function>XCheckMaskEvent</function>
-returns
-<symbol>False</symbol>,
-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
-<structname>XEvent</structname>
-structure, and returns
-<symbol>True</symbol>.
-The other events in the queue are not discarded.
-If the event is not available,
-<function>XCheckTypedEvent</function>
-returns
-<symbol>False</symbol>,
-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
-<structname>XEvent</structname>
-structure, and returns
-<symbol>True</symbol>.
-The other events in the queue are not discarded.
-If the event is not available,
-<function>XCheckTypedWindowEvent</function>
-returns
-<symbol>False</symbol>,
-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
-<symbol>SelectionNotify</symbol>
-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
-<symbol>PointerWindow</symbol>,
-or
-<symbol>InputFocus</symbol>.
- </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
-<symbol>PointerWindow</symbol>,
-the destination window is the window that contains the pointer.
- </para>
- </listitem>
- <listitem>
- <para>
-If w is
-<symbol>InputFocus</symbol>
-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
-<symbol>False</symbol>,
-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
-<symbol>True</symbol>
-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
-<symbol>InputFocus</symbol>
-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
-<structname>XEvent</structname>
-structure must be one of the core events or one of the events
-defined by an extension (or a
-<errorname>BadValue</errorname>
-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
-<symbol>True</symbol>
-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
-<errorname>BadValue</errorname>
-and
-<errorname>BadWindow</errorname>
-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 <type>long</type></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
-<symbol>MotionNotify</symbol>
-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
-<symbol>CurrentTime</symbol>.
- </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
-<symbol>CurrentTime</symbol>.
-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
-<errorname>BadWindow</errorname>
-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
-<varname>_Xdebug</varname>
-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><type>int</type></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><type>int</type></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
-<symbol>True</symbol>,
-<function>XSynchronize</function>
-turns on synchronous behavior.
-If onoff is
-<symbol>False</symbol>,
-<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
-<errorname>BadName</errorname>
-errors from
-<systemitem>OpenFont</systemitem>,
-<systemitem>LookupColor</systemitem>,
-or
-<systemitem>AllocNamedColor</systemitem>
-protocol requests or on
-<errorname>BadFont</errorname>
-errors from a
-<systemitem>QueryFont</systemitem>
-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
-<structname>XErrorEvent</structname>
-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><errorname>BadAccess</errorname></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><errorname>BadAlloc</errorname></entry>
- <entry>The server fails to allocate the requested resource.
- Note that the explicit listing of
- <errorname>BadAlloc</errorname>
- 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
- <errorname>BadAlloc</errorname>
- 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><errorname>BadAtom</errorname></entry>
- <entry>A value for an atom argument does not name a defined atom.</entry>
- </row>
- <row>
- <entry><errorname>BadColor</errorname></entry>
- <entry>A value for a colormap argument does not name a defined colormap.</entry>
- </row>
- <row>
- <entry><errorname>BadCursor</errorname></entry>
- <entry>A value for a cursor argument does not name a defined cursor.</entry>
- </row>
- <row>
- <entry><errorname>BadDrawable</errorname></entry>
- <entry>A value for a drawable argument does not name a defined window or pixmap.</entry>
- </row>
- <row>
- <entry><errorname>BadFont</errorname></entry>
- <entry>A value for a font argument does not name a defined font (or, in some cases,
- <type>GContext</type>).</entry>
- </row>
- <row>
- <entry><errorname>BadGC</errorname></entry>
- <entry>A value for a
- <type>GContext</type>
- argument does not name a defined
- <type>GContext</type>.</entry>
- </row>
- <row>
- <entry><errorname>BadIDChoice</errorname></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><errorname>BadImplementation</errorname></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><errorname>BadLength</errorname></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><errorname>BadMatch</errorname></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 <symbol>InputOnly</symbol> 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 <symbol>InputOnly</symbol>
- window lacks this attribute.</entry>
- </row>
- <row>
- <entry><errorname>BadName</errorname></entry>
- <entry>A font or color of the specified name does not exist.</entry>
- </row>
- <row>
- <entry><errorname>BadPixmap</errorname></entry>
- <entry>A value for a pixmap argument does not name a defined pixmap.</entry>
- </row>
- <row>
- <entry><errorname>BadRequest</errorname></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><errorname>BadValue</errorname></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><errorname>BadWindow</errorname></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
-<errorname>BadAtom</errorname>,
-<errorname>BadColor</errorname>,
-<errorname>BadCursor</errorname>,
-<errorname>BadDrawable</errorname>,
-<errorname>BadFont</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadPixmap</errorname>,
-and
-<errorname>BadWindow</errorname>
-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><type>int</type></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>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> +<chapter id="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 +<structname>XSetWindowAttributes</structname> +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 id='xselectinput'> +<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 +<symbol>CirculateRequest</symbol>, +<symbol>ConfigureRequest</symbol>, +or +<symbol>MapRequest</symbol> +events, which are associated with +the event mask +<symbol>SubstructureRedirectMask</symbol>. + </para> + </listitem> + <listitem> + <para> +Only one client at a time can select +a +<symbol>ResizeRequest</symbol> +event, which is associated with +the event mask +<symbol>ResizeRedirectMask</symbol>. + </para> + </listitem> + <listitem> + <para> +Only one client at a time can select a +<symbol>ButtonPress</symbol> +event, which is associated with +the event mask +<symbol>ButtonPressMask</symbol>. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The server reports the event to all interested clients. +</para> +<para> +<!-- .LP --> +<function>XSelectInput</function> +can generate a +<errorname>BadWindow</errorname> +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 id='xflush'> +<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 id='xsync'> +<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 +<symbol>False</symbol>, +<function>XSync</function> +does not discard the events in the queue. +If you passed +<symbol>True</symbol>, +<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 id='xeventsqueued'> +<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 +<symbol>QueuedAlready</symbol>, +<symbol>QueuedAfterFlush</symbol>, +or +<symbol>QueuedAfterReading</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +If mode is +<symbol>QueuedAlready</symbol>, +<function>XEventsQueued</function> +returns the number of events +already in the event queue (and never performs a system call). +If mode is +<symbol>QueuedAfterFlush</symbol>, +<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 +<symbol>QueuedAfterReading</symbol>, +<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 +<symbol>QueuedAfterFlush</symbol> +is identical in behavior to +<function>XPending</function>. +<function>XEventsQueued</function> +with mode +<symbol>QueuedAlready</symbol> +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 id='xpending'> +<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 +<symbol>QueuedAfterFlush</symbol> +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 id='xnextevent'> +<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 +<structname>XEvent</structname> +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 id='xpeekevent'> +<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 +<structname>XEvent</structname> +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><type>Bool</type></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 +<structname>XEvent</structname> +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 +<symbol>True</symbol>. +If it did not find a match, it must return +<symbol>False</symbol>. +</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 id='xifevent'> +<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 +<symbol>True</symbol> +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 +<structname>XEvent</structname> +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 id='xcheckifevent'> +<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 +<structname>XEvent</structname> +structure and returns +<symbol>True</symbol>. +(This event is removed from the queue.) +If the predicate procedure finds no match, +<function>XCheckIfEvent</function> +returns +<symbol>False</symbol>, +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 id='xpeekifevent'> +<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 +<symbol>True</symbol> +for an event. +After the predicate procedure finds a match, +<function>XPeekIfEvent</function> +copies the matched event into the client-supplied +<structname>XEvent</structname> +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 id='xwindowevent'> +<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 +<structname>XEvent</structname> +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 +<type>Bool</type> +indicating if the event was returned. +<indexterm significance="preferred"><primary>XCheckWindowEvent</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xcheckwindowevent'> +<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 +<structname>XEvent</structname> +structure, and returns +<symbol>True</symbol>. +The other events stored in the queue are not discarded. +If the event you requested is not available, +<function>XCheckWindowEvent</function> +returns +<symbol>False</symbol>, +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 id='xmaskevent'> +<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 +<structname>XEvent</structname> +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 +<type>Bool</type> +indicating if the event was returned. +<indexterm significance="preferred"><primary>XCheckMaskEvent</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xcheckmaskevent'> +<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 +<structname>XEvent</structname> +structure, and returns +<symbol>True</symbol>. +The other events stored in the queue are not discarded. +If the event you requested is not available, +<function>XCheckMaskEvent</function> +returns +<symbol>False</symbol>, +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 id='xchecktypedevent'> +<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 +<structname>XEvent</structname> +structure, and returns +<symbol>True</symbol>. +The other events in the queue are not discarded. +If the event is not available, +<function>XCheckTypedEvent</function> +returns +<symbol>False</symbol>, +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 id='xchecktypedwindowevent'> +<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 +<structname>XEvent</structname> +structure, and returns +<symbol>True</symbol>. +The other events in the queue are not discarded. +If the event is not available, +<function>XCheckTypedWindowEvent</function> +returns +<symbol>False</symbol>, +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 id='xputbackevent'> +<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 +<symbol>SelectionNotify</symbol> +event to a requestor when a selection has been converted +and stored as a property. +<indexterm significance="preferred"><primary>XSendEvent</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsendevent'> +<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 +<symbol>PointerWindow</symbol>, +or +<symbol>InputFocus</symbol>. + </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 +<symbol>PointerWindow</symbol>, +the destination window is the window that contains the pointer. + </para> + </listitem> + <listitem> + <para> +If w is +<symbol>InputFocus</symbol> +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 +<symbol>False</symbol>, +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 +<symbol>True</symbol> +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 +<symbol>InputFocus</symbol> +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 +<structname>XEvent</structname> +structure must be one of the core events or one of the events +defined by an extension (or a +<errorname>BadValue</errorname> +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 +<symbol>True</symbol> +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 +<errorname>BadValue</errorname> +and +<errorname>BadWindow</errorname> +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 id='xdisplaymotionbuffersize'> +<funcprototype> + <funcdef>unsigned <type>long</type></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 +<symbol>MotionNotify</symbol> +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 id='xgetmotionevents'> +<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 +<symbol>CurrentTime</symbol>. + </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 +<symbol>CurrentTime</symbol>. +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 +<errorname>BadWindow</errorname> +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 +<varname>_Xdebug</varname> +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 id='xsetafterfunction'> +<funcprototype> + <funcdef><type>int</type></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 id='xsynchronize'> +<funcprototype> + <funcdef><type>int</type></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 +<symbol>True</symbol>, +<function>XSynchronize</function> +turns on synchronous behavior. +If onoff is +<symbol>False</symbol>, +<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 id='xseterrorhandler'> +<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 +<errorname>BadName</errorname> +errors from +<systemitem>OpenFont</systemitem>, +<systemitem>LookupColor</systemitem>, +or +<systemitem>AllocNamedColor</systemitem> +protocol requests or on +<errorname>BadFont</errorname> +errors from a +<systemitem>QueryFont</systemitem> +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 +<structname>XErrorEvent</structname> +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><errorname>BadAccess</errorname></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><errorname>BadAlloc</errorname></entry> + <entry>The server fails to allocate the requested resource. + Note that the explicit listing of + <errorname>BadAlloc</errorname> + 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 + <errorname>BadAlloc</errorname> + 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><errorname>BadAtom</errorname></entry> + <entry>A value for an atom argument does not name a defined atom.</entry> + </row> + <row> + <entry><errorname>BadColor</errorname></entry> + <entry>A value for a colormap argument does not name a defined colormap.</entry> + </row> + <row> + <entry><errorname>BadCursor</errorname></entry> + <entry>A value for a cursor argument does not name a defined cursor.</entry> + </row> + <row> + <entry><errorname>BadDrawable</errorname></entry> + <entry>A value for a drawable argument does not name a defined window or pixmap.</entry> + </row> + <row> + <entry><errorname>BadFont</errorname></entry> + <entry>A value for a font argument does not name a defined font (or, in some cases, + <type>GContext</type>).</entry> + </row> + <row> + <entry><errorname>BadGC</errorname></entry> + <entry>A value for a + <type>GContext</type> + argument does not name a defined + <type>GContext</type>.</entry> + </row> + <row> + <entry><errorname>BadIDChoice</errorname></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><errorname>BadImplementation</errorname></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><errorname>BadLength</errorname></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><errorname>BadMatch</errorname></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 <symbol>InputOnly</symbol> 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 <symbol>InputOnly</symbol> + window lacks this attribute.</entry> + </row> + <row> + <entry><errorname>BadName</errorname></entry> + <entry>A font or color of the specified name does not exist.</entry> + </row> + <row> + <entry><errorname>BadPixmap</errorname></entry> + <entry>A value for a pixmap argument does not name a defined pixmap.</entry> + </row> + <row> + <entry><errorname>BadRequest</errorname></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><errorname>BadValue</errorname></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><errorname>BadWindow</errorname></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 +<errorname>BadAtom</errorname>, +<errorname>BadColor</errorname>, +<errorname>BadCursor</errorname>, +<errorname>BadDrawable</errorname>, +<errorname>BadFont</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadPixmap</errorname>, +and +<errorname>BadWindow</errorname> +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 id='xgeterrortext'> +<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 id='xgeterrordatabasetext'> +<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 id='xdisplayname'> +<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 id='xsetioerrorhandler'> +<funcprototype> + <funcdef><type>int</type></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> |