<?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="events">
<title>Events</title>
<para>
A client application communicates with the X server through the connection you establish with
the XOpenDisplay function. A client application sends requests to the X server over this con-
nection. These requests are made by the Xlib functions that are called in the client application.
Many Xlib functions cause the X server to generate events, and the user’s typing or moving the
pointer can generate events asynchronously. The X server returns events to the client on the same
connection.
</para>
<para>
This chapter discusses the following topics associated with events:
</para>
<itemizedlist>
<listitem><para>Event types</para></listitem>
<listitem><para>Event structures</para></listitem>
<listitem><para>Event masks</para></listitem>
<listitem><para>Event processing</para></listitem>
</itemizedlist>
<para>
Functions for handling events are dealt with in the next chapter.
</para>
<sect1 id="Event_Types">
<title>Event Types</title>
<!-- .XS -->
<!-- (SN Event Types -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Event</primary><secondary>types</secondary></indexterm>
An event is data generated asynchronously by the X server as a result of some
device activity or as side effects of a request sent by an Xlib function.
<indexterm><primary>Event</primary></indexterm>
Device-related events propagate from the source window to ancestor windows
until some client application has selected that event type
or until the event is explicitly discarded.
The X server generally sends an event to a client application
only if the client has specifically asked to be informed of that event type,
typically by setting the event-mask attribute of the window.
The mask can also be set when you create a window
or by changing the window's
event-mask.
You can also mask out events that would propagate to ancestor windows
by manipulating the
do-not-propagate mask of the window's attributes.
However,
<symbol>MappingNotify</symbol>
events are always sent to all clients.
<indexterm><primary>Input Control</primary></indexterm>
<indexterm><primary>Output Control</primary></indexterm>
</para>
<para>
<!-- .LP -->
An event type describes a specific event generated by the X server.
For each event type,
a corresponding constant name is defined in
<filename class="headerfile"><X11/X.h></filename>,
<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
which is used when referring to an event type.
<indexterm><primary>Event</primary><secondary>categories</secondary></indexterm>
The following table lists the event category
and its associated event type or types.
The processing associated with these events is discussed in section 10.5.
</para>
<para>
<!-- .LP -->
<!-- .\".CP T 1 -->
<!-- .\"Event Categories and Event Types -->
</para>
<para>
<!-- .LP -->
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry>Event Category</entry>
<entry>Event Type</entry>
</row>
</thead>
<tbody>
<row>
<entry>Keyboard events</entry>
<entry><symbol>KeyPress</symbol>,
<symbol>KeyRelease</symbol></entry>
</row>
<row>
<entry>Pointer events</entry>
<entry><symbol>ButtonPress</symbol>,
<symbol>ButtonRelease</symbol>,
<symbol>MotionNotify</symbol></entry>
</row>
<row>
<entry>Window crossing events</entry>
<entry><symbol>EnterNotify</symbol>,
<symbol>LeaveNotify</symbol></entry>
</row>
<row>
<entry>Input focus events</entry>
<entry><symbol>FocusIn</symbol>,
<symbol>FocusOut</symbol></entry>
</row>
<row>
<entry>Keymap state notification event</entry>
<entry><symbol>KeymapNotify</symbol></entry>
</row>
<row>
<entry>Exposure events</entry>
<entry><symbol>Expose</symbol>,
<symbol>GraphicsExpose</symbol>,
<symbol>NoExpose</symbol></entry>
</row>
<row>
<entry>Structure control events</entry>
<entry><symbol>CirculateRequest</symbol>,
<symbol>ConfigureRequest</symbol>,
<symbol>MapRequest</symbol>,
<symbol>ResizeRequest</symbol></entry>
</row>
<row>
<entry>Window state notification events</entry>
<entry>
<symbol>CirculateNotify</symbol>,
<symbol>ConfigureNotify</symbol>,
<symbol>CreateNotify</symbol>,
<symbol>DestroyNotify</symbol>,
<symbol>GravityNotify</symbol>,
<symbol>MapNotify</symbol>,
<symbol>MappingNotify</symbol>,
<symbol>ReparentNotify</symbol>,
<symbol>UnmapNotify</symbol>,
<symbol>VisibilityNotify</symbol></entry>
</row>
<row>
<entry>Colormap state notification event</entry>
<entry><symbol>ColormapNotify</symbol></entry>
</row>
<row>
<entry>Client communication events</entry>
<entry><symbol>ClientMessage</symbol>,
<symbol>PropertyNotify</symbol>,
<symbol>SelectionClear</symbol>,
<symbol>SelectionNotify</symbol>,
<symbol>SelectionRequest</symbol></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<!-- .\".LP -->
<!-- .\"Table 8-1 lists the event types and the Xlib functions that could cause -->
<!-- .\"the X server to generate that event type. -->
<!-- .\"The event types are listed alphabetically. -->
<!-- .\"Note that the error event is not listed in this table. -->
<!-- .\"For a list of the constants associated with an error event, see the Handling -->
<!-- .\"Errors section in this chapter. -->
<!-- .\".LP -->
<!-- .\".so eventtable -->
</para>
</sect1>
<sect1 id="Event_Structures">
<title>Event Structures</title>
<!-- .XS -->
<!-- (SN Event Structures -->
<!-- .XE -->
<para>
<!-- .LP -->
For each event type,
a corresponding structure is declared in
<filename class="headerfile"><X11/Xlib.h></filename>.
<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
All the event structures have the following common members:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XAnyEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type;
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
} XAnyEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The type member is set to the event type constant name that uniquely identifies
it.
For example, when the X server reports a
<symbol>GraphicsExpose</symbol>
event to a client application, it sends an
<structname>XGraphicsExposeEvent</structname>
structure with the type member set to
<symbol>GraphicsExpose</symbol>.
The display member is set to a pointer to the display the event was read on.
The send_event member is set to
<symbol>True</symbol>
if the event came from a
<systemitem>SendEvent</systemitem>
protocol request.
The serial member is set from the serial number reported in the protocol
but expanded from the 16-bit least-significant bits to a full 32-bit value.
The window member is set to the window that is most useful to toolkit
dispatchers.
</para>
<para>
<!-- .LP -->
The X server can send events at any time in the input stream.
Xlib stores any events received while waiting for a reply in an event queue
for later use.
Xlib also provides functions that allow you to check events
in the event queue (see section 11.3).
</para>
<para>
<!-- .LP -->
In addition to the individual structures declared for each event type, the
<structname>XEvent</structname>
structure is a union of the individual structures declared for each event type.
Depending on the type,
you should access members of each event by using the
<structname>XEvent</structname>
union.
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XEvent</primary></indexterm>
<!-- .sM -->
</para>
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef union _XEvent {
int type; /* must not be changed */
XAnyEvent xany;
XKeyEvent xkey;
XButtonEvent xbutton;
XMotionEvent xmotion;
XCrossingEvent xcrossing;
XFocusChangeEvent xfocus;
XExposeEvent xexpose;
XGraphicsExposeEvent xgraphicsexpose;
XNoExposeEvent xnoexpose;
XVisibilityEvent xvisibility;
XCreateWindowEvent xcreatewindow;
XDestroyWindowEvent xdestroywindow;
XUnmapEvent xunmap;
XMapEvent xmap;
XMapRequestEvent xmaprequest;
XReparentEvent xreparent;
XConfigureEvent xconfigure;
XGravityEvent xgravity;
XResizeRequestEvent xresizerequest;
XConfigureRequestEvent xconfigurerequest;
XCirculateEvent xcirculate;
XCirculateRequestEvent xcirculaterequest;
XPropertyEvent xproperty;
XSelectionClearEvent xselectionclear;
XSelectionRequestEvent xselectionrequest;
XSelectionEvent xselection;
XColormapEvent xcolormap;
XClientMessageEvent xclient;
XMappingEvent xmapping;
XErrorEvent xerror;
XKeymapEvent xkeymap;
long pad[24];
} XEvent;
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
An
<structname>XEvent</structname>
structure's first entry always is the type member,
which is set to the event type.
The second member always is the serial number of the protocol request
that generated the event.
The third member always is send_event,
which is a
<type>Bool</type>
that indicates if the event was sent by a different client.
The fourth member always is a display,
which is the display that the event was read from.
Except for keymap events,
the fifth member always is a window,
which has been carefully selected to be useful to toolkit dispatchers.
To avoid breaking toolkits,
the order of these first five entries is not to change.
Most events also contain a time member,
which is the time at which an event occurred.
In addition, a pointer to the generic event must be cast before it
is used to access any other information in the structure.
</para>
</sect1>
<sect1 id="Event_Masks">
<title>Event Masks</title>
<!-- .XS -->
<!-- (SN Event Masks -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>Event mask</primary></indexterm>
Clients select event reporting of most events relative to a window.
To do this, pass an event mask to an Xlib event-handling
function that takes an event_mask argument.
The bits of the event mask are defined in
<filename class="headerfile"><X11/X.h></filename>.
<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
Each bit in the event mask maps to an event mask name,
which describes the event or events you want the X server to
return to a client application.
</para>
<para>
<!-- .LP -->
Unless the client has specifically asked for them,
most events are not reported to clients when they are generated.
Unless the client suppresses them by setting graphics-exposures in the GC to
<symbol>False</symbol>,
<symbol>GraphicsExpose</symbol>
and
<symbol>NoExpose</symbol>
are reported by default as a result of
<function>XCopyPlane</function>
and
<function>XCopyArea</function>.
<symbol>SelectionClear</symbol>,
<symbol>SelectionRequest</symbol>,
<symbol>SelectionNotify</symbol>,
or
<symbol>ClientMessage</symbol>
cannot be masked.
Selection-related events are only sent to clients cooperating
with selections (see section 4.5).
When the keyboard or pointer mapping is changed,
<symbol>MappingNotify</symbol>
is always sent to clients.
</para>
<para>
<!-- .LP -->
<!-- .\"Table 8-2 -->
The following table
lists the event mask constants you can pass to
the event_mask argument and
the circumstances in which you would want to specify the
event mask:
</para>
<!-- .LP -->
<!-- .\" .CP T 2 -->
<!-- .\"Event Mask Definitions -->
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry>Event Mask</entry>
<entry>Circumstances</entry>
</row>
</thead>
<tbody>
<row>
<entry><symbol>NoEventMask</symbol></entry>
<entry>No events wanted</entry>
</row>
<row>
<entry><symbol>KeyPressMask</symbol></entry>
<entry>Keyboard down events wanted</entry>
</row>
<row>
<entry><symbol>KeyReleaseMask</symbol></entry>
<entry>Keyboard up events wanted</entry>
</row>
<row>
<entry><symbol>ButtonPressMask</symbol></entry>
<entry>Pointer button down events wanted</entry>
</row>
<row>
<entry><symbol>ButtonReleaseMask</symbol></entry>
<entry>Pointer button up events wanted</entry>
</row>
<row>
<entry><symbol>EnterWindowMask</symbol></entry>
<entry>Pointer window entry events wanted</entry>
</row>
<row>
<entry><symbol>LeaveWindowMask</symbol></entry>
<entry>Pointer window leave events wanted</entry>
</row>
<row>
<entry><symbol>PointerMotionMask</symbol></entry>
<entry>Pointer motion events wanted</entry>
</row>
<row>
<entry><symbol>PointerMotionHintMask</symbol></entry>
<entry>Pointer motion hints wanted</entry>
</row>
<row>
<entry><symbol>Button1MotionMask</symbol></entry>
<entry>Pointer motion while button 1 down</entry>
</row>
<row>
<entry><symbol>Button2MotionMask</symbol></entry>
<entry>Pointer motion while button 2 down</entry>
</row>
<row>
<entry><symbol>Button3MotionMask</symbol></entry>
<entry>Pointer motion while button 3 down</entry>
</row>
<row>
<entry><symbol>Button4MotionMask</symbol></entry>
<entry>Pointer motion while button 4 down</entry>
</row>
<row>
<entry><symbol>Button5MotionMask</symbol></entry>
<entry>Pointer motion while button 5 down</entry>
</row>
<row>
<entry><symbol>ButtonMotionMask</symbol></entry>
<entry>Pointer motion while any button down</entry>
</row>
<row>
<entry><symbol>KeymapStateMask</symbol></entry>
<entry>Keyboard state wanted at window entry and focus in</entry>
</row>
<row>
<entry><symbol>ExposureMask</symbol></entry>
<entry>Any exposure wanted</entry>
</row>
<row>
<entry><symbol>VisibilityChangeMask</symbol></entry>
<entry>Any change in visibility wanted</entry>
</row>
<row>
<entry><symbol>StructureNotifyMask</symbol></entry>
<entry>Any change in window structure wanted</entry>
</row>
<row>
<entry><symbol>ResizeRedirectMask</symbol></entry>
<entry>Redirect resize of this window</entry>
</row>
<row>
<entry><symbol>SubstructureNotifyMask</symbol></entry>
<entry>Substructure notification wanted</entry>
</row>
<row>
<entry><symbol>SubstructureRedirectMask</symbol></entry>
<entry>Redirect structure requests on children</entry>
</row>
<row>
<entry><symbol>FocusChangeMask</symbol></entry>
<entry>Any change in input focus wanted</entry>
</row>
<row>
<entry><symbol>PropertyChangeMask</symbol></entry>
<entry>Any change in property wanted</entry>
</row>
<row>
<entry><symbol>ColormapChangeMask</symbol></entry>
<entry>Any change in colormap wanted</entry>
</row>
<row>
<entry><symbol>OwnerGrabButtonMask</symbol></entry>
<entry>Automatic grabs should activate with owner_events set to True</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
</para>
</sect1>
<sect1 id="Event_Processing_Overview">
<title>Event Processing Overview</title>
<!-- .XS -->
<!-- (SN Event Processing Overview -->
<!-- .XE -->
<para>
<!-- .LP -->
The event reported to a client application during event processing
depends on which event masks you provide as the event-mask attribute
for a window.
For some event masks, there is a one-to-one correspondence between
the event mask constant and the event type constant.
For example, if you pass the event mask
<symbol>ButtonPressMask</symbol>,
the X server sends back only
<symbol>ButtonPress</symbol>
events.
<indexterm><primary>CurrentTime</primary></indexterm>
Most events contain a time member,
which is the time at which an event occurred.
</para>
<para>
<!-- .LP -->
In other cases, one event mask constant can map to several event type constants.
For example, if you pass the event mask
<symbol>SubstructureNotifyMask</symbol>,
the X server can send back
<symbol>CirculateNotify</symbol>,
<symbol>ConfigureNotify</symbol>,
<symbol>CreateNotify</symbol>,
<symbol>DestroyNotify</symbol>,
<symbol>GravityNotify</symbol>,
<symbol>MapNotify</symbol>,
<symbol>ReparentNotify</symbol>,
or
<symbol>UnmapNotify</symbol>
events.
</para>
<para>
<!-- .LP -->
In another case,
two event masks can map to one event type.
For example,
if you pass either
<symbol>PointerMotionMask</symbol>
or
<symbol>ButtonMotionMask</symbol>,
the X server sends back
a
<symbol>MotionNotify</symbol>
event.
</para>
<para>
<!-- .LP -->
The following table
lists the event mask,
its associated event type or types,
and the structure name associated with the event type.
Some of these structures actually are typedefs to a generic structure
that is shared between two event types.
Note that N.A. appears in columns for which the information is not applicable.
</para>
<!-- .LP -->
<!-- .ps 9 -->
<!-- .nr PS 9 -->
<informaltable>
<tgroup cols='4' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<colspec colname='c4'/>
<thead>
<row>
<entry>Event Mask</entry>
<entry>Event Type</entry>
<entry>Structure</entry>
<entry>Generic Structure</entry>
</row>
</thead>
<tbody>
<row>
<entry>ButtonMotionMask</entry>
<entry>MotionNotify</entry>
<entry>XPointerMovedEvent</entry>
<entry>XMotionEvent</entry>
</row>
<row>
<entry>Button1MotionMask</entry>
</row>
<row>
<entry>Button2MotionMask</entry>
</row>
<row>
<entry>Button3MotionMask</entry>
</row>
<row>
<entry>Button4MotionMask</entry>
</row>
<row>
<entry>Button5MotionMask</entry>
</row>
<row>
<entry>ButtonPressMask</entry>
<entry>ButtonPress</entry>
<entry>XButtonPressedEvent</entry>
<entry>XButtonEvent</entry>
</row>
<row>
<entry>ButtonReleaseMask</entry>
<entry>ButtonRelease</entry>
<entry>XButtonReleasedEvent</entry>
<entry>XButtonEvent</entry>
</row>
<row>
<entry>ColormapChangeMask</entry>
<entry>ColormapNotify</entry>
<entry>XColormapEvent</entry>
</row>
<row>
<entry>EnterWindowMask</entry>
<entry>EnterNotify</entry>
<entry>XEnterWindowEvent</entry>
<entry>XCrossingEvent</entry>
</row>
<row>
<entry>LeaveWindowMask</entry>
<entry>LeaveNotify</entry>
<entry>XLeaveWindowEvent</entry>
<entry>XCrossingEvent</entry>
</row>
<row>
<entry>ExposureMask</entry>
<entry>Expose</entry>
<entry>XExposeEvent </entry>
</row>
<row>
<entry>GCGraphicsExposures in GC</entry>
<entry>GraphicsExpose</entry>
<entry>XGraphicsExposeEvent</entry>
</row>
<row>
<entry></entry>
<entry>NoExpose</entry>
<entry>XNoExposeEvent</entry>
</row>
<row>
<entry>FocusChangeMask</entry>
<entry>FocusIn</entry>
<entry>XFocusInEvent</entry>
<entry>XFocusChangeEvent</entry>
</row>
<row>
<entry></entry>
<entry>FocusOut</entry>
<entry>XFocusOutEvent</entry>
<entry>XFocusChangeEvent</entry>
</row>
<row>
<entry>KeymapStateMask</entry>
<entry>KeymapNotify</entry>
<entry>XKeymapEvent</entry>
</row>
<row>
<entry>KeyPressMask</entry>
<entry>KeyPress</entry>
<entry>XKeyPressedEvent</entry>
<entry>XKeyEvent</entry>
</row>
<row>
<entry>KeyReleaseMask</entry>
<entry>KeyRelease</entry>
<entry>XKeyReleasedEvent</entry>
<entry>XKeyEvent</entry>
</row>
<row>
<entry>OwnerGrabButtonMask</entry>
<entry>N.A.</entry>
<entry>N.A.</entry>
</row>
<row>
<entry>PointerMotionMask</entry>
<entry>MotionNotify</entry>
<entry>XPointerMovedEvent</entry>
<entry>XMotionEvent</entry>
</row>
<row>
<entry>PointerMotionHintMask</entry>
<entry>N.A.</entry>
<entry>N.A.</entry>
</row>
<row>
<entry>PropertyChangeMask</entry>
<entry>PropertyNotify</entry>
<entry>XPropertyEvent</entry>
</row>
<row>
<entry>ResizeRedirectMask</entry>
<entry>ResizeRequest</entry>
<entry>XResizeRequestEvent</entry>
</row>
<row>
<entry>StructureNotifyMask</entry>
<entry>CirculateNotify</entry>
<entry>XCirculateEvent</entry>
</row>
<row>
<entry></entry>
<entry>ConfigureNotify</entry>
<entry>XConfigureEvent</entry>
</row>
<row>
<entry></entry>
<entry>DestroyNotify</entry>
<entry>XDestroyWindowEvent</entry>
</row>
<row>
<entry></entry>
<entry>GravityNotify</entry>
<entry>XGravityEvent</entry>
</row>
<row>
<entry></entry>
<entry>MapNotify</entry>
<entry>XMapEvent</entry>
</row>
<row>
<entry></entry>
<entry>ReparentNotify</entry>
<entry>XReparentEvent</entry>
</row>
<row>
<entry></entry>
<entry>UnmapNotify</entry>
<entry>XUnmapEvent</entry>
</row>
<row>
<entry>SubstructureNotifyMask</entry>
<entry>CirculateNotify</entry>
<entry>XCirculateEvent</entry>
</row>
<row>
<entry></entry>
<entry>ConfigureNotify</entry>
<entry>XConfigureEvent</entry>
</row>
<row>
<entry></entry>
<entry>CreateNotify</entry>
<entry>XCreateWindowEvent</entry>
</row>
<row>
<entry></entry>
<entry>DestroyNotify</entry>
<entry>XDestroyWindowEvent</entry>
</row>
<row>
<entry></entry>
<entry>GravityNotify</entry>
<entry>XGravityEvent</entry>
</row>
<row>
<entry></entry>
<entry>MapNotify</entry>
<entry>XMapEvent</entry>
</row>
<row>
<entry></entry>
<entry>ReparentNotify</entry>
<entry>XReparentEvent</entry>
</row>
<row>
<entry></entry>
<entry>UnmapNotify</entry>
<entry>XUnmapEvent</entry>
</row>
<row>
<entry>SubstructureRedirectMask</entry>
<entry>CirculateRequest</entry>
<entry>XCirculateRequestEvent</entry>
</row>
<row>
<entry></entry>
<entry>ConfigureRequest</entry>
<entry>XConfigureRequestEvent</entry>
</row>
<row>
<entry></entry>
<entry>MapRequest</entry>
<entry>XMapRequestEvent</entry>
</row>
<row>
<entry>N.A.</entry>
<entry>ClientMessage</entry>
<entry>XClientMessageEvent</entry>
</row>
<row>
<entry>N.A.</entry>
<entry>MappingNotify</entry>
<entry>XMappingEvent</entry>
</row>
<row>
<entry>N.A.</entry>
<entry>SelectionClear</entry>
<entry>XSelectionClearEvent</entry>
</row>
<row>
<entry>N.A.</entry>
<entry>SelectionNotify</entry>
<entry>XSelectionEvent</entry>
</row>
<row>
<entry>N.A.</entry>
<entry>SelectionRequest</entry>
<entry>XSelectionRequestEvent</entry>
</row>
<row>
<entry>VisibilityChangeMask</entry>
<entry>VisibilityNotify</entry>
<entry>XVisibilityEvent</entry>
</row>
<row>
<entry>_</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
The sections that follow describe the processing that occurs
when you select the different event masks.
The sections are organized according to these processing categories:
</para>
<itemizedlist>
<listitem>
<para>
Keyboard and pointer events
</para>
</listitem>
<listitem>
<para>
Window crossing events
</para>
</listitem>
<listitem>
<para>
Input focus events
</para>
</listitem>
<listitem>
<para>
Keymap state notification events
</para>
</listitem>
<listitem>
<para>
Exposure events
</para>
</listitem>
<listitem>
<para>
Window state notification events
</para>
</listitem>
<listitem>
<para>
Structure control events
</para>
</listitem>
<listitem>
<para>
Colormap state notification events
</para>
</listitem>
<listitem>
<para>
Client communication events
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="Keyboard_and_Pointer_Events">
<title>Keyboard and Pointer Events</title>
<!-- .XS -->
<!-- (SN Keyboard and Pointer Events -->
<!-- .XE -->
<para>
<!-- .LP -->
This section discusses:
</para>
<itemizedlist>
<listitem>
<para>
Pointer button events
</para>
</listitem>
<listitem>
<para>
Keyboard and pointer events
</para>
</listitem>
</itemizedlist>
<sect2 id="Pointer_Button_Events">
<title>Pointer Button Events</title>
<!-- .XS -->
<!-- (SN Pointer Button Events -->
<!-- .XE -->
<para>
<!-- .LP -->
The following describes the event processing that occurs when a pointer button
press is processed with the pointer in some window w and
when no active pointer grab is in progress.
</para>
<para>
<!-- .LP -->
The X server searches the ancestors of w from the root down,
looking for a passive grab to activate.
If no matching passive grab on the button exists,
the X server automatically starts an active grab for the client receiving
the event and sets the last-pointer-grab time to the current server time.
The effect is essentially equivalent to an
<function>XGrabButton</function>
with these client passed arguments:
</para>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry>Argument</entry>
<entry>Value</entry>
</row>
</thead>
<tbody>
<row>
<entry><emphasis remap='I'>w</emphasis></entry>
<entry>The event window </entry>
</row>
<row>
<entry><emphasis remap='I'>event_mask</emphasis></entry>
<entry>The client's selected pointer events on the event window</entry>
</row>
<row>
<entry><emphasis remap='I'>pointer_mode</emphasis></entry>
<entry><symbol>GrabModeAsync</symbol></entry>
</row>
<row>
<entry><emphasis remap='I'>keyboard_mode</emphasis></entry>
<entry><symbol>GrabModeAsync</symbol></entry>
</row>
<row>
<entry><emphasis remap='I'>owner_events</emphasis></entry>
<entry><symbol>True</symbol>,
if the client has selected
<symbol>OwnerGrabButtonMask</symbol>
on the event window,
otherwise
<symbol>False</symbol></entry>
</row>
<row>
<entry><emphasis remap='I'>confine_to</emphasis></entry>
<entry><symbol>None</symbol></entry>
</row>
<row>
<entry><emphasis remap='I'>cursor</emphasis></entry>
<entry><symbol>None</symbol></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
The active grab is automatically terminated when
the logical state of the pointer has all buttons released.
Clients can modify the active grab by calling
<function>XUngrabPointer</function>
and
<function>XChangeActivePointerGrab</function>.
</para>
</sect2>
<sect2 id="Keyboard_and_Pointer_Events_b">
<title>Keyboard and Pointer Events</title>
<!-- .XS -->
<!-- (SN Keyboard and Pointer Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>ButtonPress</secondary></indexterm>
<indexterm><primary>Events</primary><secondary>ButtonRelease</secondary></indexterm>
<indexterm><primary>Events</primary><secondary>KeyPress</secondary></indexterm>
<indexterm><primary>Events</primary><secondary>KeyRelease</secondary></indexterm>
<indexterm><primary>Events</primary><secondary>MotionNotify</secondary></indexterm>
This section discusses the processing that occurs for the
keyboard events
<symbol>KeyPress</symbol>
and
<symbol>KeyRelease</symbol>
and the pointer events
<symbol>ButtonPress</symbol>,
<symbol>ButtonRelease</symbol>,
and
<symbol>MotionNotify</symbol>.
For information about the keyboard event-handling utilities,
see chapter 11.
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>KeyPress</primary></indexterm>
<indexterm significance="preferred"><primary>KeyRelease</primary></indexterm>
The X server reports
<symbol>KeyPress</symbol>
or
<symbol>KeyRelease</symbol>
events to clients wanting information about keys that logically change state.
Note that these events are generated for all keys,
even those mapped to modifier bits.
<indexterm significance="preferred"><primary>ButtonPress</primary></indexterm>
<indexterm significance="preferred"><primary>ButtonRelease</primary></indexterm>
The X server reports
<symbol>ButtonPress</symbol>
or
<symbol>ButtonRelease</symbol>
events to clients wanting information about buttons that logically change state.
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>MotionNotify</primary></indexterm>
The X server reports
<symbol>MotionNotify</symbol>
events to clients wanting information about when the pointer logically moves.
The X server generates this event whenever the pointer is moved
and the pointer motion begins and ends in the window.
The granularity of
<symbol>MotionNotify</symbol>
events is not guaranteed,
but a client that selects this event type is guaranteed
to receive at least one event when the pointer moves and then rests.
</para>
<para>
<!-- .LP -->
The generation of the logical changes lags the physical changes
if device event processing is frozen.
</para>
<para>
<!-- .LP -->
To receive
<symbol>KeyPress</symbol>,
<symbol>KeyRelease</symbol>,
<symbol>ButtonPress</symbol>,
and
<symbol>ButtonRelease</symbol>
events, set
<symbol>KeyPressMask</symbol>,
<symbol>KeyReleaseMask</symbol>,
<symbol>ButtonPressMask</symbol>,
and
<symbol>ButtonReleaseMask</symbol>
bits in the event-mask attribute of the window.
</para>
<para>
<!-- .LP -->
To receive
<symbol>MotionNotify</symbol>
events, set one or more of the following event
masks bits in the event-mask attribute of the window.
</para>
<itemizedlist>
<listitem>
<para>
<symbol>Button1MotionMask</symbol> - <symbol>Button5MotionMask</symbol>
</para>
</listitem>
<listitem>
<para>
The client application receives
<symbol>MotionNotify</symbol>
events only when one or more of the specified buttons is pressed.
</para>
</listitem>
<listitem>
<para>
<symbol>ButtonMotionMask</symbol>
</para>
</listitem>
<listitem>
<para>
The client application receives
<symbol>MotionNotify</symbol>
events only when at least one button is pressed.
</para>
</listitem>
<listitem>
<para>
<symbol>PointerMotionMask</symbol>
</para>
</listitem>
<listitem>
<para>
The client application receives
<symbol>MotionNotify</symbol>
events independent of the state of
the pointer buttons.
</para>
</listitem>
<listitem>
<para>
<symbol>PointerMotionHintMask</symbol>
</para>
</listitem>
<listitem>
<para>
If
<symbol>PointerMotionHintMask</symbol>
is selected in combination with one or more of the above masks,
the X server is free to send only one
<symbol>MotionNotify</symbol>
event (with the is_hint member of the
<type>XPointerMovedEvent</type>
structure set to
<symbol>NotifyHint</symbol>)
to the client for the event window,
until either the key or button state changes,
the pointer leaves the event window, or the client calls
<function>XQueryPointer</function>
or
<function>XGetMotionEvents</function>.
The server still may send
<symbol>MotionNotify</symbol>
events without is_hint set to
<symbol>NotifyHint</symbol>.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
The source of the event is the viewable window that the pointer is in.
The window used by the X server to report these events depends on
the window's position in the window hierarchy
and whether any intervening window prohibits the generation of these events.
Starting with the source window,
the X server searches up the window hierarchy until it locates the first
window specified by a client as having an interest in these events.
If one of the intervening windows has its do-not-propagate-mask
set to prohibit generation of the event type,
the events of those types will be suppressed.
Clients can modify the actual window used for reporting by performing
active grabs and, in the case of keyboard events, by using the focus window.
</para>
<para>
<!-- .LP -->
The structures for these event types contain:
</para>
<literallayout class="monospaced">
typedef struct {
int type; /* ButtonPress or ButtonRelease */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* ``event'' window it is reported relative to */
Window root; /* root window that the event occurred on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* pointer x, y coordinates in event window */
int x_root, y_root; /* coordinates relative to root */
unsigned int state; /* key or button mask */
unsigned int button; /* detail */
Bool same_screen; /* same screen flag */
} XButtonEvent;
typedef XButtonEvent XButtonPressedEvent;
typedef XButtonEvent XButtonReleasedEvent;
</literallayout>
<literallayout class="monospaced">
typedef struct {
int type; /* KeyPress or KeyRelease */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* ``event'' window it is reported relative to */
Window root; /* root window that the event occurred on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* pointer x, y coordinates in event window */
int x_root, y_root; /* coordinates relative to root */
unsigned int state; /* key or button mask */
unsigned int keycode; /* detail */
Bool same_screen; /* same screen flag */
} XKeyEvent;
typedef XKeyEvent XKeyPressedEvent;
typedef XKeyEvent XKeyReleasedEvent;
</literallayout>
<literallayout class="monospaced">
typedef struct {
int type; /* MotionNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* ``event'' window reported relative to */
Window root; /* root window that the event occurred on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* pointer x, y coordinates in event window */
int x_root, y_root; /* coordinates relative to root */
unsigned int state; /* key or button mask */
char is_hint; /* detail */
Bool same_screen; /* same screen flag */
} XMotionEvent;
typedef XMotionEvent XPointerMovedEvent;
</literallayout>
<para>
These structures have the following common members:
window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen.
The window member is set to the window on which the
event was generated and is referred to as the event window.
As long as the conditions previously discussed are met,
this is the window used by the X server to report the event.
The root member is set to the source window's root window.
The x_root and y_root members are set to the pointer's coordinates
relative to the root window's origin at the time of the event.
</para>
<para>
<!-- .LP -->
The same_screen member is set to indicate whether the event
window is on the same screen
as the root window and can be either
<symbol>True</symbol>
or
<symbol>False</symbol>.
If
<symbol>True</symbol>,
the event and root windows are on the same screen.
If
<symbol>False</symbol>,
the event and root windows are not on the same screen.
</para>
<para>
<!-- .LP -->
If the source window is an inferior of the event window,
the subwindow member of the structure is set to the child of the event window
that is the source window or the child of the event window that is
an ancestor of the source window.
Otherwise, the X server sets the subwindow member to
<symbol>None</symbol>.
The time member is set to the time when the event was generated
and is expressed in milliseconds.
</para>
<para>
<!-- .LP -->
If the event window is on the same screen as the root window,
the x and y members
are set to the coordinates relative to the event window's origin.
Otherwise, these members are set to zero.
</para>
<para>
<!-- .LP -->
The state member is set to indicate the logical state of the pointer buttons
and modifier keys just prior to the event,
which is the bitwise inclusive OR of one or more of the
button or modifier key masks:
<symbol>Button1Mask</symbol>,
<symbol>Button2Mask</symbol>,
<symbol>Button3Mask</symbol>,
<symbol>Button4Mask</symbol>,
<symbol>Button5Mask</symbol>,
<symbol>ShiftMask</symbol>,
<symbol>LockMask</symbol>,
<symbol>ControlMask</symbol>,
<symbol>Mod1Mask</symbol>,
<symbol>Mod2Mask</symbol>,
<symbol>Mod3Mask</symbol>,
<symbol>Mod4Mask</symbol>,
and
<symbol>Mod5Mask</symbol>.
</para>
<para>
<!-- .LP -->
Each of these structures also has a member that indicates the detail.
For the
<type>XKeyPressedEvent</type>
and
<type>XKeyReleasedEvent</type>
structures, this member is called a keycode.
It is set to a number that represents a physical key on the keyboard.
The keycode is an arbitrary representation for any key on the keyboard
(see sections 12.7 and 16.1).
</para>
<para>
<!-- .LP -->
For the
<type>XButtonPressedEvent</type>
and
<type>XButtonReleasedEvent</type>
structures, this member is called button.
It represents the pointer button that changed state and can be the
<symbol>Button1</symbol>,
<symbol>Button2</symbol>,
<symbol>Button3</symbol>,
<symbol>Button4</symbol>,
or
<symbol>Button5</symbol>
value.
For the
<type>XPointerMovedEvent</type>
structure, this member is called is_hint.
It can be set to
<symbol>NotifyNormal</symbol>
or
<symbol>NotifyHint</symbol>.
</para>
<para>
<!-- .LP -->
Some of the symbols mentioned in this section have fixed values, as
follows:
</para>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry>Symbol</entry>
<entry>Value</entry>
</row>
</thead>
<tbody>
<row>
<entry><symbol>Button1MotionMask</symbol></entry>
<entry>(1L<<8)</entry>
</row>
<row>
<entry><symbol>Button2MotionMask</symbol></entry>
<entry>(1L<<9)</entry>
</row>
<row>
<entry><symbol>Button3MotionMask</symbol></entry>
<entry>(1L<<10)</entry>
</row>
<row>
<entry><symbol>Button4MotionMask</symbol></entry>
<entry>(1L<<11)</entry>
</row>
<row>
<entry><symbol>Button5MotionMask</symbol></entry>
<entry>(1L<<12)</entry>
</row>
<row>
<entry><symbol>Button1Mask</symbol></entry>
<entry>(1<<8)</entry>
</row>
<row>
<entry><symbol>Button2Mask</symbol></entry>
<entry>(1<<9)</entry>
</row>
<row>
<entry><symbol>Button3Mask</symbol></entry>
<entry>(1<<10)</entry>
</row>
<row>
<entry><symbol>Button4Mask</symbol></entry>
<entry>(1<<11)</entry>
</row>
<row>
<entry><symbol>Button5Mask</symbol></entry>
<entry>(1<<12)</entry>
</row>
<row>
<entry><symbol>ShiftMask</symbol></entry>
<entry>(1<<0)</entry>
</row>
<row>
<entry><symbol>LockMask</symbol></entry>
<entry>(1<<1)</entry>
</row>
<row>
<entry><symbol>ControlMask</symbol></entry>
<entry>(1<<2)</entry>
</row>
<row>
<entry><symbol>Mod1Mask</symbol></entry>
<entry>(1<<3)</entry>
</row>
<row>
<entry><symbol>Mod2Mask</symbol></entry>
<entry>(1<<4)</entry>
</row>
<row>
<entry><symbol>Mod3Mask</symbol></entry>
<entry>(1<<5)</entry>
</row>
<row>
<entry><symbol>Mod4Mask</symbol></entry>
<entry>(1<<6)</entry>
</row>
<row>
<entry><symbol>Mod5Mask</symbol></entry>
<entry>(1<<7)</entry>
</row>
<row>
<entry><symbol>Button1</symbol></entry>
<entry>1</entry>
</row>
<row>
<entry><symbol>Button2</symbol></entry>
<entry>2</entry>
</row>
<row>
<entry><symbol>Button3</symbol></entry>
<entry>3</entry>
</row>
<row>
<entry><symbol>Button4</symbol></entry>
<entry>4</entry>
</row>
<row>
<entry><symbol>Button5</symbol></entry>
<entry>5</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
</sect1>
<sect1 id="Window_Entry_Exit_Events">
<title>Window Entry/Exit Events</title>
<!-- .XS -->
<!-- (SN Window Entry/Exit Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>EnterNotify</secondary></indexterm>
<indexterm><primary>Events</primary><secondary>LeaveNotify</secondary></indexterm>
This section describes the processing that
occurs for the window crossing events
<symbol>EnterNotify</symbol>
and
<symbol>LeaveNotify</symbol>.
<indexterm significance="preferred"><primary>EnterNotify</primary></indexterm>
<indexterm significance="preferred"><primary>LeaveNotify</primary></indexterm>
If a pointer motion or a window hierarchy change causes the
pointer to be in a different window than before, the X server reports
<symbol>EnterNotify</symbol>
or
<symbol>LeaveNotify</symbol>
events to clients who have selected for these events.
All
<symbol>EnterNotify</symbol>
and
<symbol>LeaveNotify</symbol>
events caused by a hierarchy change are
generated after any hierarchy event
(<symbol>UnmapNotify</symbol>,
<symbol>MapNotify</symbol>,
<symbol>ConfigureNotify</symbol>,
<symbol>GravityNotify</symbol>,
<symbol>CirculateNotify</symbol>)
caused by that change;
however, the X protocol does not constrain the ordering of
<symbol>EnterNotify</symbol>
and
<symbol>LeaveNotify</symbol>
events with respect to
<symbol>FocusOut</symbol>,
<symbol>VisibilityNotify</symbol>,
and
<symbol>Expose</symbol>
events.
</para>
<para>
<!-- .LP -->
This contrasts with
<symbol>MotionNotify</symbol>
events, which are also generated when the pointer moves
but only when the pointer motion begins and ends in a single window.
An
<symbol>EnterNotify</symbol>
or
<symbol>LeaveNotify</symbol>
event also can be generated when some client application calls
<function>XGrabPointer</function>
and
<function>XUngrabPointer</function>.
</para>
<para>
<!-- .LP -->
To receive
<symbol>EnterNotify</symbol>
or
<symbol>LeaveNotify</symbol>
events, set the
<symbol>EnterWindowMask</symbol>
or
<symbol>LeaveWindowMask</symbol>
bits of the event-mask attribute of the window.
</para>
<para>
<!-- .LP -->
The structure for these event types contains:
</para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XCrossingEvent</primary></indexterm>
<indexterm significance="preferred"><primary>XEnterWindowEvent</primary></indexterm>
<indexterm significance="preferred"><primary>XLeaveWindowEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* EnterNotify or LeaveNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* ``event'' window reported relative to */
Window root; /* root window that the event occurred on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* pointer x, y coordinates in event window */
int x_root, y_root; /* coordinates relative to root */
int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */
int detail;
/*
* NotifyAncestor, NotifyVirtual, NotifyInferior,
* NotifyNonlinear,NotifyNonlinearVirtual
*/
Bool same_screen; /* same screen flag */
Bool focus; /* boolean focus */
unsigned int state; /* key or button mask */
} XCrossingEvent;
typedef XCrossingEvent XEnterWindowEvent;
typedef XCrossingEvent XLeaveWindowEvent;
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
The window member is set to the window on which the
<symbol>EnterNotify</symbol>
or
<symbol>LeaveNotify</symbol>
event was generated and is referred to as the event window.
This is the window used by the X server to report the event,
and is relative to the root
window on which the event occurred.
The root member is set to the root window of the screen
on which the event occurred.
</para>
<para>
<!-- .LP -->
For a
<symbol>LeaveNotify</symbol>
event,
if a child of the event window contains the initial position of the pointer,
the subwindow component is set to that child.
Otherwise, the X server sets the subwindow member to
<symbol>None</symbol>.
For an
<symbol>EnterNotify</symbol>
event, if a child of the event window contains the final pointer position,
the subwindow component is set to that child or
<symbol>None</symbol>.
</para>
<para>
<!-- .LP -->
The time member is set to the time when the event was generated
and is expressed in milliseconds.
The x and y members are set to the coordinates of the pointer position in
the event window.
This position is always the pointer's final position,
not its initial position.
If the event window is on the same
screen as the root window, x and y are the pointer coordinates
relative to the event window's origin.
Otherwise, x and y are set to zero.
The x_root and y_root members are set to the pointer's coordinates relative to the
root window's origin at the time of the event.
</para>
<para>
<!-- .LP -->
The same_screen member is set to indicate whether the event window is on the same screen
as the root window and can be either
<symbol>True</symbol>
or
<symbol>False</symbol>.
If
<symbol>True</symbol>,
the event and root windows are on the same screen.
If
<symbol>False</symbol>,
the event and root windows are not on the same screen.
</para>
<para>
<!-- .LP -->
The focus member is set to indicate whether the event window is the focus window or an
inferior of the focus window.
The X server can set this member to either
<symbol>True</symbol>
or
<symbol>False</symbol>.
If
<symbol>True</symbol>,
the event window is the focus window or an inferior of the focus window.
If
<symbol>False</symbol>,
the event window is not the focus window or an inferior of the focus window.
</para>
<para>
<!-- .LP -->
The state member is set to indicate the state of the pointer buttons and
modifier keys just prior to the
event.
The X server can set this member to the bitwise inclusive OR of one
or more of the button or modifier key masks:
<symbol>Button1Mask</symbol>,
<symbol>Button2Mask</symbol>,
<symbol>Button3Mask</symbol>,
<symbol>Button4Mask</symbol>,
<symbol>Button5Mask</symbol>,
<symbol>ShiftMask</symbol>,
<symbol>LockMask</symbol>,
<symbol>ControlMask</symbol>,
<symbol>Mod1Mask</symbol>,
<symbol>Mod2Mask</symbol>,
<symbol>Mod3Mask</symbol>,
<symbol>Mod4Mask</symbol>,
<symbol>Mod5Mask</symbol>.
</para>
<para>
<!-- .LP -->
The mode member is set to indicate whether the events are normal events,
pseudo-motion events
when a grab activates, or pseudo-motion events when a grab deactivates.
The X server can set this member to
<symbol>NotifyNormal</symbol>,
<symbol>NotifyGrab</symbol>,
or
<symbol>NotifyUngrab</symbol>.
</para>
<para>
<!-- .LP -->
The detail member is set to indicate the notify detail and can be
<symbol>NotifyAncestor</symbol>,
<symbol>NotifyVirtual</symbol>,
<symbol>NotifyInferior</symbol>,
<symbol>NotifyNonlinear</symbol>,
or
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
<sect2 id="Normal_Entry_Exit_Events">
<title>Normal Entry/Exit Events</title>
<!-- .XS -->
<!-- (SN Normal Entry/Exit Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<symbol>EnterNotify</symbol>
and
<symbol>LeaveNotify</symbol>
events are generated when the pointer moves from
one window to another window.
Normal events are identified by
<type>XEnterWindowEvent</type>
or
<type>XLeaveWindowEvent</type>
structures whose mode member is set to
<symbol>NotifyNormal</symbol>.
</para>
<itemizedlist>
<listitem>
<para>
When the pointer moves from window A to window B and A is an inferior of B,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>LeaveNotify</symbol>
event on window A, with the detail member of the
<type>XLeaveWindowEvent</type>
structure set to
<symbol>NotifyAncestor</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>LeaveNotify</symbol>
event on each window between window A and window B, exclusive,
with the detail member of each
<type>XLeaveWindowEvent</type>
structure set to
<symbol>NotifyVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates an
<symbol>EnterNotify</symbol>
event on window B, with the detail member of the
<type>XEnterWindowEvent</type>
structure set to
<symbol>NotifyInferior</symbol>.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When the pointer moves from window A to window B and B is an inferior of A,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>LeaveNotify</symbol>
event on window A,
with the detail member of the
<type>XLeaveWindowEvent</type>
structure set to
<symbol>NotifyInferior</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates an
<symbol>EnterNotify</symbol>
event on each window between window A and window B, exclusive, with the
detail member of each
<type>XEnterWindowEvent</type>
structure set to
<symbol>NotifyVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates an
<symbol>EnterNotify</symbol>
event on window B, with the detail member of the
<type>XEnterWindowEvent</type>
structure set to
<symbol>NotifyAncestor</symbol>.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When the pointer moves from window A to window B
and window C is their least common ancestor,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>LeaveNotify</symbol>
event on window A,
with the detail member of the
<type>XLeaveWindowEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>LeaveNotify</symbol>
event on each window between window A and window C, exclusive,
with the detail member of each
<type>XLeaveWindowEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates an
<symbol>EnterNotify</symbol>
event on each window between window C and window B, exclusive,
with the detail member of each
<type>XEnterWindowEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates an
<symbol>EnterNotify</symbol>
event on window B, with the detail member of the
<type>XEnterWindowEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When the pointer moves from window A to window B on different screens,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>LeaveNotify</symbol>
event on window A,
with the detail member of the
<type>XLeaveWindowEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
</para>
</listitem>
<listitem>
<para>
If window A is not a root window,
it generates a
<symbol>LeaveNotify</symbol>
event on each window above window A up to and including its root,
with the detail member of each
<type>XLeaveWindowEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
If window B is not a root window,
it generates an
<symbol>EnterNotify</symbol>
event on each window from window B's root down to but not including
window B, with the detail member of each
<type>XEnterWindowEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates an
<symbol>EnterNotify</symbol>
event on window B, with the detail member of the
<type>XEnterWindowEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
<!-- .RE -->
<!-- .\".SH 3 -->
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="Grab_and_Ungrab_Entry_Exit_Events">
<title>Grab and Ungrab Entry/Exit Events</title>
<!-- .XS -->
<!-- (SN Grab and Ungrab Entry/Exit Events -->
<!-- .XE -->
<para>
<!-- .LP -->
Pseudo-motion mode
<symbol>EnterNotify</symbol>
and
<symbol>LeaveNotify</symbol>
events are generated when a pointer grab activates or deactivates.
Events in which the pointer grab activates
are identified by
<type>XEnterWindowEvent</type>
or
<type>XLeaveWindowEvent</type>
structures whose mode member is set to
<symbol>NotifyGrab</symbol>.
Events in which the pointer grab deactivates
are identified by
<type>XEnterWindowEvent</type>
or
<type>XLeaveWindowEvent</type>
structures whose mode member is set to
<symbol>NotifyUngrab</symbol>
(see
<function>XGrabPointer</function>).
</para>
<itemizedlist>
<listitem>
<para>
When a pointer grab activates after any initial warp into a confine_to
window and before generating any actual
<symbol>ButtonPress</symbol>
event that activates the grab,
G is the grab_window for the grab,
and P is the window the pointer is in,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
It generates
<symbol>EnterNotify</symbol>
and
<symbol>LeaveNotify</symbol>
events (see section 10.6.1)
with the mode members of the
<type>XEnterWindowEvent</type>
and
<type>XLeaveWindowEvent</type>
structures set to
<symbol>NotifyGrab</symbol>.
These events are generated
as if the pointer were to suddenly warp from
its current position in P to some position in G.
However, the pointer does not warp, and the X server uses the pointer position
as both the initial and final positions for the events.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When a pointer grab deactivates after generating any actual
<symbol>ButtonRelease</symbol>
event that deactivates the grab,
G is the grab_window for the grab,
and P is the window the pointer is in,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
It generates
<symbol>EnterNotify</symbol>
and
<symbol>LeaveNotify</symbol>
events (see section 10.6.1)
with the mode members of the
<type>XEnterWindowEvent</type>
and
<type>XLeaveWindowEvent</type>
structures set to
<symbol>NotifyUngrab</symbol>.
These events are generated as if the pointer were to suddenly warp from
some position in G to its current position in P.
However, the pointer does not warp, and the X server uses the
current pointer position as both the
initial and final positions for the events.
<!-- .RE -->
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="Input_Focus_Events">
<title>Input Focus Events</title>
<!-- .XS -->
<!-- (SN Input Focus Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>FocusIn</secondary></indexterm>
<indexterm><primary>Events</primary><secondary>FocusOut</secondary></indexterm>
This section describes the processing that occurs for the input focus events
<symbol>FocusIn</symbol>
and
<symbol>FocusOut</symbol>.
<indexterm significance="preferred"><primary>FocusIn</primary></indexterm>
<indexterm significance="preferred"><primary>FocusOut</primary></indexterm>
The X server can report
<symbol>FocusIn</symbol>
or
<symbol>FocusOut</symbol>
events to clients wanting information about when the input focus changes.
The keyboard is always attached to some window
(typically, the root window or a top-level window),
which is called the focus window.
The focus window and the position of the pointer determine the window that
receives keyboard input.
Clients may need to know when the input focus changes
to control highlighting of areas on the screen.
</para>
<para>
<!-- .LP -->
To receive
<symbol>FocusIn</symbol>
or
<symbol>FocusOut</symbol>
events, set the
<symbol>FocusChangeMask</symbol>
bit in the event-mask attribute of the window.
</para>
<para>
<!-- .LP -->
The structure for these event types contains:
</para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XFocusChangeEvent</primary></indexterm>
<indexterm significance="preferred"><primary>XFocusInEvent</primary></indexterm>
<indexterm significance="preferred"><primary>XFocusOutEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* FocusIn or FocusOut */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* window of event */
int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */
int detail;
/*
* NotifyAncestor, NotifyVirtual, NotifyInferior,
* NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
* NotifyPointerRoot, NotifyDetailNone
*/
} XFocusChangeEvent;
typedef XFocusChangeEvent XFocusInEvent;
typedef XFocusChangeEvent XFocusOutEvent;
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
The window member is set to the window on which the
<symbol>FocusIn</symbol>
or
<symbol>FocusOut</symbol>
event was generated.
This is the window used by the X server to report the event.
The mode member is set to indicate whether the focus events
are normal focus events,
focus events while grabbed,
focus events
when a grab activates, or focus events when a grab deactivates.
The X server can set the mode member to
<symbol>NotifyNormal</symbol>,
<symbol>NotifyWhileGrabbed</symbol>,
<symbol>NotifyGrab</symbol>,
or
<symbol>NotifyUngrab</symbol>.
</para>
<para>
<!-- .LP -->
All
<symbol>FocusOut</symbol>
events caused by a window unmap are generated after any
<symbol>UnmapNotify</symbol>
event; however, the X protocol does not constrain the ordering of
<symbol>FocusOut</symbol>
events with respect to
generated
<symbol>EnterNotify</symbol>,
<symbol>LeaveNotify</symbol>,
<symbol>VisibilityNotify</symbol>,
and
<symbol>Expose</symbol>
events.
</para>
<para>
<!-- .LP -->
Depending on the event mode,
the detail member is set to indicate the notify detail and can be
<symbol>NotifyAncestor</symbol>,
<symbol>NotifyVirtual</symbol>,
<symbol>NotifyInferior</symbol>,
<symbol>NotifyNonlinear</symbol>,
<symbol>NotifyNonlinearVirtual</symbol>,
<symbol>NotifyPointer</symbol>,
<symbol>NotifyPointerRoot</symbol>,
or
<symbol>NotifyDetailNone</symbol>.
</para>
<sect2 id="Normal_Focus_Events_and_Focus_Events_While_Grabbed_">
<title>Normal Focus Events and Focus Events While Grabbed </title>
<!-- .XS -->
<!-- (SN Normal Focus Events and Focus Events While Grabbed -->
<!-- .XE -->
<para>
<!-- .LP -->
Normal focus events are identified by
<type>XFocusInEvent</type>
or
<type>XFocusOutEvent</type>
structures whose mode member is set to
<symbol>NotifyNormal</symbol>.
Focus events while grabbed are identified by
<type>XFocusInEvent</type>
or
<type>XFocusOutEvent</type>
structures whose mode member is set to
<symbol>NotifyWhileGrabbed</symbol>.
The X server processes normal focus and focus events while grabbed according to
the following:
</para>
<itemizedlist>
<listitem>
<para>
When the focus moves from window A to window B, A is an inferior of B,
and the pointer is in window P,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusOut</symbol>
event on window A, with the detail member of the
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyAncestor</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusOut</symbol>
event on each window between window A and window B, exclusive,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusIn</symbol>
event on window B, with the detail member of the
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyInferior</symbol>.
</para>
</listitem>
<listitem>
<para>
If window P is an inferior of window B
but window P is not window A or an inferior or ancestor of window A,
it generates a
<symbol>FocusIn</symbol>
event on each window below window B, down to and including window P,
with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When the focus moves from window A to window B, B is an inferior of A,
and the pointer is in window P,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
If window P is an inferior of window A
but P is not an inferior of window B or an ancestor of B,
it generates a
<symbol>FocusOut</symbol>
event on each window from window P up to but not including window A,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusOut</symbol>
event on window A,
with the detail member of the
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyInferior</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusIn</symbol>
event on each window between window A and window B, exclusive, with the
detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusIn</symbol>
event on window B, with the detail member of the
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyAncestor</symbol>.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When the focus moves from window A to window B,
window C is their least common ancestor,
and the pointer is in window P,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
If window P is an inferior of window A,
it generates a
<symbol>FocusOut</symbol>
event on each window from window P up to but not including window A,
with the detail member of the
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusOut</symbol>
event on window A,
with the detail member of the
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusOut</symbol>
event on each window between window A and window C, exclusive,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusIn</symbol>
event on each window between C and B, exclusive,
with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusIn</symbol>
event on window B, with the detail member of the
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
</para>
</listitem>
<listitem>
<para>
If window P is an inferior of window B, it generates a
<symbol>FocusIn</symbol>
event on each window below window B down to and including window P,
with the detail member of the
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When the focus moves from window A to window B on different screens
and the pointer is in window P,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
If window P is an inferior of window A, it generates a
<symbol>FocusOut</symbol>
event on each window from window P up to but not including window A,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusOut</symbol>
event on window A,
with the detail member of the
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
</para>
</listitem>
<listitem>
<para>
If window A is not a root window,
it generates a
<symbol>FocusOut</symbol>
event on each window above window A up to and including its root,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
If window B is not a root window,
it generates a
<symbol>FocusIn</symbol>
event on each window from window B's root down to but not including
window B, with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusIn</symbol>
event on window B, with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
</para>
</listitem>
<listitem>
<para>
If window P is an inferior of window B, it generates a
<symbol>FocusIn</symbol>
event on each window below window B down to and including window P,
with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When the focus moves from window A to
<symbol>PointerRoot</symbol>
(events sent to the window under the pointer)
or
<symbol>None</symbol>
(discard), and the pointer is in window P,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
If window P is an inferior of window A, it generates a
<symbol>FocusOut</symbol>
event on each window from window P up to but not including window A,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusOut</symbol>
event on window A, with the detail member of the
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
</para>
</listitem>
<listitem>
<para>
If window A is not a root window,
it generates a
<symbol>FocusOut</symbol>
event on each window above window A up to and including its root,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusIn</symbol>
event on the root window of all screens, with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyPointerRoot</symbol>
(or
<symbol>NotifyDetailNone</symbol>).
</para>
</listitem>
<listitem>
<para>
If the new focus is
<symbol>PointerRoot</symbol>,
it generates a
<symbol>FocusIn</symbol>
event on each window from window P's root down to and including window P,
with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When the focus moves from
<symbol>PointerRoot</symbol>
(events sent to the window under the pointer)
or
<symbol>None</symbol>
to window A, and the pointer is in window P,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
If the old focus is
<symbol>PointerRoot</symbol>,
it generates a
<symbol>FocusOut</symbol>
event on each window from window P up to and including window P's root,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusOut</symbol>
event on all root windows,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyPointerRoot</symbol>
(or
<symbol>NotifyDetailNone</symbol>).
</para>
</listitem>
<listitem>
<para>
If window A is not a root window,
it generates a
<symbol>FocusIn</symbol>
event on each window from window A's root down to but not including window A,
with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyNonlinearVirtual</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusIn</symbol>
event on window A,
with the detail member of the
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyNonlinear</symbol>.
</para>
</listitem>
<listitem>
<para>
If window P is an inferior of window A, it generates a
<symbol>FocusIn</symbol>
event on each window below window A down to and including window P,
with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When the focus moves from
<symbol>PointerRoot</symbol>
(events sent to the window under the pointer)
to
<symbol>None</symbol>
(or vice versa), and the pointer is in window P,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
If the old focus is
<symbol>PointerRoot</symbol>,
it generates a
<symbol>FocusOut</symbol>
event on each window from window P up to and including window P's root,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusOut</symbol>
event on all root windows,
with the detail member of each
<type>XFocusOutEvent</type>
structure set to either
<symbol>NotifyPointerRoot</symbol>
or
<symbol>NotifyDetailNone</symbol>.
</para>
</listitem>
<listitem>
<para>
It generates a
<symbol>FocusIn</symbol>
event on all root windows,
with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyDetailNone</symbol>
or
<symbol>NotifyPointerRoot</symbol>.
</para>
</listitem>
<listitem>
<para>
If the new focus is
<symbol>PointerRoot</symbol>,
it generates a
<symbol>FocusIn</symbol>
event on each window from window P's root down to and including window P,
with the detail member of each
<type>XFocusInEvent</type>
structure set to
<symbol>NotifyPointer</symbol>.
<!-- .RE -->
<!-- .\".SH 3 -->
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="Focus_Events_Generated_by_Grabs">
<title>Focus Events Generated by Grabs</title>
<!-- .XS -->
<!-- (SN Focus Events Generated by Grabs -->
<!-- .XE -->
<para>
<!-- .LP -->
Focus events in which the keyboard grab activates
are identified by
<type>XFocusInEvent</type>
or
<type>XFocusOutEvent</type>
structures whose mode member is set to
<symbol>NotifyGrab</symbol>.
Focus events in which the keyboard grab deactivates
are identified by
<type>XFocusInEvent</type>
or
<type>XFocusOutEvent</type>
structures whose mode member is set to
<symbol>NotifyUngrab</symbol>
(see
<function>XGrabKeyboard</function>).
</para>
<itemizedlist>
<listitem>
<para>
When a keyboard grab activates before generating any actual
<symbol>KeyPress</symbol>
event that activates the grab,
G is the grab_window, and F is the current focus,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
It generates
<symbol>FocusIn</symbol>
and
<symbol>FocusOut</symbol>
events, with the mode members of the
<type>XFocusInEvent</type>
and
<type>XFocusOutEvent</type>
structures set to
<symbol>NotifyGrab</symbol>.
These events are generated
as if the focus were to change from
F to G.
<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
When a keyboard grab deactivates after generating any actual
<symbol>KeyRelease</symbol>
event that deactivates the grab,
G is the grab_window, and F is the current focus,
the X server does the following:
<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
It generates
<symbol>FocusIn</symbol>
and
<symbol>FocusOut</symbol>
events, with the mode members of the
<type>XFocusInEvent</type>
and
<type>XFocusOutEvent</type>
structures set to
<symbol>NotifyUngrab</symbol>.
These events are generated
as if the focus were to change from
G to F.
<!-- .RE -->
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="Key_Map_State_Notification_Events">
<title>Key Map State Notification Events</title>
<!-- .XS -->
<!-- (SN Key Map State Notification Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>KeymapNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>KeymapNotify</primary></indexterm>
The X server can report
<symbol>KeymapNotify</symbol>
events to clients that want information about changes in their keyboard state.
</para>
<para>
<!-- .LP -->
To receive
<symbol>KeymapNotify</symbol>
events, set the
<symbol>KeymapStateMask</symbol>
bit in the event-mask attribute of the window.
The X server generates this event immediately after every
<symbol>EnterNotify</symbol>
and
<symbol>FocusIn</symbol>
event.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XKeymapEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
/* generated on EnterWindow and FocusIn when KeymapState selected */
typedef struct {
int type; /* KeymapNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
char key_vector[32];
} XKeymapEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The window member is not used but is present to aid some toolkits.
The key_vector member is set to the bit vector of the keyboard.
Each bit set to 1 indicates that the corresponding key
is currently pressed.
The vector is represented as 32 bytes.
Byte N (from 0) contains the bits for keys 8N to 8N + 7
with the least significant bit in the byte representing key 8N.
</para>
</sect1>
<sect1 id="Exposure_Events">
<title>Exposure Events</title>
<!-- .XS -->
<!-- (SN Exposure Events -->
<!-- .XE -->
<para>
<!-- .LP -->
The X protocol does not guarantee to preserve the contents of window
regions when
the windows are obscured or reconfigured.
Some implementations may preserve the contents of windows.
Other implementations are free to destroy the contents of windows
when exposed.
X expects client applications to assume the responsibility for
restoring the contents of an exposed window region.
(An exposed window region describes a formerly obscured window whose
region becomes visible.)
Therefore, the X server sends
<symbol>Expose</symbol>
events describing the window and the region of the window that has been exposed.
A naive client application usually redraws the entire window.
A more sophisticated client application redraws only the exposed region.
</para>
<sect2 id="Expose_Events">
<title>Expose Events</title>
<!-- .XS -->
<!-- (SN Expose Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>Expose</secondary></indexterm>
<indexterm significance="preferred"><primary>Expose</primary></indexterm>
The X server can report
<symbol>Expose</symbol>
events to clients wanting information about when the contents of window regions
have been lost.
The circumstances in which the X server generates
<symbol>Expose</symbol>
events are not as definite as those for other events.
However, the X server never generates
<symbol>Expose</symbol>
events on windows whose class you specified as
<symbol>InputOnly</symbol>.
The X server can generate
<symbol>Expose</symbol>
events when no valid contents are available for regions of a window
and either the regions are visible,
the regions are viewable and the server is (perhaps newly) maintaining
backing store on the window,
or the window is not viewable but the server is (perhaps newly) honoring the
window's backing-store attribute of
<symbol>Always</symbol>
or
<symbol>WhenMapped</symbol>.
The regions decompose into an (arbitrary) set of rectangles,
and an
<symbol>Expose</symbol>
event is generated for each rectangle.
For any given window,
the X server guarantees to report contiguously
all of the regions exposed by some action that causes
<symbol>Expose</symbol>
events, such as raising a window.
</para>
<para>
<!-- .LP -->
To receive
<symbol>Expose</symbol>
events, set the
<symbol>ExposureMask</symbol>
bit in the event-mask attribute of the window.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XExposeEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* Expose */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
int x, y;
int width, height;
int count; /* if nonzero, at least this many more */
} XExposeEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The window member is set to the exposed (damaged) window.
The x and y members are set to the coordinates relative to the window's origin
and indicate the upper-left corner of the rectangle.
The width and height members are set to the size (extent) of the rectangle.
The count member is set to the number of
<symbol>Expose</symbol>
events that are to follow.
If count is zero, no more
<symbol>Expose</symbol>
events follow for this window.
However, if count is nonzero, at least that number of
<symbol>Expose</symbol>
events (and possibly more) follow for this window.
Simple applications that do not want to optimize redisplay by distinguishing
between subareas of its window can just ignore all
<symbol>Expose</symbol>
events with nonzero counts and perform full redisplays
on events with zero counts.
</para>
</sect2>
<sect2 id="GraphicsExpose_and_NoExpose_Events">
<title>GraphicsExpose and NoExpose Events</title>
<!-- .XS -->
<!-- (SN GraphicsExpose and NoExpose Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>GraphicsExpose</secondary></indexterm>
<indexterm><primary>Events</primary><secondary>NoExpose</secondary></indexterm>
<indexterm significance="preferred"><primary>GraphicsExpose</primary></indexterm>
The X server can report
<symbol>GraphicsExpose</symbol>
events to clients wanting information about when a destination region could not
be computed during certain graphics requests:
<function>XCopyArea</function>
or
<function>XCopyPlane</function>.
The X server generates this event whenever a destination region could not be
computed because of an obscured or out-of-bounds source region.
In addition, the X server guarantees to report contiguously all of the regions exposed by
some graphics request
(for example, copying an area of a drawable to a destination
drawable).
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>NoExpose</primary></indexterm>
The X server generates a
<symbol>NoExpose</symbol>
event whenever a graphics request that might
produce a
<symbol>GraphicsExpose</symbol>
event does not produce any.
In other words, the client is really asking for a
<symbol>GraphicsExpose</symbol>
event but instead receives a
<symbol>NoExpose</symbol>
event.
</para>
<para>
<!-- .LP -->
To receive
<symbol>GraphicsExpose</symbol>
or
<symbol>NoExpose</symbol>
events, you must first set the graphics-exposure
attribute of the graphics context to
<symbol>True</symbol>.
You also can set the graphics-expose attribute when creating a graphics
context using
<function>XCreateGC</function>
or by calling
<function>XSetGraphicsExposures</function>.
</para>
<para>
<!-- .LP -->
The structures for these event types contain:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XGraphicsExposeEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* GraphicsExpose */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Drawable drawable;
int x, y;
int width, height;
int count; /* if nonzero, at least this many more */
int major_code; /* core is CopyArea or CopyPlane */
int minor_code; /* not defined in the core */
} XGraphicsExposeEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNoExposeEvent</primary></indexterm>
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* NoExpose */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Drawable drawable;
int major_code; /* core is CopyArea or CopyPlane */
int minor_code; /* not defined in the core */
} XNoExposeEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
Both structures have these common members: drawable, major_code, and minor_code.
The drawable member is set to the drawable of the destination region on
which the graphics request was to be performed.
The major_code member is set to the graphics request initiated by the client
and can be either
<symbol>X_CopyArea</symbol>
or
<symbol>X_CopyPlane</symbol>.
If it is
<symbol>X_CopyArea</symbol>,
a call to
<function>XCopyArea</function>
initiated the request.
If it is
<symbol>X_CopyPlane</symbol>,
a call to
<function>XCopyPlane</function>
initiated the request.
These constants are defined in
<filename class="headerfile"><X11/Xproto.h></filename>.
<indexterm type="file"><primary><filename class="headerfile">X11/Xproto.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xproto.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xproto.h></filename></secondary></indexterm>
The minor_code member,
like the major_code member,
indicates which graphics request was initiated by
the client.
However, the minor_code member is not defined by the core
X protocol and will be zero in these cases,
although it may be used by an extension.
</para>
<para>
<!-- .LP -->
The
<structname>XGraphicsExposeEvent</structname>
structure has these additional members: x, y, width, height, and count.
The x and y members are set to the coordinates relative to the drawable's origin
and indicate the upper-left corner of the rectangle.
The width and height members are set to the size (extent) of the rectangle.
The count member is set to the number of
<symbol>GraphicsExpose</symbol>
events to follow.
If count is zero, no more
<symbol>GraphicsExpose</symbol>
events follow for this window.
However, if count is nonzero, at least that number of
<symbol>GraphicsExpose</symbol>
events (and possibly more) are to follow for this window.
</para>
</sect2>
</sect1>
<sect1 id="Window_State_Change_Events_">
<title>Window State Change Events </title>
<!-- .XS -->
<!-- (SN Window State Change Events -->
<!-- .XE -->
<para>
<!-- .LP -->
The following sections discuss:
</para>
<itemizedlist>
<listitem>
<para>
<symbol>CirculateNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>ConfigureNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>CreateNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>DestroyNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>GravityNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>MapNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>MappingNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>ReparentNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>UnmapNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>VisibilityNotify</symbol>
events
<!-- .\" .SH 3 -->
</para>
</listitem>
</itemizedlist>
<sect2 id="CirculateNotify_Events">
<title>CirculateNotify Events</title>
<!-- .XS -->
<!-- (SN CirculateNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>CirculateNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>CirculateNotify</primary></indexterm>
The X server can report
<symbol>CirculateNotify</symbol>
events to clients wanting information about when a window changes
its position in the stack.
The X server generates this event type whenever a window is actually restacked
as a result of a client application calling
<function>XCirculateSubwindows</function>,
<function>XCirculateSubwindowsUp</function>,
or
<function>XCirculateSubwindowsDown</function>.
</para>
<para>
<!-- .LP -->
To receive
<symbol>CirculateNotify</symbol>
events, set the
<symbol>StructureNotifyMask</symbol>
bit in the event-mask attribute of the window
or the
<symbol>SubstructureNotifyMask</symbol>
bit in the event-mask attribute of the parent window
(in which case, circulating any child generates an event).
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XCirculateEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* CirculateNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window event;
Window window;
int place; /* PlaceOnTop, PlaceOnBottom */
} XCirculateEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The event member is set either to the restacked window or to its parent,
depending on whether
<systemitem class="event">StructureNotify</systemitem>
or
<systemitem class="event">SubstructureNotify</systemitem>
was selected.
The window member is set to the window that was restacked.
The place member is set to the window's position after the restack occurs and
is either
<symbol>PlaceOnTop</symbol>
or
<symbol>PlaceOnBottom</symbol>.
If it is
<symbol>PlaceOnTop</symbol>,
the window is now on top of all siblings.
If it is
<symbol>PlaceOnBottom</symbol>,
the window is now below all siblings.
</para>
</sect2>
<sect2 id="ConfigureNotify_Events">
<title>ConfigureNotify Events</title>
<!-- .XS -->
<!-- (SN ConfigureNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>ConfigureNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>ConfigureNotify</primary></indexterm>
The X server can report
<symbol>ConfigureNotify</symbol>
events to clients wanting information about actual changes to a window's
state, such as size, position, border, and stacking order.
The X server generates this event type whenever one of the following configure
window requests made by a client application actually completes:
</para>
<itemizedlist>
<listitem>
<para>
A window's size, position, border, and/or stacking order is reconfigured
by calling
<function>XConfigureWindow</function>.
</para>
</listitem>
<listitem>
<para>
The window's position in the stacking order is changed by calling
<function>XLowerWindow</function>,
<function>XRaiseWindow</function>,
or
<function>XRestackWindows</function>.
</para>
</listitem>
<listitem>
<para>
A window is moved by calling
<function>XMoveWindow</function>.
</para>
</listitem>
<listitem>
<para>
A window's size is changed by calling
<function>XResizeWindow</function>.
</para>
</listitem>
<listitem>
<para>
A window's size and location is changed by calling
<function>XMoveResizeWindow</function>.
</para>
</listitem>
<listitem>
<para>
A window is mapped and its position in the stacking order is changed
by calling
<function>XMapRaised</function>.
</para>
</listitem>
<listitem>
<para>
A window's border width is changed by calling
<function>XSetWindowBorderWidth</function>.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
To receive
<symbol>ConfigureNotify</symbol>
events, set the
<symbol>StructureNotifyMask</symbol>
bit in the event-mask attribute of the window or the
<symbol>SubstructureNotifyMask</symbol>
bit in the event-mask attribute of the parent window
(in which case, configuring any child generates an event).
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XConfigureEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* ConfigureNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window event;
Window window;
int x, y;
int width, height;
int border_width;
Window above;
Bool override_redirect;
} XConfigureEvent;
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
The event member is set either to the reconfigured window or to its parent,
depending on whether
<systemitem class="event">StructureNotify</systemitem>
or
<systemitem class="event">SubstructureNotify</systemitem>
was selected.
The window member is set to the window whose size, position,
border, and/or stacking
order was changed.
</para>
<para>
<!-- .LP -->
The x and y members are set to the coordinates relative to the parent window's
origin and indicate the position of the upper-left outside corner of the window.
The width and height members are set to the inside size of the window,
not including
the border.
The border_width member is set to the width of the window's border, in pixels.
</para>
<para>
<!-- .LP -->
The above member is set to the sibling window and is used
for stacking operations.
If the X server sets this member to
<symbol>None</symbol>,
the window whose state was changed is on the bottom of the stack
with respect to sibling windows.
However, if this member is set to a sibling window,
the window whose state was changed is placed on top of this sibling window.
</para>
<para>
<!-- .LP -->
The override_redirect member is set to the override-redirect attribute of the
window.
Window manager clients normally should ignore this window if the
override_redirect member
is
<symbol>True</symbol>.
</para>
</sect2>
<sect2 id="CreateNotify_Events">
<title>CreateNotify Events</title>
<!-- .XS -->
<!-- (SN CreateNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>CreateNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>CreateNotify</primary></indexterm>
The X server can report
<symbol>CreateNotify</symbol>
events to clients wanting information about creation of windows.
The X server generates this event whenever a client
application creates a window by calling
<function>XCreateWindow</function>
or
<function>XCreateSimpleWindow</function>.
</para>
<para>
<!-- .LP -->
To receive
<symbol>CreateNotify</symbol>
events, set the
<symbol>SubstructureNotifyMask</symbol>
bit in the event-mask attribute of the window.
Creating any children then generates an event.
</para>
<para>
<!-- .LP -->
The structure for the event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XCreateWindowEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* CreateNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window parent; /* parent of the window */
Window window; /* window id of window created */
int x, y; /* window location */
int width, height; /* size of window */
int border_width; /* border width */
Bool override_redirect; /* creation should be overridden */
} XCreateWindowEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The parent member is set to the created window's parent.
The window member specifies the created window.
The x and y members are set to the created window's coordinates relative
to the parent window's origin and indicate the position of the upper-left
outside corner of the created window.
The width and height members are set to the inside size of the created window
(not including the border) and are always nonzero.
The border_width member is set to the width of the created window's border, in pixels.
The override_redirect member is set to the override-redirect attribute of the
window.
Window manager clients normally should ignore this window
if the override_redirect member is
<symbol>True</symbol>.
</para>
</sect2>
<sect2 id="DestroyNotify_Events">
<title>DestroyNotify Events</title>
<!-- .XS -->
<!-- (SN DestroyNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>DestroyNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>DestroyNotify</primary></indexterm>
The X server can report
<symbol>DestroyNotify</symbol>
events to clients wanting information about which windows are destroyed.
The X server generates this event whenever a client application destroys a
window by calling
<function>XDestroyWindow</function>
or
<function>XDestroySubwindows</function>.
</para>
<para>
<!-- .LP -->
The ordering of the
<symbol>DestroyNotify</symbol>
events is such that for any given window,
<symbol>DestroyNotify</symbol>
is generated on all inferiors of the window
before being generated on the window itself.
The X protocol does not constrain the ordering among
siblings and across subhierarchies.
</para>
<para>
<!-- .LP -->
To receive
<symbol>DestroyNotify</symbol>
events, set the
<symbol>StructureNotifyMask</symbol>
bit in the event-mask attribute of the window or the
<symbol>SubstructureNotifyMask</symbol>
bit in the event-mask attribute of the parent window
(in which case, destroying any child generates an event).
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XDestroyWindowEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* DestroyNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window event;
Window window;
} XDestroyWindowEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The event member is set either to the destroyed window or to its parent,
depending on whether
<systemitem class="event">StructureNotify</systemitem>
or
<systemitem class="event">SubstructureNotify</systemitem>
was selected.
The window member is set to the window that is destroyed.
</para>
</sect2>
<sect2 id="GravityNotify_Events">
<title>GravityNotify Events</title>
<!-- .XS -->
<!-- (SN GravityNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>GravityNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>GravityNotify</primary></indexterm>
The X server can report
<symbol>GravityNotify</symbol>
events to clients wanting information about when a window is moved because of a
change in the size of its parent.
The X server generates this event whenever a client
application actually moves a child window as a result of resizing its parent by calling
<function>XConfigureWindow</function>,
<function>XMoveResizeWindow</function>,
or
<function>XResizeWindow</function>.
</para>
<para>
<!-- .LP -->
To receive
<symbol>GravityNotify</symbol>
events, set the
<symbol>StructureNotifyMask</symbol>
bit in the event-mask attribute of the window or the
<symbol>SubstructureNotifyMask</symbol>
bit in the event-mask attribute of the parent window
(in which case, any child that is moved because its parent has been resized
generates an event).
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XGravityEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* GravityNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window event;
Window window;
int x, y;
} XGravityEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The event member is set either to the window that was moved or to its parent,
depending on whether
<systemitem class="event">StructureNotify</systemitem>
or
<systemitem class="event">SubstructureNotify</systemitem>
was selected.
The window member is set to the child window that was moved.
The x and y members are set to the coordinates relative to the
new parent window's origin
and indicate the position of the upper-left outside corner of the
window.
</para>
</sect2>
<sect2 id="MapNotify_Events">
<title>MapNotify Events</title>
<!-- .XS -->
<!-- (SN MapNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>MapNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>MapNotify</primary></indexterm>
The X server can report
<symbol>MapNotify</symbol>
events to clients wanting information about which windows are mapped.
The X server generates this event type whenever a client application changes the
window's state from unmapped to mapped by calling
<function>XMapWindow</function>,
<function>XMapRaised</function>,
<function>XMapSubwindows</function>,
<function>XReparentWindow</function>,
or as a result of save-set processing.
</para>
<para>
<!-- .LP -->
To receive
<symbol>MapNotify</symbol>
events, set the
<symbol>StructureNotifyMask</symbol>
bit in the event-mask attribute of the window or the
<symbol>SubstructureNotifyMask</symbol>
bit in the event-mask attribute of the parent window
(in which case, mapping any child generates an event).
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XMapEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* MapNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window event;
Window window;
Bool override_redirect; /* boolean, is override set... */
} XMapEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The event member is set either to the window that was mapped or to its parent,
depending on whether
<systemitem class="event">StructureNotify</systemitem>
or
<systemitem class="event">SubstructureNotify</systemitem>
was selected.
The window member is set to the window that was mapped.
The override_redirect member is set to the override-redirect attribute
of the window.
Window manager clients normally should ignore this window
if the override-redirect attribute is
<symbol>True</symbol>,
because these events usually are generated from pop-ups,
which override structure control.
</para>
</sect2>
<sect2 id="MappingNotify_Events">
<title>MappingNotify Events</title>
<!-- .XS -->
<!-- (SN MappingNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>MappingNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>MappingNotify</primary></indexterm>
The X server reports
<symbol>MappingNotify</symbol>
events to all clients.
There is no mechanism to express disinterest in this event.
The X server generates this event type whenever a client application
successfully calls:
</para>
<itemizedlist>
<listitem>
<para>
<function>XSetModifierMapping</function>
to indicate which KeyCodes are to be used as modifiers
</para>
</listitem>
<listitem>
<para>
<function>XChangeKeyboardMapping</function>
to change the keyboard mapping
</para>
</listitem>
<listitem>
<para>
<function>XSetPointerMapping</function>
to set the pointer mapping
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XMappingEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* MappingNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* unused */
int request; /* one of MappingModifier, MappingKeyboard,
MappingPointer */
int first_keycode; /* first keycode */
int count; /* defines range of change w. first_keycode*/
} XMappingEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The request member is set to indicate the kind of mapping change that occurred
and can be
<symbol>MappingModifier</symbol>,
<symbol>MappingKeyboard</symbol>,
or
<symbol>MappingPointer</symbol>.
If it is
<symbol>MappingModifier</symbol>,
the modifier mapping was changed.
If it is
<symbol>MappingKeyboard</symbol>,
the keyboard mapping was changed.
If it is
<symbol>MappingPointer</symbol>,
the pointer button mapping was changed.
The first_keycode and count members are set only
if the request member was set to
<symbol>MappingKeyboard</symbol>.
The number in first_keycode represents the first number in the range
of the altered mapping,
and count represents the number of keycodes altered.
</para>
<para>
<!-- .LP -->
To update the client application's knowledge of the keyboard,
you should call
<function>XRefreshKeyboardMapping</function>.
</para>
</sect2>
<sect2 id="ReparentNotify_Events">
<title>ReparentNotify Events</title>
<!-- .XS -->
<!-- (SN ReparentNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>ReparentNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>ReparentNotify</primary></indexterm>
The X server can report
<symbol>ReparentNotify</symbol>
events to clients wanting information about changing a window's parent.
The X server generates this event whenever a client
application calls
<function>XReparentWindow</function>
and the window is actually reparented.
</para>
<para>
<!-- .LP -->
To receive
<symbol>ReparentNotify</symbol>
events, set the
<symbol>StructureNotifyMask</symbol>
bit in the event-mask attribute of the window or the
<symbol>SubstructureNotifyMask</symbol>
bit in the event-mask attribute of either the old or the new parent window
(in which case, reparenting any child generates an event).
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XReparentEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* ReparentNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window event;
Window window;
Window parent;
int x, y;
Bool override_redirect;
} XReparentEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The event member is set either to the reparented window
or to the old or the new parent, depending on whether
<systemitem class="event">StructureNotify</systemitem>
or
<systemitem class="event">SubstructureNotify</systemitem>
was selected.
The window member is set to the window that was reparented.
The parent member is set to the new parent window.
The x and y members are set to the reparented window's coordinates relative
to the new parent window's
origin and define the upper-left outer corner of the reparented window.
The override_redirect member is set to the override-redirect attribute of the
window specified by the window member.
Window manager clients normally should ignore this window
if the override_redirect member is
<symbol>True</symbol>.
</para>
</sect2>
<sect2 id="UnmapNotify_Events">
<title>UnmapNotify Events</title>
<!-- .XS -->
<!-- (SN UnmapNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>UnmapNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>UnmapNotify</primary></indexterm>
The X server can report
<symbol>UnmapNotify</symbol>
events to clients wanting information about which windows are unmapped.
The X server generates this event type whenever a client application changes the
window's state from mapped to unmapped.
</para>
<para>
<!-- .LP -->
To receive
<symbol>UnmapNotify</symbol>
events, set the
<symbol>StructureNotifyMask</symbol>
bit in the event-mask attribute of the window or the
<symbol>SubstructureNotifyMask</symbol>
bit in the event-mask attribute of the parent window
(in which case, unmapping any child window generates an event).
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XUnmapEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* UnmapNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window event;
Window window;
Bool from_configure;
} XUnmapEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The event member is set either to the unmapped window or to its parent,
depending on whether
<systemitem class="event">StructureNotify</systemitem>
or
<systemitem class="event">SubstructureNotify</systemitem>
was selected.
This is the window used by the X server to report the event.
The window member is set to the window that was unmapped.
The from_configure member is set to
<symbol>True</symbol>
if the event was generated as a result of a resizing of the window's parent when
the window itself had a win_gravity of
<symbol>UnmapGravity</symbol>.
</para>
</sect2>
<sect2 id="VisibilityNotify_Events">
<title>VisibilityNotify Events</title>
<!-- .XS -->
<!-- (SN VisibilityNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>VisibilityNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>VisibilityNotify</primary></indexterm>
The X server can report
<symbol>VisibilityNotify</symbol>
events to clients wanting any change in the visibility of the specified window.
A region of a window is visible if someone looking at the screen can
actually see it.
The X server generates this event whenever the visibility changes state.
However, this event is never generated for windows whose class is
<symbol>InputOnly</symbol>.
</para>
<para>
<!-- .LP -->
All
<symbol>VisibilityNotify</symbol>
events caused by a hierarchy change are generated
after any hierarchy event
(<symbol>UnmapNotify</symbol>,
<symbol>MapNotify</symbol>,
<symbol>ConfigureNotify</symbol>,
<symbol>GravityNotify</symbol>,
<symbol>CirculateNotify</symbol>)
caused by that change. Any
<symbol>VisibilityNotify</symbol>
event on a given window is generated before any
<symbol>Expose</symbol>
events on that window, but it is not required that all
<symbol>VisibilityNotify</symbol>
events on all windows be generated before all
<symbol>Expose</symbol>
events on all windows.
The X protocol does not constrain the ordering of
<symbol>VisibilityNotify</symbol>
events with
respect to
<symbol>FocusOut</symbol>,
<symbol>EnterNotify</symbol>,
and
<symbol>LeaveNotify</symbol>
events.
</para>
<para>
<!-- .LP -->
To receive
<symbol>VisibilityNotify</symbol>
events, set the
<symbol>VisibilityChangeMask</symbol>
bit in the event-mask attribute of the window.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XVisibilityEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* VisibilityNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
int state;
} XVisibilityEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The window member is set to the window whose visibility state changes.
The state member is set to the state of the window's visibility and can be
<symbol>VisibilityUnobscured</symbol>,
<symbol>VisibilityPartiallyObscured</symbol>,
or
<symbol>VisibilityFullyObscured</symbol>.
The X server ignores all of a window's subwindows
when determining the visibility state of the window and processes
<symbol>VisibilityNotify</symbol>
events according to the following:
</para>
<itemizedlist>
<listitem>
<para>
When the window changes state from partially obscured, fully obscured,
or not viewable to viewable and completely unobscured,
the X server generates the event with the state member of the
<structname>XVisibilityEvent</structname>
structure set to
<symbol>VisibilityUnobscured</symbol>.
</para>
</listitem>
<listitem>
<para>
When the window changes state from viewable and completely unobscured or
not viewable to viewable and partially obscured,
the X server generates the event with the state member of the
<structname>XVisibilityEvent</structname>
structure set to
<symbol>VisibilityPartiallyObscured</symbol>.
</para>
</listitem>
<listitem>
<para>
When the window changes state from viewable and completely unobscured,
viewable and partially obscured, or not viewable to viewable and
fully obscured,
the X server generates the event with the state member of the
<structname>XVisibilityEvent</structname>
structure set to
<symbol>VisibilityFullyObscured</symbol>.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="Structure_Control_Events">
<title>Structure Control Events</title>
<!-- .XS -->
<!-- (SN Structure Control Events -->
<!-- .XE -->
<para>
<!-- .LP -->
This section discusses:
</para>
<itemizedlist>
<listitem>
<para>
<symbol>CirculateRequest</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>ConfigureRequest</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>MapRequest</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>ResizeRequest</symbol>
events
</para>
</listitem>
</itemizedlist>
<sect2 id="CirculateRequest_Events">
<title>CirculateRequest Events</title>
<!-- .XS -->
<!-- (SN CirculateRequest Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>CirculateRequest</secondary></indexterm>
<indexterm significance="preferred"><primary>CirculateRequest</primary></indexterm>
The X server can report
<symbol>CirculateRequest</symbol>
events to clients wanting information about
when another client initiates a circulate window request
on a specified window.
The X server generates this event type whenever a client initiates a circulate
window request on a window and a subwindow actually needs to be restacked.
The client initiates a circulate window request on the window by calling
<function>XCirculateSubwindows</function>,
<function>XCirculateSubwindowsUp</function>,
or
<function>XCirculateSubwindowsDown</function>.
</para>
<para>
<!-- .LP -->
To receive
<symbol>CirculateRequest</symbol>
events, set the
<symbol>SubstructureRedirectMask</symbol>
in the event-mask attribute of the window.
Then, in the future,
the circulate window request for the specified window is not executed,
and thus, any subwindow's position in the stack is not changed.
For example, suppose a client application calls
<function>XCirculateSubwindowsUp</function>
to raise a subwindow to the top of the stack.
If you had selected
<symbol>SubstructureRedirectMask</symbol>
on the window, the X server reports to you a
<symbol>CirculateRequest</symbol>
event and does not raise the subwindow to the top of the stack.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XCirculateRequestEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* CirculateRequest */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window parent;
Window window;
int place; /* PlaceOnTop, PlaceOnBottom */
} XCirculateRequestEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The parent member is set to the parent window.
The window member is set to the subwindow to be restacked.
The place member is set to what the new position in the stacking order should be
and is either
<symbol>PlaceOnTop</symbol>
or
<symbol>PlaceOnBottom</symbol>.
If it is
<symbol>PlaceOnTop</symbol>,
the subwindow should be on top of all siblings.
If it is
<symbol>PlaceOnBottom</symbol>,
the subwindow should be below all siblings.
</para>
</sect2>
<sect2 id="ConfigureRequest_Events">
<title>ConfigureRequest Events</title>
<!-- .XS -->
<!-- (SN ConfigureRequest Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>ConfigureRequest</secondary></indexterm>
<indexterm significance="preferred"><primary>ConfigureRequest</primary></indexterm>
The X server can report
<symbol>ConfigureRequest</symbol>
events to clients wanting information about when a different client initiates
a configure window request on any child of a specified window.
The configure window request attempts to
reconfigure a window's size, position, border, and stacking order.
The X server generates this event whenever a different client initiates
a configure window request on a window by calling
<function>XConfigureWindow</function>,
<function>XLowerWindow</function>,
<function>XRaiseWindow</function>,
<function>XMapRaised</function>,
<function>XMoveResizeWindow</function>,
<function>XMoveWindow</function>,
<function>XResizeWindow</function>,
<function>XRestackWindows</function>,
or
<function>XSetWindowBorderWidth</function>.
</para>
<para>
<!-- .LP -->
To receive
<symbol>ConfigureRequest</symbol>
events, set the
<symbol>SubstructureRedirectMask</symbol>
bit in the event-mask attribute of the window.
<symbol>ConfigureRequest</symbol>
events are generated when a
<systemitem>ConfigureWindow</systemitem>
protocol request is issued on a child window by another client.
For example, suppose a client application calls
<function>XLowerWindow</function>
to lower a window.
If you had selected
<symbol>SubstructureRedirectMask</symbol>
on the parent window and if the override-redirect attribute
of the window is set to
<symbol>False</symbol>,
the X server reports a
<symbol>ConfigureRequest</symbol>
event to you and does not lower the specified window.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XConfigureRequestEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* ConfigureRequest */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window parent;
Window window;
int x, y;
int width, height;
int border_width;
Window above;
int detail; /* Above, Below, TopIf, BottomIf, Opposite */
unsigned long value_mask;
} XConfigureRequestEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The parent member is set to the parent window.
The window member is set to the window whose size, position, border width,
and/or stacking order is to be reconfigured.
The value_mask member indicates which components were specified in the
<systemitem>ConfigureWindow</systemitem>
protocol request.
The corresponding values are reported as given in the request.
The remaining values are filled in from the current geometry of the window,
except in the case of above (sibling) and detail (stack-mode),
which are reported as
<symbol>None</symbol>
and
<symbol>Above</symbol>,
respectively, if they are not given in the request.
</para>
</sect2>
<sect2 id="MapRequest_Events">
<title>MapRequest Events</title>
<!-- .XS -->
<!-- (SN MapRequest Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>MapRequest</secondary></indexterm>
<indexterm significance="preferred"><primary>MapRequest</primary></indexterm>
The X server can report
<symbol>MapRequest</symbol>
events to clients wanting information about a different client's desire
to map windows.
A window is considered mapped when a map window request completes.
The X server generates this event whenever a different client initiates
a map window request on an unmapped window whose override_redirect member
is set to
<symbol>False</symbol>.
Clients initiate map window requests by calling
<function>XMapWindow</function>,
<function>XMapRaised</function>,
or
<function>XMapSubwindows</function>.
</para>
<para>
<!-- .LP -->
To receive
<symbol>MapRequest</symbol>
events, set the
<symbol>SubstructureRedirectMask</symbol>
bit in the event-mask attribute of the window.
This means another client's attempts to map a child window by calling one of
the map window request functions is intercepted, and you are sent a
<symbol>MapRequest</symbol>
instead.
For example, suppose a client application calls
<function>XMapWindow</function>
to map a window.
If you (usually a window manager) had selected
<symbol>SubstructureRedirectMask</symbol>
on the parent window and if the override-redirect attribute
of the window is set to
<symbol>False</symbol>,
the X server reports a
<symbol>MapRequest</symbol>
event to you
and does not map the specified window.
Thus, this event gives your window manager client the ability
to control the placement of subwindows.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XMapRequestEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* MapRequest */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window parent;
Window window;
} XMapRequestEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The parent member is set to the parent window.
The window member is set to the window to be mapped.
</para>
</sect2>
<sect2 id="ResizeRequest_Events">
<title>ResizeRequest Events</title>
<!-- .XS -->
<!-- (SN ResizeRequest Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>ResizeRequest</secondary></indexterm>
<indexterm significance="preferred"><primary>ResizeRequest</primary></indexterm>
The X server can report
<symbol>ResizeRequest</symbol>
events to clients wanting information about another client's attempts to change the
size of a window.
The X server generates this event whenever some other client attempts to change
the size of the specified window by calling
<function>XConfigureWindow</function>,
<function>XResizeWindow</function>,
or
<function>XMoveResizeWindow</function>.
</para>
<para>
<!-- .LP -->
To receive
<symbol>ResizeRequest</symbol>
events, set the
<symbol>ResizeRedirect</symbol>
bit in the event-mask attribute of the window.
Any attempts to change the size by other clients are then redirected.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XResizeRequestEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* ResizeRequest */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
int width, height;
} XResizeRequestEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The window member is set to the window whose size another
client attempted to change.
The width and height members are set to the inside size of the window,
excluding the border.
</para>
</sect2>
</sect1>
<sect1 id="Colormap_State_Change_Events">
<title>Colormap State Change Events</title>
<!-- .XS -->
<!-- (SN Colormap State Change Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>ColormapNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>ColormapNotify</primary></indexterm>
The X server can report
<symbol>ColormapNotify</symbol>
events to clients wanting information about when the colormap changes
and when a colormap is installed or uninstalled.
The X server generates this event type whenever a client application:
</para>
<itemizedlist>
<listitem>
<para>
Changes the colormap member of the
<structname>XSetWindowAttributes</structname>
structure by
calling
<function>XChangeWindowAttributes</function>,
<function>XFreeColormap</function>,
or
<function>XSetWindowColormap</function>
</para>
</listitem>
<listitem>
<para>
Installs or uninstalls the colormap by calling
<function>XInstallColormap</function>
or
<function>XUninstallColormap</function>
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
To receive
<symbol>ColormapNotify</symbol>
events, set the
<symbol>ColormapChangeMask</symbol>
bit in the event-mask attribute of the window.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XColormapEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* ColormapNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
Colormap colormap; /* colormap or None */
Bool new;
int state; /* ColormapInstalled, ColormapUninstalled */
} XColormapEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The window member is set to the window whose associated
colormap is changed, installed, or uninstalled.
For a colormap that is changed, installed, or uninstalled,
the colormap member is set to the colormap associated with the window.
For a colormap that is changed by a call to
<function>XFreeColormap</function>,
the colormap member is set to
<symbol>None</symbol>.
The new member is set to indicate whether the colormap
for the specified window was changed or installed or uninstalled
and can be
<symbol>True</symbol>
or
<symbol>False</symbol>.
If it is
<symbol>True</symbol>,
the colormap was changed.
If it is
<symbol>False</symbol>,
the colormap was installed or uninstalled.
The state member is always set to indicate whether the colormap is installed or
uninstalled and can be
<symbol>ColormapInstalled</symbol>
or
<symbol>ColormapUninstalled</symbol>.
</para>
</sect1>
<sect1 id="Client_Communication_Events">
<title>Client Communication Events</title>
<!-- .XS -->
<!-- (SN Client Communication Events -->
<!-- .XE -->
<para>
<!-- .LP -->
This section discusses:
</para>
<itemizedlist>
<listitem>
<para>
<symbol>ClientMessage</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>PropertyNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>SelectionClear</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>SelectionNotify</symbol>
events
</para>
</listitem>
<listitem>
<para>
<symbol>SelectionRequest</symbol>
events
</para>
</listitem>
</itemizedlist>
<sect2 id="ClientMessage_Events">
<title>ClientMessage Events</title>
<!-- .XS -->
<!-- (SN ClientMessage Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>ClientMessage</secondary></indexterm>
<indexterm significance="preferred"><primary>ClientMessage</primary></indexterm>
The X server generates
<symbol>ClientMessage</symbol>
events only when a client calls the function
<function>XSendEvent</function>.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XClientMessageEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 1i 3i -->
<!-- .ta .5i 1i 3i -->
typedef struct {
int type; /* ClientMessage */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
Atom message_type;
int format;
union {
char b[20];
short s[10];
long l[5];
} data;
} XClientMessageEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The message_type member is set to an atom that indicates how the data
should be interpreted by the receiving client.
The format member is set to 8, 16, or 32 and specifies whether the data
should be viewed as a list of bytes, shorts, or longs.
The data member is a union that contains the members b, s, and l.
The b, s, and l members represent data of twenty 8-bit values,
ten 16-bit values, and five 32-bit values.
Particular message types might not make use of all these values.
The X server places no interpretation on the values in the window,
message_type, or data members.
</para>
</sect2>
<sect2 id="PropertyNotify_Events">
<title>PropertyNotify Events</title>
<!-- .XS -->
<!-- (SN PropertyNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>PropertyNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>PropertyNotify</primary></indexterm>
The X server can report
<symbol>PropertyNotify</symbol>
events to clients wanting information about property changes
for a specified window.
</para>
<para>
<!-- .LP -->
To receive
<symbol>PropertyNotify</symbol>
events, set the
<symbol>PropertyChangeMask</symbol>
bit in the event-mask attribute of the window.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XPropertyEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* PropertyNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
Atom atom;
Time time;
int state; /* PropertyNewValue or PropertyDelete */
} XPropertyEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The window member is set to the window whose associated
property was changed.
The atom member is set to the property's atom and indicates which
property was changed or desired.
The time member is set to the server time when the property was changed.
The state member is set to indicate whether the property was changed
to a new value or deleted and can be
<symbol>PropertyNewValue</symbol>
or
<symbol>PropertyDelete</symbol>.
The state member is set to
<symbol>PropertyNewValue</symbol>
when a property of the window is changed using
<function>XChangeProperty</function>
or
<function>XRotateWindowProperties</function>
(even when adding zero-length data using
<function>XChangeProperty</function>)
and when replacing all or part of a property with identical data using
<function>XChangeProperty</function>
or
<function>XRotateWindowProperties</function>.
The state member is set to
<symbol>PropertyDelete</symbol>
when a property of the window is deleted using
<function>XDeleteProperty</function>
or, if the delete argument is
<symbol>True</symbol>,
<function>XGetWindowProperty</function>.
</para>
</sect2>
<sect2 id="SelectionClear_Events">
<title>SelectionClear Events</title>
<!-- .XS -->
<!-- (SN SelectionClear Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm ><primary>Events</primary><secondary>SelectionClear</secondary></indexterm>
<indexterm significance="preferred"><primary>SelectionClear</primary></indexterm>
The X server reports
<symbol>SelectionClear</symbol>
events to the client losing ownership of a selection.
The X server generates this event type when another client
asserts ownership of the selection by calling
<function>XSetSelectionOwner</function>.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XSelectionClearEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* SelectionClear */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
Atom selection;
Time time;
} XSelectionClearEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The selection member is set to the selection atom.
The time member is set to the last change time recorded for the
selection.
The window member is the window that was specified by the current owner
(the owner losing the selection) in its
<function>XSetSelectionOwner</function>
call.
</para>
</sect2>
<sect2 id="SelectionRequest_Events">
<title>SelectionRequest Events</title>
<!-- .XS -->
<!-- (SN SelectionRequest Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>SelectionRequest</secondary></indexterm>
<indexterm significance="preferred"><primary>SelectionRequest</primary></indexterm>
The X server reports
<symbol>SelectionRequest</symbol>
events to the owner of a selection.
The X server generates this event whenever a client
requests a selection conversion by calling
<function>XConvertSelection</function>
for the owned selection.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XSelectionRequestEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* SelectionRequest */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window owner;
Window requestor;
Atom selection;
Atom target;
Atom property;
Time time;
} XSelectionRequestEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The owner member is set to the window
that was specified by the current owner in its
<function>XSetSelectionOwner</function>
call.
The requestor member is set to the window requesting the selection.
The selection member is set to the atom that names the selection.
For example, PRIMARY is used to indicate the primary selection.
The target member is set to the atom that indicates the type
the selection is desired in.
The property member can be a property name or
<symbol>None</symbol>.
The time member is set to the timestamp or
<symbol>CurrentTime</symbol>
value from the
<systemitem>ConvertSelection</systemitem>
request.
</para>
<para>
<!-- .LP -->
The owner should convert the selection based on the specified target type
and send a
<symbol>SelectionNotify</symbol>
event back to the requestor.
A complete specification for using selections is given in the X Consortium
standard <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
</para>
</sect2>
<sect2 id="SelectionNotify_Events">
<title>SelectionNotify Events</title>
<!-- .XS -->
<!-- (SN SelectionNotify Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm><primary>Events</primary><secondary>SelectionNotify</secondary></indexterm>
<indexterm significance="preferred"><primary>SelectionNotify</primary></indexterm>
This event is generated by the X server in response to a
<systemitem>ConvertSelection</systemitem>
protocol request when there is no owner for the selection.
When there is an owner, it should be generated by the owner
of the selection by using
<function>XSendEvent</function>.
The owner of a selection should send this event to a requestor when a selection
has been converted and stored as a property
or when a selection conversion could
not be performed (which is indicated by setting the property member to
<symbol>None</symbol>).
</para>
<para>
<!-- .LP -->
If
<symbol>None</symbol>
is specified as the property in the
<systemitem>ConvertSelection</systemitem>
protocol request, the owner should choose a property name,
store the result as that property on the requestor window,
and then send a
<symbol>SelectionNotify</symbol>
giving that actual property name.
</para>
<para>
<!-- .LP -->
The structure for this event type contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XSelectionEvent</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int type; /* SelectionNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window requestor;
Atom selection;
Atom target;
Atom property; /* atom or None */
Time time;
} XSelectionEvent;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The requestor member is set to the window associated with
the requestor of the selection.
The selection member is set to the atom that indicates the selection.
For example, PRIMARY is used for the primary selection.
The target member is set to the atom that indicates the converted type.
For example, PIXMAP is used for a pixmap.
The property member is set to the atom that indicates which
property the result was stored on.
If the conversion failed,
the property member is set to
<symbol>None</symbol>.
The time member is set to the time the conversion took place and
can be a timestamp or
<symbol>CurrentTime</symbol>.
<!-- .bp -->
</para>
</sect2>
</sect1>
</chapter>