<?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>