mirror of
https://gitlab.freedesktop.org/xorg/lib/libx11.git
synced 2026-05-26 13:38:17 +02:00
9dfb0f3c0a
Many of the custom nroff macros (.ds <macro> <contents>) were left
unsubstituted in the nroff->docbook conversion. This substitution
is now performed, via the following perl script:
#! /usr/bin/perl -w -i
use Text::Wrap;
while ($_ = <>) {
while ($_ =~ m/\((\w+)\b/g) {
my $m = $1;
if (exists $macro{$m}) {
$_ =~ s/\($m/$macro{$m}/;
$_ = wrap('', '', $_);
$_ =~ s/[ \t]+$//;
}
}
if ($_ =~ /\<!-- .ds (\w+) (.*) -->/) {
my ($m, $s) = ($1, $2);
$macro{$m} = $s;
while ($macro{$m} =~ /\\\s*$/) {
$macro{$m} =~ s/\\\s*$//ms;
$macro{$m} .= <>;
chomp($macro{$m});
}
$macro{$m} =~ s/\\ / /g;
} else {
print $_;
}
}
Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
2519 lines
72 KiB
XML
2519 lines
72 KiB
XML
<?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
|
|
<xref linkend='XCreateWindow' xrefstyle='select: title'/>
|
|
and
|
|
<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>.
|
|
Another way is to use
|
|
<xref linkend='XSelectInput' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the window whose events you are interested in.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>event_mask</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the event mask.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XSelectInput' xrefstyle='select: title'/>
|
|
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 -->
|
|
<xref linkend='XSelectInput' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XFlush' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XFlush' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XPending' xrefstyle='select: title'/>,
|
|
<xref linkend='XNextEvent' xrefstyle='select: title'/>,
|
|
and
|
|
<xref linkend='XWindowEvent' xrefstyle='select: title'/>.
|
|
<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
|
|
<xref linkend='XSync' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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
|
|
<xref linkend='XSync' xrefstyle='select: title'/>
|
|
discards all events on the event queue.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XSync' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XSync' xrefstyle='select: title'/>
|
|
calls the client application's error handling routine
|
|
(see <link linkend="Using_the_Default_Error_Handlers">section 11.8.2</link>).
|
|
Any events generated by the server are enqueued into the library's
|
|
event queue.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
Finally, if you passed
|
|
<symbol>False</symbol>,
|
|
<xref linkend='XSync' xrefstyle='select: title'/>
|
|
does not discard the events in the queue.
|
|
If you passed
|
|
<symbol>True</symbol>,
|
|
<xref linkend='XSync' xrefstyle='select: title'/>
|
|
discards all events in the queue,
|
|
including those events that were on the queue before
|
|
<xref linkend='XSync' xrefstyle='select: title'/>
|
|
was called.
|
|
Client applications seldom need to call
|
|
<xref linkend='XSync' xrefstyle='select: title'/>.
|
|
</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
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
If mode is
|
|
<symbol>QueuedAlready</symbol>,
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>
|
|
returns the number of events
|
|
already in the event queue (and never performs a system call).
|
|
If mode is
|
|
<symbol>QueuedAfterFlush</symbol>,
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>
|
|
returns the number of events already in the queue if the number is nonzero.
|
|
If there are no events in the queue,
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>
|
|
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>,
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>
|
|
returns the number of events already in the queue if the number is nonzero.
|
|
If there are no events in the queue,
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>
|
|
attempts to read more events out of the application's connection
|
|
without flushing the output buffer and returns the number read.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>
|
|
always returns immediately without I/O if there are events already in the
|
|
queue.
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>
|
|
with mode
|
|
<symbol>QueuedAfterFlush</symbol>
|
|
is identical in behavior to
|
|
<xref linkend='XPending' xrefstyle='select: title'/>.
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>
|
|
with mode
|
|
<symbol>QueuedAlready</symbol>
|
|
is identical to the
|
|
<xref linkend='XQLength' xrefstyle='select: title'/>
|
|
function.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To return the number of events that are pending, use
|
|
<xref linkend='XPending' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XPending' xrefstyle='select: title'/>
|
|
function returns the number of events that have been received from the
|
|
X server but have not been removed from the event queue.
|
|
<xref linkend='XPending' xrefstyle='select: title'/>
|
|
is identical to
|
|
<xref linkend='XEventsQueued' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XNextEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XNextEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XNextEvent' xrefstyle='select: title'/>
|
|
flushes the output buffer and blocks until an event is received.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To peek at the event queue, use
|
|
<xref linkend='XPeekEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XPeekEvent' xrefstyle='select: title'/>
|
|
function returns the first event from the event queue,
|
|
but it does not remove the event from the queue.
|
|
If the queue is empty,
|
|
<xref linkend='XPeekEvent' xrefstyle='select: title'/>
|
|
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:
|
|
</para>
|
|
<!-- .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
|
|
<xref linkend='XIfEvent' xrefstyle='select: title'/>,
|
|
<xref linkend='XCheckIfEvent' xrefstyle='select: title'/>,
|
|
or
|
|
<xref linkend='XPeekIfEvent' xrefstyle='select: title'/>
|
|
function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<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
|
|
<xref linkend='XIfEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XIfEvent' xrefstyle='select: title'/>
|
|
function completes only when the specified predicate
|
|
procedure returns
|
|
<symbol>True</symbol>
|
|
for an event,
|
|
which indicates an event in the queue matches.
|
|
<xref linkend='XIfEvent' xrefstyle='select: title'/>
|
|
flushes the output buffer if it blocks waiting for additional events.
|
|
<xref linkend='XIfEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XCheckIfEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
When the predicate procedure finds a match,
|
|
<xref linkend='XCheckIfEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XCheckIfEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XPeekIfEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XPeekIfEvent' xrefstyle='select: title'/>
|
|
function returns only when the specified predicate
|
|
procedure returns
|
|
<symbol>True</symbol>
|
|
for an event.
|
|
After the predicate procedure finds a match,
|
|
<xref linkend='XPeekIfEvent' xrefstyle='select: title'/>
|
|
copies the matched event into the client-supplied
|
|
<structname>XEvent</structname>
|
|
structure without removing the event from the queue.
|
|
<xref linkend='XPeekIfEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XWindowEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the window whose events you are interested in.
|
|
</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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XWindowEvent' xrefstyle='select: title'/>
|
|
function searches the event queue for an event that matches both the specified
|
|
window and event mask.
|
|
When it finds a match,
|
|
<xref linkend='XWindowEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XWindowEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XCheckWindowEvent' xrefstyle='select: title'/>.
|
|
<indexterm><primary>XCheckWindowEvent</primary></indexterm>
|
|
This function is similar to
|
|
<xref linkend='XWindowEvent' xrefstyle='select: title'/>
|
|
except that it never blocks and it returns a
|
|
<type>Bool</type>
|
|
indicating if the event was returned.
|
|
</para>
|
|
<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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>w</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the window whose events you are interested in.
|
|
</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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XCheckWindowEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XCheckWindowEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XCheckWindowEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XMaskEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XMaskEvent' xrefstyle='select: title'/>
|
|
function searches the event queue for the events associated with the
|
|
specified mask.
|
|
When it finds a match,
|
|
<xref linkend='XMaskEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XMaskEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XCheckMaskEvent' xrefstyle='select: title'/>.
|
|
This function is similar to
|
|
<xref linkend='XMaskEvent' xrefstyle='select: title'/>
|
|
except that it never blocks and it returns a
|
|
<type>Bool</type>
|
|
indicating if the event was returned.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XCheckMaskEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XCheckMaskEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XCheckMaskEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XCheckTypedEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XCheckTypedEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XCheckTypedEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XCheckTypedEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XCheckTypedWindowEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XCheckTypedWindowEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XCheckTypedWindowEvent' xrefstyle='select: title'/>
|
|
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,
|
|
<xref linkend='XCheckTypedWindowEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XPutBackEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XPutBackEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XPutBackEvent' xrefstyle='select: title'/>.
|
|
</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
|
|
<xref linkend='XSendEvent' xrefstyle='select: title'/>.
|
|
<indexterm><primary>XSendEvent</primary></indexterm>
|
|
This function is often used in selection processing.
|
|
For example, the owner of a selection should use
|
|
<xref linkend='XSendEvent' xrefstyle='select: title'/>
|
|
to send a
|
|
<symbol>SelectionNotify</symbol>
|
|
event to a requestor when a selection has been converted
|
|
and stored as a property.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XSendEvent' xrefstyle='select: title'/>
|
|
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 <link linkend="Event_Masks">section 10.3</link>.
|
|
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,
|
|
<xref linkend='XSendEvent' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XSendEvent' xrefstyle='select: title'/>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XSendEvent' xrefstyle='select: title'/>
|
|
returns zero if the conversion to wire protocol format failed
|
|
and returns nonzero otherwise.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XSendEvent' xrefstyle='select: title'/>
|
|
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>.
|
|
</para>
|
|
<indexterm significance="preferred"><primary>XDisplayMotionBufferSize</primary></indexterm>
|
|
<!-- .sM -->
|
|
<funcsynopsis id='XGetMotionEvents'>
|
|
<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>
|
|
<!-- .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
|
|
<xref linkend='XGetMotionEvents' xrefstyle='select: title'/>
|
|
function makes this history available.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .sp -->
|
|
To get the motion history for a specified window and time, use
|
|
<xref linkend='XGetMotionEvents' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGetMotionEvents' xrefstyle='select: title'/>
|
|
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;
|
|
<xref linkend='XGetMotionEvents' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XFree' xrefstyle='select: title'/>.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<xref linkend='XGetMotionEvents' xrefstyle='select: title'/>
|
|
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.
|
|
<xref linkend='XSetAfterFunction' xrefstyle='select: title'/>
|
|
sets which function is to be called.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The specified procedure is called with only a display pointer.
|
|
<xref linkend='XSetAfterFunction' xrefstyle='select: title'/>
|
|
returns the previous after function.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
To enable or disable synchronization, use
|
|
<function>XSynchronize</function>.
|
|
</para>
|
|
<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>
|
|
<!-- .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
|
|
<xref linkend='XSetErrorHandler' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .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
|
|
<filename class="headerfile"><X11/Xproto.h></filename>.
|
|
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 frame='topbot'>
|
|
<?dbfo keep-together="auto" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colname='c1' colwidth='1.0*'/>
|
|
<colspec colname='c2' colwidth='3.5*'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Error Code</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><errorname id='BadAccess'>BadAccess</errorname></entry>
|
|
<entry>
|
|
<para>A client attempts to grab a key/button combination already grabbed
|
|
by another client.</para>
|
|
<para>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.</para>
|
|
<para>A client attempts to store into a read-only or unallocated colormap entry.</para>
|
|
<para>A client attempts to modify the access control list from other than the local
|
|
(or otherwise authorized) host.</para>
|
|
<para>A client attempts to select an event type that another client
|
|
has already selected.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><errorname id='BadAlloc'>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 id='BadAtom'>BadAtom</errorname></entry>
|
|
<entry>A value for an atom argument does not name a defined atom.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><errorname id='BadColor'>BadColor</errorname></entry>
|
|
<entry>A value for a colormap argument does not name a defined colormap.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><errorname id='BadCursor'>BadCursor</errorname></entry>
|
|
<entry>A value for a cursor argument does not name a defined cursor.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><errorname id='BadDrawable'>BadDrawable</errorname></entry>
|
|
<entry>A value for a drawable argument does not name a defined window or pixmap.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><errorname id='BadFont'>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 id='BadGC'>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 id='BadIDChoice'>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 id='BadImplementation'>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 id='BadLength'>BadLength</errorname></entry>
|
|
<entry><para>The length of a request is shorter or longer than that required to
|
|
contain the arguments.
|
|
This is an internal Xlib or server error.</para>
|
|
<para>The length of a request exceeds the maximum length accepted by the server.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><errorname id='BadMatch'>BadMatch</errorname></entry>
|
|
<entry><para>In a graphics request,
|
|
the root and depth of the graphics context do not match those of the drawable.</para>
|
|
<para>An <symbol>InputOnly</symbol> window is used as a drawable.</para>
|
|
<para>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.</para>
|
|
<para>An <symbol>InputOnly</symbol>
|
|
window lacks this attribute.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><errorname id='BadName'>BadName</errorname></entry>
|
|
<entry>A font or color of the specified name does not exist.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><errorname id='BadPixmap'>BadPixmap</errorname></entry>
|
|
<entry>A value for a pixmap argument does not name a defined pixmap.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><errorname id='BadRequest'>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 id='BadValue'>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 id='BadWindow'>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
|
|
<xref linkend='XGetErrorText' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGetErrorText' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XGetErrorDatabaseText' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XGetErrorDatabaseText' xrefstyle='select: title'/>
|
|
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
|
|
<xref linkend='XDisplayName' xrefstyle='select: title'/>.
|
|
</para>
|
|
<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>
|
|
<!-- .LP -->
|
|
<!-- .eM -->
|
|
The
|
|
<xref linkend='XDisplayName' xrefstyle='select: title'/>
|
|
function returns the name of the display that
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
would attempt to use.
|
|
If a NULL string is specified,
|
|
<xref linkend='XDisplayName' xrefstyle='select: title'/>
|
|
looks in the environment for the display and returns the display name that
|
|
<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
|
|
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>.
|
|
</para>
|
|
<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>
|
|
<!-- .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>
|