.\".U7
.\".UT "Events and Event-Handling Functions" 8
\&
.sp 1
.ce 3
\s+1\fBChapter 8\fP\s-1

\s+1\fBEvents and Event-Handling Functions\fP\s-1
.sp 2
.nr H1 8
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 8: Events and Event-Handling Functions 
.XE
A client application communicates with the X server through the connection you
establish with the 
.PN XOpenDisplay 
.IN "XOpenDisplay"
function.
It is over this connection that a client application sends ``requests'' to the X
server.
.IN "Requests" "" "@DEF@"
These requests are made by the Xlib functions that are 
called in the client application.
The X server sends back to the client 
application either ``replies'' or events.
.IN "Reply" "" "@DEF@"
Most requests made by Xlib functions do not generate replies.
Some requests generate multiple replies.
Numerous Xlib functions cause the X server to generate events.
In addition, the user's typing or moving the pointer can generate
events asynchronously.
.LP
This chapter begins with a discussion of the following topics associated with
events:
.IP \(bu 5
Event types
.IP \(bu 5
Event structures
.IP \(bu 5
Event mask
.IP \(bu 5
Event processing
.LP
The chapter continues with a discussion of the Xlib functions you can use to:
.IP \(bu 5
Select events
.IP \(bu 5
Handle the output buffer and the event queue
.IP \(bu 5
Select events from the event queue 
.IP \(bu 5
Send and get events
.IP \(bu 5
Handle error events
.LE
.RE
.NT
Some toolkits use their own event-handling routines.
Also, some toolkits do not allow you to interchange these event-handling routines
with those in the Xlib library.
See the document supplied with your toolkit
for further information. 
.NE
.LP
Most applications simply are event loops.
That is, they wait for an event, decide what to do with it,
execute some amount of code, which, in turn, results in changes to the display,
and then wait for the next event.
.NH 2
Event Types
.XS
\*(SN Event Types 
.XE
.LP
.IN "Event" "Types"
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.
.IN "Event" "" "@DEF@"
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, 
usually
by calling the 
.PN XSelectInput 
Xlib function.
However,
.PN KeymapNotify
events are always sent.
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.
.IN "Input Control"
.IN "Output Control"
.LP
The event type describes a specific event generated by the X server.
For each event type, there is a corresponding constant name defined in
.Pn < X11/X.h >.
When referring to an event type, this manual uses the constant name defined in
this file.
It is often useful to group one or more event types into logical
categories.
For example, exposure processing refers to
the processing that occurs for the exposure events 
.PN Expose ,
.PN GraphicsExpose ,
and
.PN NoExpose .
.LP
.\"Table 8-1
.IN "Event" "Categories"
The following table 
lists the event category 
and its associated event type or types. 
The processing associated with these events is discussed in Section 8.4.
.LP
.\".CP T 1
.\"Event Categories and Event Types
.LP
.TS H
lw(2.25i) lw(3.5i).
_
.sp 6p
.TB
Event Category	Event Type
.sp 6p
_
.sp 6p
.TH
.R
T{
Keyboard events
T}	T{
.PN KeyPress ,
.PN KeyRelease
T}
.sp 6p
T{
Pointer motion events
T}	T{
.PN ButtonPress , 
.PN ButtonRelease  ,
.PN MotionNotify
T}
.sp 6p
T{
Window crossing events
T}	T{
.PN EnterNotify , 
.PN LeaveNotify
T}
.sp 6p
T{
Input focus events
T}	T{
.PN FocusIn , 
.PN FocusOut
T}
.sp 6p
T{
Key map state notification event
T}	T{
.PN KeymapNotify
T}
.sp 6p
T{
Exposure events	
T}	T{
.PN Expose , 
.PN GraphicsExpose , 
.PN NoExpose
T}
.sp 6p
T{
Structure control events
T}	T{
.PN CirculateRequest , 
.PN ConfigureRequest , 
.PN MapRequest ,
.PN ResizeRequest
T}
.sp 6p
T{
Window state notification events
T}	T{
.PN CirculateNotify , 
.PN ConfigureNotify , 
.PN CreateNotify , 
.PN DestroyNotify , 
.PN GravityNotify , 
.PN MapNotify ,
.PN MappingNotify , 
.PN ReparentNotify , 
.PN UnmapNotify , 
.PN VisibilityNotify
T}
.sp 6p
T{
Color map state notification event
T}	T{
.PN ColormapNotify
T}
.sp 6p
T{
Client communication events
T}	T{
.PN ClientMessage , 
.PN PropertyNotify , 
.PN SelectionClear , 
.PN SelectionNotify , 
.PN SelectionRequest
T}
.sp 6p
_
.TE
.\".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
.NH 2
Event Structures
.XS
\*(SN Event Structures 
.XE
.LP
Each event type has a corresponding structure declared in
.Pn < X11/Xlib.h >.
.IN "Event Structures" 
All event structures have the following members:
.IP type 1i
Set to the event type
constant name that uniquely identifies it. 
For example, when the X server reports a
.PN GraphicsExpose
event to a client application, it sends an
.PN XGraphicsExposeEvent
structure with the type member set to
.PN GraphicsExpose .
.IP display 1i
Set to a pointer to the display the event was read on.
.IP send_event 1i
Set to
.PN True
if the event came from an
.PN XSendEvent
request.
.IP serial 1i
Set from the serial number reported in the protocol
but expanded from the 16-bit least-significant bits to a full 32-bit value.
.LP
The X server may send events at any time in the input stream, 
even between the
time your client application sends a request and receives a reply.
Xlib stores in an event queue any events received 
while waiting for a reply for later use.
Xlib also provides functions that allow you to check events 
in the event queue, 
and these are discussed in Section 8.6.
.LP
.IN "XEvent" "" "@DEF@"
In addition to the individual structures declared for each event type,
there is also a generic 
.PN XEvent
structure. 
The
.PN XEvent
structure is a union of the individual structures declared for each event type.
Once you determine the event type, use the structures declared in
.Pn < X11/Xlib.h > 
when making references to it in a client application.
All events contain a ``type'' member that determines the format
of the information.
Depending on the type,
you should access elements of each event by using the 
.PN XEvent
union.
.NH 2
Event Mask
.XS
\*(SN Event Mask 
.XE
.LP
.IN "event mask" "" "@DEF@"
Clients select event reporting of most events relative to a window.
To do this, you 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
.Pn < X11/X.h >.
Each bit in the event mask maps to an event mask name.
The event mask name describes the event or events you want the X server to
return to a client application.
When referring to a specific event mask, 
this manual uses the constant name defined in
this file.
.LP
Most events are not reported to clients when they are generated, 
unless the client has specifically asked for them.
.PN GraphicsExpose
and 
.PN NoExpose ,
however, are reported, by default, as a result of
.PN XCopyPlane
and
.PN XCopyArea ,
unless the client suppresses them by setting graphics_expose in the GC to
.PN False .
See Section 6.2 for further information.
.PN SelectionClear ,
.PN SelectionRequest ,
.PN SelectionNotify 
or
.PN ClientMessage
cannot be masked, but they generally are only sent to clients cooperating
with selections.
See Section 4.4 for further information.
.PN MappingNotify
is always sent to clients when the keyboard mapping is changed.
.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.
.LP
.\" .CP T 2
.\"Event Mask Definitions
.TS H
lw(2i) lw(3.5i).
_
.sp 6p
.TB
Event Mask	Circumstances
.sp 6p
_
.sp 6p
.TH
.R
T{
.PN NoEventMask
T}	T{
No events wanted
T}
T{
.PN KeyPressMask
T}	T{
Keyboard down events wanted
T}
T{
.PN KeyReleaseMask
T}	T{
Keyboard up events wanted
T}
T{
.PN ButtonPressMask
T}	T{
Pointer button down events wanted
T}
T{
.PN ButtonReleaseMask
T}	T{
Pointer button up events wanted
T}
T{
.PN EnterWindowMask
T}	T{
Pointer window entry events wanted
T}
T{
.PN LeaveWindowMask
T}	T{
Pointer window leave events wanted
T}
T{
.PN PointerMotionMask
T}	T{
Pointer motion events wanted
T}
T{
.PN PointerMotionHintMask
T}	T{
Pointer motion hints wanted
T}
T{
.PN Button1MotionMask
T}	T{
Pointer motion while button 1 down
T}
T{
.PN Button2MotionMask
T}	T{
Pointer motion while button 2 down
T}
T{
.PN Button3MotionMask
T}	T{
Pointer motion while button 3 down
T}
T{
.PN Button4MotionMask
T}	T{
Pointer motion while button 4 down
T}
T{
.PN Button5MotionMask
T}	T{
Pointer motion while button 5 down
T}
T{
.PN ButtonMotionMask
T}	T{
Pointer motion while any button down
T}
T{
.PN KeymapStateMask
T}	T{
Any keyboard state change wanted
T}
T{
.PN ExposureMask
T}	T{
Any exposure wanted
T}
T{
.PN VisibilityChangeMask
T}	T{
Any change in visibility wanted
T}
T{
.PN StructureNotifyMask
T}	T{
Any change in window structure wanted
T}
T{
.PN ResizeRedirectMask
T}	T{
Redirect resize of this window
T}
T{
.PN SubstructureNotifyMask
T}	T{
Substructure notification wanted
T}
T{
.PN SubstructureRedirectMask
T}	T{
Redirect substructure of window
T}
T{
.PN FocusChangeMask
T}	T{
Any change in input focus wanted
T}
T{
.PN PropertyChangeMask
T}	T{
Any change in property wanted
T}
T{
.PN ColormapChangeMask
T}	T{
Any change in Colormap wanted
T}
T{
.PN OwnerGrabButtonMask
T}	T{
Automatic grabs should activate when owner_events is 
.PN True
T}
.sp 6p
_
.TE
.LP
.NH 2
Event Processing
.XS
\*(SN Event Processing 
.XE
.LP
The event types reported to a client application during event processing
depend on which event masks
you pass to the event_mask argument of the
.PN XSelectInput
function (Section 8.5).
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
.PN ButtonPressMask ,
the X server sends back only
.PN ButtonPress
events.
.IN "CurrentTime"
Most events contain a time member that is the time at which an event occurred.
.LP
In other cases, one event mask constant can map to several event type constants.
For example, if you pass the event mask
.PN SubstructureNotifyMask ,
the X server can send back
.PN CirculateNotify ,
.PN ConfigureNotify ,
.PN CreateNotify ,
.PN DestroyNotify ,
.PN GravityNotify ,
.PN MapNotify ,
.PN ReparentNotify ,
or
.PN UnmapNotify
events.
.LP
In another case, two event mask constants map to one event type constant.
For example, if you pass the event mask
.PN PointerMotionMask
or
.PN PointerMotionHintMask
the X server sends back
a
.PN MotionNotify
event.
.LP
.\"Table 8-3
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 typedef's to a generic structure
that is shared between two event types.
Note that the letters N.A. appear in columns for which the information is not applicable.
.\".CP T 3
.\"Event Masks, Event Types, and Event Structures
.LP
.ps 9
.nr PS 9
.TS H
lw(1.5i) lw(1i) lw(1.5i) lw(1.5i).
_
.sp 6p
.TB
Event Mask	Event Type	Structure	Generic Structure
.sp 6p
_
.sp 6p
.TH
.R
ButtonMotionMask	MotionNotify	XPointerMovedEvent	XMotionEvent
Button1MotionMask		
Button2MotionMask		
Button3MotionMask		
Button4MotionMask		
Button5MotionMask		
.sp 6p
ButtonPressMask	ButtonPress	XButtonPressedEvent	XButtonEvent
.sp 6p
ButtonReleaseMask	ButtonRelease	XButtonReleasedEvent	XButtonEvent
.sp 6p
ColormapChangeMask	ColormapNotify	XColormapEvent
.sp 6p
EnterWindowMask	EnterNotify	XEnterWindowEvent	XCrossingEvent
.sp 6p
LeaveWindowMask	LeaveNotify	XLeaveWindowEvent
.sp 6p
ExposureMask	Expose	XExposeEvent 
	GraphicsExpose	XGraphicsExposeEvent
	NoExpose	XNoExposeEvent
.sp 6p
FocusChangeMask	FocusIn	XFocusInEvent	XFocusChangeEvent
	FocusOut	XFocusOutEvent	XFocusChangeEvent
.sp 6p
KeymapStateMask	KeymapNotify	XKeymapEvent
.sp 6p
KeyPressMask	KeyPress	XKeyPressedEvent	XKeyEvent
	KeyRelease	XKeyReleasedEvent	XKeyEvent
.sp 6p
OwnerGrabButtonMask	N.A.	N.A.
.sp 6p
PointerMotionMask	MotionNotify	XPointerMovedEvent	XMotionEvent
PointerMotionHintMask		
.sp 6p
PropertyChangeMask	PropertyNotify	XPropertyEvent
.sp 6p
ResizeRedirectMask	ResizeRequest	XResizeRequestEvent
.sp 6p
StructureNotifyMask	CirculateNotify	XCirculateEvent
	ConfigureNotify	XConfigureEvent
	DestroyNotify	XDestroyWindowEvent
	GravityNotify	XGravityEvent
	MapNotify	XMapEvent
	ReparentNotify	XReparentEvent
	UnmapNotify	XUnmapEvent
.sp 6p
SubstructureNotifyMask	CirculateNotify	XCirculateEvent
	ConfigureNotify	XConfigureEvent
	CreateNotify	XCreateWindowEvent
	DestroyNotify	XDestroyWindowEvent
	GravityNotify	XGravityEvent
	MapNotify	XMapEvent
	ReparentNotify	XReparentEvent
	UnmapNotify	XUnmapEvent
.sp 6p
SubstructureRedirectMask	CirculateRequest	XCirculateRequestEvent
	ConfigureRequest	XConfigureRequestEvent
	MapRequest	XMapRequestEvent
.sp 6p
N.A.	ClientMessage	XClientMessageEvent
.sp 6p
N.A.	MappingNotify	XMappingEvent
.sp 6p
N.A.	SelectionClear	XSelectionClearEvent
.sp 6p
N.A.	SelectionNotify	XSelectionEvent
.sp 6p
N.A.	SelectionRequest	XSelectionRequestEvent
.sp 6p
VisibilityChangeMask	VisibilityNotify	XVisibilityEvent
.sp 6p
_
.TE
.ps 11
.nr PS 11
.LP
The sections below describe the processing that occurs 
when you pass the different event masks to
.PN XSelectInput
(Section 8.5). 
The sections are organized according to these processing categories:
.IP \(bu 5
Keyboard and pointer event processing 
.IP \(bu 5
Window crossing event processing
.IP \(bu 5
Input focus event processing
.IP \(bu 5
Key map state notification event processing
.IP \(bu 5
Exposure event processing
.IP \(bu 5
Window state notification event processing
.IP \(bu 5
Structure control event processing
.IP \(bu 5
Color map state notification event processing
.IP \(bu 5
Client communication event processing
.LP
The processing descriptions include explanations of the structure or structures
associated with the event.
All the event structures contain the members type and display, 
which were discussed in Section 8.2.
Thus, 
the explanations for these members are not repeated in the following sections.
.NH 3
Keyboard and Pointer Event Processing
.XS
\*(SN Keyboard and Pointer Event Processing 
.XE
.LP
This section discusses the event processing that occurs when a pointer button
is pressed and when the keyboard events
.PN KeyPress
and
.PN KeyRelease 
and the pointer motion events
.PN ButtonPress ,
.PN ButtonRelease ,
and
.PN MotionNotify
are generated.
.NH 4
Pointer Button Specific Processing
.XS
\*(SN Pointer Button Specific Processing 
.XE
.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.
.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
.PN XGrabButton
with these client passed arguments:
.IP \fIw\fP 1i
The event window 
.IP \fIevent_mask\fP 1i
The client's selected pointer motion events on the event window.
.IP \fIpointer_mode\fP 1i
.PN GrabModeAsync .
.IP \fIkeyboard_mode\fP 1i
.PN GrabModeAsync .
.IP \fIowner_events\fP 1i
.PN True ,
if the client has selected
.PN OwnerGrabButtonMask
on the event window; 
otherwise,
.PN False .
.IP \fIconfine_to\fP 1i
.PN None .
.IP \fIcursor\fP 1i
.PN None .
.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
.PN XUngrabPointer
and
.PN XChangeActivePointerGrab .
.NH 4
Common Keyboard and Pointer Event Processing
.XS
\*(SN Common Keyboard and Pointer Event Processing 
.XE
.LP
.IN "Event Processing" "ButtonPress"
.IN "Event Processing" "ButtonRelease"
.IN "Event Processing" "KeyPress"
.IN "Event Processing" "KeyRelease"
.IN "Event Processing" "MotionNotify"
This section discusses the processing that occurs for the
keyboard events
.PN KeyPress
and 
.PN KeyRelease 
and the pointer motion events
.PN ButtonPress ,
.PN ButtonRelease ,
and
.PN MotionNotify .
See Chapter 10
for information about the keyboard event handling utility
functions provided in XLib.
.LP
The X server can report
.PN KeyPress
.or
.PN KeyRelease
events to clients wanting information about when a key is pressed and
.PN KeyRelease
events to clients wanting information about when a key logically changes state.
Note that these events are generated for all keys, 
even those mapped to modifier bits.
The X server reports
.PN ButtonPress
or
.PN ButtonRelease
events to clients wanting information about buttons that logically change state.
.LP
The X server reports
.PN MotionNotify
events to clients wanting information about when the pointer logically moves.
The X server generates this event whenever the pointer changes state, 
that is, whenever the pointer is moved 
and the pointer motion begins and ends in the window.
The granularity of
.PN MotionNotify
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.
.LP
The generation of the logical changes may lag the physical changes 
if device event processing is frozen.
.LP
To receive
.PN KeyPress ,
.PN KeyRelease ,
.PN ButtonPress ,
and
.PN ButtonRelease 
events in a client application, you pass a window ID 
and 
.PN KeyPressMask ,
.PN KeyReleaseMask ,
.PN ButtonPressMask ,
and
.PN ButtonReleaseMask 
as the event_mask arguments to
.PN XSelectInput .
.LP
To receive 
.PN MotionNotify
events in a client application, you pass a window ID 
and one or more of the following event masks 
as the event_mask argument to
.PN XSelectInput :
.IP \(bu 5
Button1MotionMask\-Button5MotionMask
.IP
The client application receives
.PN MotionNotify
events only when one or more of the specified buttons is pressed.
.IP \(bu 5
ButtonMotionMask
.IP
The client application receives
.PN MotionNotify
events only when at least one button is pressed.
.IP \(bu 5
PointerMotionMask
.IP
The client application receives 
.PN MotionNotify
events independent of the state of
the pointer buttons.
.IP \(bu 5
PointerMotionHint
.IP
If
.PN PointerMotionHintMask
is selected, the X server is free to send only one
.PN MotionNotify
event (with the is_hint member  of the
.PN XPointerMovedEvent
structure set to
.PN NotifyHint )
to the client for the event window, until either the key or button state changes,
or the pointer leaves the event window, or the client calls the
.PN XQueryPointer
or
.PN XGetMotionEvents
functions.
The server still may send
.PN MotionNotify
events without is_hint set to
.PN NotifyHint .
.LP
The source of the event is the smallest window containing the pointer.
The window used by the X server to report these events depends on its 
position in the window hierarchy and whether any intervening window 
prohibits the generation of these events.
The X server searches up the window hierarchy, starting with the source
window, 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 event 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.
See Chapter 7 for a discussion of the 
.PN XGrabPointer ,
.PN XGrabKeyboard ,
and
.PN XSetInputFocus
functions. 
.LP
The structures associated with these events are
.PN XKeyPressedEvent ,
.PN XKeyReleasedEvent ,
.PN XButtonPressedEvent ,
.PN XButtonReleasedEvent ,
and
.PN XPointerMovedEvent .
The window the event is reported with respect to is called the event
window.
These structures have the following common members:
window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen.
.LP
The window member is set to the window ID of the window on which the
event was generated and is referred to as the event window. 
This is the window used by the X server to report the event, as long as the
conditions discussed in the previous paragraph are met.
The root member is set to the window ID of 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.
.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
.PN True 
or
.PN False .
If
.PN True ,
the event and root windows are on the same screen.
If
.PN False ,
the event and root windows are not on the same screen.
.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 an ancestor of or is the source member.
Otherwise, the X server sets the subwindow member to
.PN None .
The time member is set to the time when the event was generated 
and is expressed in milliseconds since the server reset.
.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.
.LP
The state member is set to indicate the logical state of the pointer buttons 
and modifier keys just prior to the event.
For the state of the pointer buttons, the X server can set this member to 
the bitwise inclusive OR of one or more of the
button or modifier key masks:
.PN Button1Mask ,
.PN Button2Mask ,
.PN Button3Mask ,
.PN Button4Mask ,
.PN Button5Mask ,
.PN ShiftMask ,
.PN LockMask ,
.PN ControlMask ,
.PN Mod1Mask ,
.PN Mod2Mask ,
.PN Mod3Mask ,
.PN Mod4Mask ,
.PN Mod5Mask .
.LP
Each of these structures also has a member that indicates the detail.
For the
.PN XKeyPressedEvent
and
.PN XKeyReleasedEvent
structures, this member is called 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 Chapter 10 for more information on the keycode.
.LP
For the
.PN XButtonPressedEvent
and
.PN XButtonReleasedEvent
structures, this member is called button.
It represents the pointer buttons that changed state and can be
set to the bitwise inclusive OR of one or more of these
button names:
.PN Button1 ,
.PN Button2 ,
.PN Button3 ,
.PN Button4 ,
.PN Button5 .
For the
.PN XPointerMovedEvent
structure, this member is called is_hint.
It can be set to one of these constants: 
.PN NotifyNormal
or
.PN NotifyHint .
.NH 3
Window Entry/Exit Event Processing
.XS
\*(SN Window Entry/Exit Event Processing 
.XE
.LP
.IN "Event Processing" "EnterNotify"
.IN "Event Processing" "LeaveNotify"
This section describes the processing that 
occurs for the window crossing events
.PN EnterNotify
and
.PN LeaveNotify .
If a pointer motion or a window hierarchy change causes the
pointer to be in a different window than before, the X server reports
.PN EnterNotify
or
.PN LeaveNotify
events to clients who have selected for these events.
All 
.PN EnterNotify
and 
.PN LeaveNotify
events caused by a hierarchy change are
generated after any hierarchy event (
.PN UnmapNotify ,
.PN MapNotify ,
.PN ConfigureNotify ,
.PN GravityNotify ,
.PN CirculateNotify )
caused by that change,
but the ordering of 
.PN EnterNotify and 
.PN LeaveNotify 
events with respect to
.PN FocusOut , 
.PN VisibilityNotify ,
and 
.PN Expose 
events is not constrained by the X protocol.
.LP
This contrasts with
.PN MotionNotify
events, which are also generated when the pointer moves, 
but the pointer motion begins and ends in a single window.
An
.PN EnterNotify
or
.PN LeaveNotify
event may also be generated when some client application calls
.PN XChangeActivePointerGrab ,
.PN XGrabKeyboard ,
.PN XGrabPointer ,
and
.PN XUngrabPointer .
.LP
To receive
.PN EnterNotify
events in a client application, you must pass a window ID 
and
.PN EnterWindowMask
as the event_mask argument to
.PN XSelectInput .
Likewise, to receive
.PN LeaveNotify
events, you pass the window ID and 
.PN LeaveWindowMask .
.LP
The members of the
.PN XEnterWindowEvent
and
.PN XLeaveWindowEvent
structures associated with these events are window, root,
subwindow, time, x, y, x_root, y_root, mode, detail, same_screen,
focus, and state.
The pointer position reported in the event is always the
final position, not the initial position of the pointer.
.LP
The window member is set to the window ID of the window on which the
.PN EnterNotify
or
.PN LeaveNotify
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 the root window for this position and
is set to the window ID of the root window on which the 
event occurred.
.LP
In a LeaveNotify 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
.PN None .
For an
EnterNotify event, if a child of the event window contains the final
pointer position, the subwindow component is set to that child.
Otherwise, it is set to
.PN None .
.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 final position of the pointer, 
not the initial position of the pointer.
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.
.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
.PN True 
or
.PN False .
If
.PN True ,
the event and root windows are on the same screen.
If
.PN False ,
the event and root windows are not on the same screen.
.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
.PN True 
or
.PN False .
If
.PN True ,
the event window is the focus window or an inferior of the focus window.
If
.PN False ,
the event window is not the focus window or an inferior of the focus window.
.LP
The state member is set to indicate the state of the pointer buttons and
modifier keys just prior to the
event.
For the state of the pointer buttons, the X server can set this member to 
the bitwise inclusive OR of one or more of the
button or modifier key masks:
.PN Button1Mask ,
.PN Button2Mask ,
.PN Button3Mask ,
.PN Button4Mask ,
.PN Button5Mask ,
.PN ShiftMask ,
.PN LockMask ,
.PN ControlMask ,
.PN Mod1Mask ,
.PN Mod2Mask ,
.PN Mod3Mask ,
.PN Mod4Mask ,
.PN Mod5Mask .
.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 the corresponding constants
.PN NotifyNormal ,
.PN NotifyGrab ,
or
.PN NotifyUngrab .
.LP
The detail member is set to indicate the notify detail and can be one of these
constants:
.PN NotifyAncestor ,
.PN NotifyVirtual ,
.PN NotifyInferior ,
.PN NotifyNonlinear ,
or
.PN NotifyNonlinearVirtual .
.LP
The following sections discuss how the X server processes normal pointer motion
events and pseudo motion events.
.\".SH 3
.NH 4 
Normal Entry/Exit Event Processing
.XS
\*(SN Normal Entry/Exit Event Processing 
.XE
.LP
.PN EnterNotify
and
.PN LeaveNotify
events are generated when the pointer moves from
one window to another window.
Normal events are identified by
.PN XEnterWindowEvent
or
.PN XLeaveWindowEvent
structures whose mode member is set to
.PN NotifyNormal .
.IP \(bu 5
When the pointer moves from window A to window B, 
and A is an inferior of B, the
X server generates:
.RS
.IP \- 5
A
.PN LeaveNotify
event on window A with the detail member of the
.PN XLeaveWindowEvent
structure set to
.PN NotifyAncestor .
.IP \- 5
A
.PN LeaveNotify
event on each window between window A and window B exclusive,
with the detail member of each
.PN XLeaveWindowEvent
structure set to
.PN NotifyVirtual .
.IP \- 5
An
.PN EnterNotify
event on window B with the detail member of the 
.PN XEnterWindowEvent
structure set to
.PN NotifyInferior .
.RE
.IP \(bu 5
When the pointer moves from window A to window B, and B is an inferior of A,
the X server generates:
.RS
.IP \- 5
A
.PN LeaveNotify
event on window A
with the detail member of the
.PN XLeaveWindowEvent
structure set to
.PN NotifyInferior .
.IP \- 5
An
.PN EnterNotify
event on each window between window A and window B exclusive, with the 
detail member of each 
.PN XEnterWindowEvent
structure set to
.PN NotifyVirtual . 
.IP \- 5
An
.PN EnterNotify
event on window B with the detail member of the 
.PN XEnterWindowEvent
structure set to
.PN NotifyAncestor .
.RE
.IP \(bu 5
When the pointer moves from window A to window B, and window C is their least
common ancestor, the X server generates:
.RS
.IP \- 5
A
.PN LeaveNotify
event on window A
with the detail member of the
.PN XLeaveWindowEvent
structure set to 
.PN NotifyNonlinear .
.IP \- 5
A
.PN LeaveNotify
event on each window between window A and window C exclusive,
with the detail member of each
.PN XLeaveWindowEvent
structure set to
.PN NotifyNonlinearVirtual .
.IP \- 5
An
.PN EnterNotify
event on each window between window C and window B exclusive, 
with the detail member of each
.PN XEnterWindowEvent
structure set to
.PN NotifyNonlinearVirtual .
.IP \- 5
An
.PN EnterNotify
event on window B with the detail member of the 
.PN XEnterWindowEvent
structure set to 
.PN NotifyNonlinear .
.RE
.IP \(bu 5
When the pointer moves from window A to window B on different screens, the X
server:
.RS
.IP \- 5
Generates a
.PN LeaveNotify
event on window A
with the detail member of the
.PN XLeaveWindowEvent
structure set to 
.PN NotifyNonlinear .
.IP \- 5
If window A is not a root window,
it generates a
.PN LeaveNotify
event on each window above window A up to and including its root,
with the detail member of each
.PN XLeaveWindowEvent
structure set to 
.PN NotifyNonlinearVirtual .
.IP \- 5
If window B is not a root window,
it generates an
.PN EnterNotify
event on each window from window B's root down to but not including
window B, with the detail member of each
.PN XEnterWindowEvent
structure set to 
.PN NotifyNonlinearVirtual .
.IP \- 5
Generates an
.PN EnterNotify
event on window B with the detail member of the
.PN XEnterWindowEvent
structure set to 
.PN NotifyNonlinear .
.RE
.\".SH 3
.NH 4 
Grab and Ungrab Entry/Exit Event Processing
.XS
\*(SN Grab and Ungrab Entry/Exit Event Processing 
.XE
.LP
Pseudo-motion mode
.PN EnterNotify
and
.PN LeaveNotify
events are generated when a pointer grab activates or deactivates.
Events in which the pointer grab activates
are identified by
.PN XEnterWindowEvent
or
.PN XLeaveWindowEvent
structures whose mode member is set to 
.PN NotifyGrab .
Events in which the pointer grab deactivates
are identified by
.PN XEnterWindowEvent
or
.PN XLeaveWindowEvent
structures whose mode member is set to 
.PN NotifyUngrab .
See the discussion of 
.PN XGrabPointer
discussed in Chapter 7.
.IP \(bu 5
When a pointer grab activates but after any initial warp into a confine_to
window, and before generating any actual
.PN ButtonPress
event that activates the grab, with G the grab_window for the grab and P the
window the pointer is in, the X server:
.RS
.IP \- 5
Generates
.PN EnterNotify
and
.PN LeaveNotify
events (see Section 8.4.2.1)
with the mode members of the 
.PN XEnterWindowEvent
and
.PN XLeaveWindowEvent
structures set to 
.PN NotifyGrab .
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
.IP \(bu 5
When a pointer grab deactivates but after generating any actual
.PN ButtonRelease
event that deactivates the grab, with G the grab_window for the grab and P the
window the pointer is in, the X server:
.RS
.IP \- 5
Generates
.PN EnterNotify
and
.PN LeaveNotify
events (see Section 8.4.2.1)
with the mode members of the
.PN XEnterWindowEvent
and
.PN XLeaveWindowEvent
structures set to 
.PN NotifyUngrab .
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
.NH 3
Input Focus Events
.XS
\*(SN Input Focus Events 
.XE
.LP
.IN "Event Processing" "FocusIn"
.IN "Event Processing" "FocusOut"
This section describes the processing that occurs for the input focus events
.PN FocusIn
and
.PN FocusOut .
The X server can report
.PN FocusIn
or
.PN FocusOut
events to clients wanting information about when the input focus changes.
The input focus is where the keyboard input goes.
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 determines the window that
receives keyboard input.
Clients may need to know when the input focus changes.
This is often used to control highlighting of areas of the
screen.
See also the focus member enter/exit events in Section 8.4.2.
This can occur when a client calls
.PN XGrabKeyboard
and
.PN XUngrabKeyboard .
.LP
To receive
.PN FocusIn
and
.PN FocusOut
events in a client application, you pass a window ID 
and
.PN FocusChangeMask
as the event_mask argument to
.PN XSelectInput .
.LP
The members of the
.PN XFocusInEvent
and
.PN XFocusOutEvent
structures associated with these events are window, mode,
and detail.
The window member is set to the window ID of the window on which the
.PN FocusIn
or
.PN FocusOut
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, 
while grabbed focus events,
focus events
when a grab activates, or focus events when a grab deactivates.
The X server can set the mode member to the corresponding constants
.PN NotifyNormal ,
.PN NotifyWhileGrabbed ,
.PN NotifyGrab ,
or
.PN NotifyUngrab .
The following sections discuss how the X server processes normal focus
events, while grabbed focus events, and grab activate/deactivate focus events.
.LP
All 
.PN FocusOut
events caused by a window unmap are generated after any
.PN UnmapNotify
event, but the ordering of 
.PN FocusOut
events with respect to
generated 
.PN EnterNotify ,
.PN LeaveNotify ,
.PN VisibilityNotify ,
and
.PN Expose
events is not constrained by the X protocol.
.LP
Depending on the event mode,
the detail member is set to indicate the notify detail and can be one of these
constants:
.PN NotifyAncestor ,
.PN NotifyVirtual ,
.PN NotifyInferior ,
.PN NotifyNonlinear ,
.PN NotifyNonlinearVirtual ,
.PN NotifyPointer ,
.PN NotifyPointerRoot ,
or
.PN NotifyDetailNone ,
.\".SH 3
.NH 4 
Normal and While Grabbed Focus Event Processing
.XS
\*(SN Normal and While Grabbed Focus Event Processing 
.XE
.LP
Normal focus events are identified by
.PN XFocusInEvent
or
.PN XFocusOutEvent
structures whose mode member is set to 
.PN NotifyNormal .
While grabbed focus events are identified by
.PN XFocusInEvent
or
.PN XFocusOutEvent
structures whose mode member is set to 
.PN NotifyWhileGrabbed .
The X server processes normal focus and while grabbed focus events according to 
the following
focus scenarios:
.IP \(bu 5
When the focus moves from window A to window B, 
and A is an inferior of B with the
pointer in window P, the
X server:
.RS
.IP \- 5
Generates a
.PN FocusOut
event on window A with the detail member of the
.PN XFocusOutEvent
structure set to 
.PN NotifyAncestor . 
.IP \- 5
Generates a
.PN FocusOut
event on each window between window A and window B exclusive,
with the detail member of each
.PN XFocusOutEvent
structure set to 
.PN NotifyVirtual .
.IP \- 5
Generates a
.PN FocusIn
event on window B with the detail member of the 
.PN XFocusOutEvent
structure set to 
.PN NotifyInferior .
.IP \- 5
If window P is an inferior of window B,
but window P is not window A or an inferior of window A,
it generates a
.PN FocusIn
event on each window below window B down to and including window P, 
with the detail member of each 
.PN XFocusInEvent
structure set to 
.PN NotifyInferior .
.RE
.IP \(bu 5
When the focus moves from window A to window B, and B is an inferior of A with
the pointer in window P, the X server:
.RS
.IP \- 5
If window P is an inferior of window A,
but P is not A, or an inferior of window B, or an ancestor of B,
it generates a
.PN FocusOut
event on each window from window P up to but not including window A (in
that order), with the detail member of each 
.PN XFocusOutEvent
structure set to  
.PN NotifyPointer .
.IP \- 5
Generates a
.PN FocusOut
event on window A
with the detail member of the
.PN XFocusOutEvent
structure set to  
.PN NotifyInferior . 
.IP \- 5
Generates a
.PN FocusIn
event on each window between window A and window B exclusive, with the 
detail member of each 
.PN XFocusInEvent
structure set to  
.PN NotifyVirtual . 
.IP \- 5
Generates a
.PN FocusIn
event on window B with the detail member of the 
.PN XFocusInEvent
structure set to  
.PN NotifyAncestor
.RE
.IP \(bu 5
When the focus moves from window A to window B, and window C is their least
common ancestor, and with the pointer in window P, the X server:
.RS
.IP \- 5
If window P is an inferior of window A,
it generates a
.PN FocusOut
event on each window from window P up to but not including window A, 
with the detail member of the 
.PN XFocusOutEvent
structure set to  
.PN NotifyPointer .
.IP \- 5
Generates a
.PN FocusOut
event on window A
with the detail member of the
.PN XFocusOutEvent
structure set to  
.PN NotifyNonlinear .
.IP \- 5
Generates a
.PN FocusOut
event on each window between window A and window C exclusive,
with the detail member of each
.PN XFocusOutEvent
structure set to  
.PN NotifyNonlinearVirtual .
.IP \- 5
Generates a
.PN FocusIn
event on each window between C and B exclusive,
with the detail member of each
.PN XFocusInEvent
structure set to  
.PN NotifyNonlinearVirtual .
.IP \- 5
Generates a
.PN FocusIn
event on window B with the detail member of the 
.PN XFocusInEvent
structure set to  
.PN NotifyNonlinear .
.IP \- 5
If window P is an inferior of window B, it generates a
.PN FocusIn
event on each window below window B down to and including window P, 
with the detail member of the 
.PN XFocusInEvent
structure set to  
.PN NotifyPointer .
.RE
.IP \(bu 5
When the focus moves from window A to window B on different screens with the
pointer in window P, the X server:
.RS
.IP \- 5
If window P is an inferior of window A, it generates a
.PN FocusOut
event on each window from window P up to but not including window A, 
with the detail member of each 
.PN XFocusOutEvent
structure set to  
.PN NotifyPointer .
.IP \- 5
Generates a
.PN FocusOut
event on window A
with the detail member of the
.PN XFocusOutEvent
structure set to  
.PN NotifyNonlinear .
.IP \- 5
If window A is not a root window,
it generates a
.PN FocusOut
event on each window above window A up to and including its root, 
with the detail member of each
.PN XFocusOutEvent
structure set to  
.PN NotifyNonlinearVirtual .
.IP \- 5
If window B is not a root window,
it generates a
.PN FocusIn
event on each window from window B's root down to but not including
window B, with the detail member of each
.PN XFocusInEvent
structure set to  
.PN NotifyNonlinearVirtual .
.IP \- 5
Generates a
.PN FocusIn
event on window B with the detail member of each 
.PN XFocusInEvent
structure set to  
.PN NotifyNonlinear .
.IP \- 5
If window P is an inferior of window B, it generates a
.PN FocusIn
event on each window below window B down to and including window P, 
with the detail member of each 
.PN XFocusInEvent
structure set to  
.PN NotifyPointer .
.RE
.IP \(bu 5
You may have specified the focus window by passing 
.PN PointerRoot
(or
.PN None ),
when you called the function
.PN XSetInputFocus .
(See Chapter 7.)
When the focus moves from window A to 
.PN PointerRoot
(events sent to the window under the pointer)
or
.PN None 
(discard), with the pointer in window P,  the X server:
.RS
.IP \- 5
If window P is an inferior of window A, it generates a
.PN FocusOut
event on each window from window P up to but not including window A, 
with the detail member of each 
.PN XFocusOutEvent
structure set to  
.PN NotifyPointer .
.IP \- 5
Generates a
.PN FocusOut
event on window A with the detail member of the
.PN XFocusOutEvent
structure set to
.PN NotifyNonlinear .
.IP \- 5
If window A is not a root window,
it generates a
.PN FocusOut
event on each window above window A up to and including its root, 
with the detail member of each
.PN XFocusOutEvent
structure set to
.PN NotifyNonlinearVirtual .
.IP \- 5
Generates a
.PN FocusIn
event on the root window of all screens with the detail member of each
.PN XFocusInEvent
structure set to
.PN NotifyPointerRoot
(or
.PN NotifyDetailNone ).
.IP \- 5
If the new focus is
.PN PointerRoot ,
it generates a
.PN FocusIn
event on each window from window P's root down to and including window P, 
with the detail member of each
.PN XFocusInEvent
structure set to
.PN NotifyPointerRoot .
.RE
.IP \(bu 5
When the focus moves from 
.PN PointerRoot
(events sent to the window under the pointer)
or
.PN None 
to window A, with the pointer in window P, the X server: 
.RS
.IP \- 5
If the old focus is
.PN PointerRoot ,
it generates a
.PN FocusOut
event on each window from window P up to and including window P's root, 
with the detail member of each
.PN XFocusOutEvent
structure set to
.PN NotifyPointerRoot
(in order).
.IP \- 5
Generates a
.PN FocusOut
event on all root windows 
with the detail member of each
.PN XFocusOutEvent
structure set to
.PN NotifyPointerRoot 
(or
.PN NotifyDetailNone ).
.IP \- 5
If window A is not a root window,
it generates a
.PN FocusIn
event on each window from window A's root down to but not including window A,
with the detail member of each
.PN XFocusInEvent
structure set to
.PN NotifyNonlinearVirtual .
.IP \- 5
Generates a
.PN FocusIn
event on window A 
with the detail member of the 
.PN XFocusInEvent
structure set to  
.PN NotifyNonlinear .
.IP \- 5
If window P is an inferior of window A, it generates a
.PN FocusIn
event on each window below window A down to and including window P, 
with the detail member of each 
.PN XFocusInEvent
structure set to  
.PN NotifyPointer .
.RE
.IP \(bu 5
When the focus moves from 
.PN PointerRoot
(events sent to the window under the pointer)
to
.PN None
(or vice versa), 
with the pointer in window P, the X server:
.RS
.IP \- 5
If the old focus is
.PN PointerRoot ,
it generates a
.PN FocusOut
event on each window from window P up to and including window P's root, 
with the detail member of each
.PN XFocusOutEvent
structure set to
.PN NotifyPointerRoot .
.IP \- 5
Generates a
.PN FocusOut
event on all root windows
with the detail member of each 
.PN XFocusOutEvent
structure set to either
.PN NotifyPointerRoot
or
.PN NotifyDetailNone . 
.IP \- 5
Generates a
.PN FocusIn
event on all root windows 
with the detail member of each
.PN XFocusInEvent
structure set to
.PN NotifyDetailNone 
or
.PN NotifyPointerRoot .
.IP \- 5
If the new focus is
.PN PointerRoot ,
it generates a
.PN FocusIn
event on each window from window P's root down to and including window P, 
with the detail member of each
.PN XFocusInEvent
structure set to
.PN NotifyPointerRoot .
.RE
.\".SH 3
.NH 4 
Focus Events Generated by Grabs
.XS
\*(SN Focus Events Generated by Grabs 
.XE
.LP
Focus events in which the keyboard grab activates
are identified by
.PN XFocusInEvent
or
.PN XFocusOutEvent
structures whose mode member is set to 
.PN NotifyGrab .
Focus events in which the keyboard grab deactivates
are identified by
.PN XFocusInEvent
or
.PN XFocusOutEvent
structures whose mode member is set to 
.PN NotifyUngrab .
See the discussion of
.PN XGrabKeyboard
in Chapter 7.
.IP \(bu 5
When a keyboard grab activates but before generating any actual 
.PN KeyPress
event that activates the grab
with G the grab_window and F the current focus, the X server:
.RS
.IP \- 5
Generates 
.PN FocusIn
and
.PN FocusOut
events (as discussed in the previous section), 
with the mode members of the 
.PN XFocusInEvent
and
.PN XFocusOutEvent
structures set to 
.PN NotifyGrab .
These events are generated
as if the focus were to change from
F to G.
.RE
.IP \(bu 5
When a keyboard grab deactivates but after generating any actual
.PN KeyRelease
event that deactivates the grab with G the grab_window and F the current focus,
the X server:
.RS
.IP \- 5
Generates 
.PN FocusIn
and
.PN FocusOut
events (as discussed in the previous section),
with the mode members of the 
.PN XFocusInEvent
and
.PN XFocusOutEvent
structures set to
.PN NotifyUngrab .
These events are generated
as if the focus were to change from
G to F.
.RE
.NH 3
Key Map State Notification Event Processing
.XS
\*(SN Key Map State Notification Event Processing 
.XE
.LP
This section discusses the processing that occurs for the key map state notification
event
.PN KeymapNotify .
The X server reports
.PN KeymapNotify
events to clients wanting information about changes in the keyboard state.
To receive
.PN KeymapNotify
events in a client application, you pass a window ID 
and
.PN KeymapStateMask
as the event_mask argument to
.PN XSelectInput .
The X server generates this event immediately after every
.PN EnterNotify
and
.PN FocusIn
event.
.LP
The members of the
.PN XKeymapEvent
structure associated with this event are window and
key_vector.
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 one bit 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.
.NH 3
Exposure Event Processing
.XS
\*(SN Exposure Event Processing 
.XE
.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.
Many other implementations will feel 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 or piece of a region becomes visible). 
Therefore, the X server sends exposure events 
describing the window and the region of the window that has been exposed.
A trivial client application usually redraws the entire window. 
A more
sophisticated client application redraws only the exposed region.
The following sections discuss the processing that occurs for the
.PN Expose ,
.PN GraphicsExpose ,
and
.PN NoExpose
exposure events. 
.\".SH 3
.NH 4
Expose Event Processing
.XS
\*(SN Expose Event Processing 
.XE
.LP
.IN "Event Processing" "Expose"
The X server can report
.PN Expose
events to clients wanting information about when the contents of window regions
have been lost.
The circumstances in which the X server generates
.PN Expose
events are not as definite as those for other events.
However, the X server never generates
.PN Expose
events on windows whose class you specified as
.PN InputOnly .
The X server can generate
.PN Expose
events when no valid contents are available for regions of a window
and either the regions are visible, or 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
.PN Always
or
.PN WhenMapped .
The regions are decomposed into an (arbitrary) set of rectangles,
and an
.PN Expose
event is generated for each rectangle.
The X server guarantees to report contiguously for any given window
all of the regions exposed by some action that causes Exposure events, 
such as raising a window.
.LP
To receive
.PN Expose
events in a client application, you pass a window ID 
and
.PN ExposureMask
as the event_mask argument to
.PN XSelectInput .
.LP
The members of the
.PN XExposeEvent
structure associated with this event are window, x, y, width, height, 
and count.
The window member is set to the window ID of the exposed (damaged) window.
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
.PN Expose
events that are to follow.
If count is set to 0 (zero), no more
.PN Expose
events follow for this window.
However, if count is set to nonzero, at least count 
.PN Expose 
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
.PN Expose
events with nonzero counts and perform full redisplays
on events with zero counts.
.\" .SH 3
.NH 4
GraphicsExpose and NoExpose Event Processing
.XS
\*(SN GraphicsExpose and NoExpose Event Processing 
.XE
.LP
.IN "Event Processing" "GraphicsExpose"
.IN "Event Processing" "NoExpose"
The X server can report
.PN GraphicsExpose
events to clients wanting information about when a destination region could not
be computed during a graphics request.
Clients initiate a graphics request by calling 
.PN XCopyArea
or
.PN XCopyPlane .
The X server generates this event whenever a destination region could not be
computed due to 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).
.LP
The X server generates
.PN NoExpose
events whenever a graphics request that might
produce a
.PN GraphicsExpose
event does not produce any.
In other words, the client is really asking for a
.PN GraphicsExpose
event but instead receives a
.PN NoExpose
event.
.LP
To receive
.PN GraphicsExpose
or
.PN NoExpose
events in a client application, you must first set the graphics_exposures
member of the 
.PN XGCValues 
structure for the associated graphics context to 
.PN True .
You did this when you created the graphics context by calling 
.PN XCreateGC .
Or, you may have set the graphics_exposures member after creating the graphics context
by calling
.PN XSetGraphicsExposures .
See Chapter 5 for more information on these functions. 
.LP
The structures associated with these event types are
.PN XGraphicsExposeEvent
and
.PN XNoExposeEvent ,
and they have these common members: drawable, major_code, and minor_code.
The drawable member is set to the drawable ID of the destination region on 
which the copy request
was to be performed.
The major_code member is set to the graphics request initiated by the client,
and can be either
.PN X_CopyArea
or
.PN X_CopyPlane .
If
.PN X_CopyArea ,
a call to
.PN XCopyArea
initiated the request.
If
.PN X_CopyPlane ,
a call to
.PN XCopyPlane
initiated the request.
These constants are defined in 
.Pn < X11/Xproto.h >.
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, but may be used by an extension.
.LP
The 
.PN XGraphicsExposeEvent
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
.PN GraphicsExpose
events to follow.
If count is set to 0 (zero), no more
.PN GraphicsExpose
events follow for this window.
However, if count is set to nonzero, at least that many more, and
possibly more,
.PN GraphicsExpose
events are to follow for this window.
.NH 3
Window State Notification Event Processing
.XS
\*(SN Window State Notification Event Processing 
.XE
.LP
The following sections
discuss the processing that occurs for these window state
notification events:
.PN CirculateNotify ,
.PN ConfigureNotify ,
.PN CreateNotify ,
.PN DestroyNotify ,
.PN GravityNotify ,
.PN MapNotify ,
.PN MappingNotify ,
.PN ReparentNotify,
.PN UnmapNotify ,
and
.PN VisibilityNotify . 
.\" .SH 3
.NH 4
CirculateNotify Event Processing
.XS
\*(SN CirculateNotify Event Processing 
.XE
.LP
.IN "Event Processing" "CirculateNotify"
The X server can report
.PN CirculateNotify
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
.PN XCirculateSubwindows ,
.PN XCirculateSubwindowsUp ,
or
.PN XCirculateSubwindowsDown .
.LP
To receive this event type in a client application,
you pass the window ID and
.PN StructureNotifyMask
as the event_mask argument to
.PN XSelectInput .
You can also receive this event type by passing the parent window ID
and
.PN SubstructureNotifyMask .
.LP
The members of the
.PN XCirculateEvent
structure associated with this event are event, window, and
place.
The event member is set to the window ID of the window on which the
.PN CirculateNotify
event was generated.
This is the window used by the X server to report the event.
The window member is set to the window ID of the window that was restacked.
The place member is set to the window's position after the restack occurs, and
is either
.PN PlaceOnTop
or
.PN PlaceOnBottom .
If
.PN PlaceOnTop ,
the window is now on top of all siblings.
If
.PN PlaceOnBottom ,
the window is now below all siblings.
.\" .SH 3
.NH 4
ConfigureNotify Event Processing
.XS
\*(SN ConfigureNotify Event Processing 
.XE
.LP
.IN "Event Processing" "ConfigureNotify"
The X server can report
.PN ConfigureNotify
events to clients wanting information about actual changes to a window's
state, that is, size, position, border, stacking order.
The X server generates this event type whenever one of the following configure 
window requests made by a client application actually completes:
.IP \(bu 5
A window's size, position, border, 
and stacking order is reconfigured as a result
of calling
.PN XConfigureWindow .
.IP \(bu 5
The window's position in the stacking order is changed as a result of calling
.PN XLowerWindow ,
.PN XRaiseWindow ,
or
.PN XRestackWindows .
.IP \(bu 5
A window is moved as a result of calling
.PN XMoveWindow .
.IP \(bu 5
A window's size is changed as a result of calling
.PN XResizeWindow .
.IP \(bu 5
A window's size and location is changed as a result of calling
.PN XMoveResizeWindow .
.IP \(bu 5
A window is mapped and its position in the stacking order is changed
as a result of calling
.PN XMapRaised .
.IP \(bu 5
A window's border width is changed as a result of calling
.PN XSetWindowBorderWidth .
.LP
To receive this event type in a client application,
you pass the window ID and
.PN StructureNotifyMask
as the event_mask argument to
.PN XSelectInput .
You can also receive this event type by passing the parent window ID and
.PN SubstructureNotifyMask .
.LP
The members of the
.PN XConfigureEvent
structure associated with this event are event, window, x, y, width,
height, border_width, above, and override_redirect.
The event member is set to the window ID of the window on which the
.PN ConfigureNotify
event was generated.
This is the window used by the X server to report the event.
The window member is set to the window ID of the window whose size, position, 
border, and/or stacking
order was changed.
.LP
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.
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.
.LP
The above member is set to the window ID of the sibling window and is used 
for stacking operations.
If the X server sets this member to
.PN None ,
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 the ID of a sibling window, the X server
places the window whose state was changed on top of this sibling window.
.LP
The override_redirect member is set to the constant you specified for the
override_redirect member of the
.PN XSetWindowAttributes
structure when you created the window or changed its attributes.
This constant is either
.PN True
or
.PN False .
Window manager clients normally should ignore this event if the 
override_redirect member
is
.PN True .
.\" .SH 3
.NH 4
CreateNotify Event Processing
.XS
\*(SN CreateNotify Event Processing 
.XE
.LP
.IN "Event Processing" "CreateNotify"
The X server can report
.PN CreateNotify
events to clients wanting information about creation of windows.
The X server generates this event whenever a client
application creates a window by calling
.PN XCreateWindow
or
.PN XCreateSimpleWindow .
.LP
To receive this event type in a client application, 
you pass the window ID of the parent window and 
.PN SubstructureNotifyMask
as the event_mask argument to
.PN XSelectInput .
.LP
The members of the
.PN XCreateWindowEvent
structure associated with this event are parent, window, 
x, y, width, height, border_width, and override_redirect.
The parent member is set to the window ID of the created window's parent.
The window member specifies the window ID of the created window.
The x and y members are set to the created window's coordinates relative 
to the inside of the
parent window's borders 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 a nonzero value.
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 constant you specified for the
override_redirect member of the
.PN XSetWindowAttributes
structure when you created the window or changed its attributes.
This constant is either
.PN True
or
.PN False .
Window manager clients normally should ignore this event if the override_redirect member
is
.PN True .
.\" .SH 3
.NH 4
DestroyNotify Event Processing 
.XS
\*(SN DestroyNotify Event Processing 
.XE
.LP
.IN "Event Processing" "DestroyNotify"
The X server can report
.PN DestroyNotify
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
.PN XDestroyWindow
or
.PN XDestroySubwindows .
.LP
The ordering of the 
.PN DestroyNotify 
events is such that for any given window, 
.PN DestroyNotify
is generated on all inferiors of the window
before being generated on the window itself.  
The ordering among
siblings and across subhierarchies is not otherwise constrained
by the X protocol.
.LP
To receive this event type in a client application, you pass the window ID of the parent 
window and 
.PN SubstructureNotifyMask
as the event_mask argument to
.PN XSelectInput .
You can also receive this event type by passing
the window ID of the window and 
.PN SubstructureNotifyMask .
.LP
The members of the
.PN XDestroyWindowEvent
structure associated with this event are event and window.
The event member is set to the window ID of the window on which the
.PN DestroyNotify
event was generated.
This is the window used by the X server to report the event.
The window member is set to the window ID of the window that is destroyed.
.\" .SH 3
.NH 4
GravityNotify Event Processing
.XS
\*(SN GravityNotify Event Processing 
.XE
.LP
.IN "Event Processing" "GravityNotify"
The X server can report
.PN GravityNotify
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
.PN XConfigureWindow ,
.PN XMoveResizeWindow ,
and
.PN XResizeWindow . 
.LP
To receive this event type in a client application, you pass the window ID of the 
window and
.PN StructureNotifyMask
as the event_mask argument to
.PN XSelectInput .
You can also receive this event type by passing the window ID of the parent window
and
.PN SubstructureNotifyMask .
.LP
The members of the
.PN XGravityEvent
structure associated with this event are event, window, x, and y.
The event member is set to the window ID of the window on which the
.PN GravityNotify
event was generated.
This is the window used by the X server to report the event.
The window member is set to the window ID of 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.
.\" .SH 3
.NH 4
MapNotify Event Processing
.XS
\*(SN MapNotify Event Processing 
.XE
.LP
.IN "Event Processing" "MapNotify"
The X server can report
.PN MapNotify
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
.PN XMapWindow ,
.PN XMapRaised ,
or
.PN XMapSubwindows .
.LP
To receive this event type, you pass the window ID of the window 
and
.PN StructureNotifyMask
as the event_mask argument to
.PN XSelectInput .
You can also receive this event type by passing the window ID of a parent window and
.PN SubstructureNotifyMask .
.LP
The members of the
.PN XMapEvent
structure associated with this event are event, window, and
override_redirect.
The event member is set to the window ID of the window on which the
.PN MapNotify
event was generated.
This is the window used by the X server to report the event.
The window member is set to the window ID of the window that was mapped.
The override_redirect member is set to the constant you specified for the
override_redirect member of the
.PN XSetWindowAttributes
structure, when you created the window or changed its attributes.
This constant is either
.PN True
or
.PN False .
Window manager clients normally should ignore this event 
if the override_redirect member is
.PN True ,
because these events usually are generated from pop-ups,
which override structure control.
.NH 4
MappingNotify Event Processing
.XS
\*(SN MappingNotify Event Processing 
.XE
.LP
.IN "Event Processing" "MappingNotify"
The X server reports
.PN MappingNotify
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 calls:
.IP \(bu 5
.PN XSetModifierMapping
to indicate which keycodes are to be used as modifiers. 
The status reply must be
.PN MappingSuccess .
.IP \(bu 5
.PN XChangeKeyboardMapping
to change the keyboard mapping. 
.IP \(bu 5
.PN XSetPointerMapping
to set the pointer mapping.
The status reply must be
.PN MappingSuccess .
.LP
See sections 7.8 and 7.9 for a discussion of these functions.
.LP
The members of the
.PN XMappingEvent
structure associated with this event are window (not used and only present to
aid certain toolkits), request, first_keycode, and count.
The request member is set to indicate the kind of mapping change that occurred,
and can be one of the constants
.PN MappingModifier ,
.PN MappingKeyboard ,
.PN MappingPointer .
If
.PN MappingModifier ,
the specified keycodes are used as modifiers.
If
.PN MappingKeyboard ,
the keyboard mapping is changed.
If
.PN MappingPointer ,
the pointer button mapping is set. 
The first_keycode and count members are set only if the request member was set to
.PN MappingKeyboard .
If this is the case, these members are set to numbers that indicate the range of
altered keyboards.
Thus, the number in first_keycode represents the first number in the range, 
and the number in count represents the last number in the range. 
.LP
To update the client application's knowledge of the keyboard,
you should call
.PN XRefreshKeyboardMapping . 
See Chapter 10 for a discussion of this function.
.\" .SH 3
.NH 4
ReparentNotify Event Processing
.XS
\*(SN ReparentNotify Event Processing 
.XE
.LP
.IN "Event Processing" "ReparentNotify"
The X server can report
.PN ReparentNotify
events to clients wanting information about changing a window's parent.
The X server generates this event whenever a client
application calls
.PN XReparentWindow 
and the window is actually reparented.
.LP
To receive this event type in a client application, you pass the window ID of the 
old or the new parent window and 
.PN SubStructureNotifyMask
as the event_mask argument to
.PN XSelectInput .
You can also receive this event type by passing the window ID and
.PN StructureNotifyMask .
.LP
The members of the
.PN XReparentEvent
structure associated with this event are event, window, parent, x, y, and
override_redirect.
The event member is set to the window ID of the window on which the
.PN ReparentNotify
event was generated and on which you requested notification by using
.PN XSelectInput .
This is the window used by the X server to report the event.
The window member is set to the window ID of the window that was reparented.
The parent member is set to the window ID of 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 constant you specified for the
override_redirect member of the
.PN XSetWindowAttributes
structure when you created the window or changed its attributes.
This constant is either
.PN True
or
.PN False .
Window manager clients normally should ignore this event if the override_redirect member
is
.PN True .
.\" .SH 3
.NH 4
UnmapNotify Event Processing
.XS
\*(SN UnmapNotify Event Processing 
.XE
.LP
.IN "Event Processing" "UnmapNotify"
The X server can report
.PN UnmapNotify
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 by calling
.PN XUnmapWindow 
or
.PN XUnmapSubwindows .
.LP
To receive this event type, you pass the window ID and
.PN StructureNotifyMask
as the event_mask argument to
.PN XSelectInput .
You can also receive this event type by passing the window ID of the parent window and
.PN SubstructureNotifyMask .
.LP
The members of the
.PN XUnmapEvent
structure associated with this event are event, window, and
from_configure.
The event member is set to the window ID of the window on which the
.PN UnmapNotify
event was generated and on which you requested notification by using
.PN XSelectInput .
This is the window used by the X server to report the event.
The window member is set to the window ID of the window that was unmapped.
The from_configure member is set to
.PN True 
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
.PN UnmapGravity .
.NH 4
VisibilityNotify Event Processing
.XS
\*(SN VisibilityNotify Event Processing 
.XE
.LP
.IN "Event Processing" "VisibilityNotify"
The X server can report
.PN VisibilityNotify
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
.PN InputOnly .
X ignores any subwindows in this computation.
.LP
All 
.PN VisibilityNotify
events caused by a hierarchy change are generated
after any hierarchy event (
.PN UnmapNotify , 
.PN MapNotify , 
.PN ConfigureNotify ,
.PN GravityNotify ,
.PN CirculateNotify )
caused by that change.  Any
.PN VisibilityNotify
event on a given window is generated before any
.PN Expose 
events on that window, but it is not required that all
.PN VisibilityNotify
events on all windows be generated before all 
.PN Expose
events on all windows.  
The ordering of 
.PN VisibilityNotify
events with
respect to 
.PN FocusOut , 
.PN EnterNotify ,
and 
.PN LeaveNotify
events is not
constrained by the X protocol.
.LP
To receive this event type in a client application, you pass the window ID of the
window and 
.PN VisibilityChangeMask
as the event_mask argument to
.PN XSelectInput .
.LP
The members of the
.PN XVisibilityEvent
structure associated with this event are window and state. 
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
one of the constants
.PN VisibilityUnobscured ,
.PN VisibilityPartiallyObscured ,
or
.PN VisibilityFullyObscured .
The X server ignores all of a window's subwindows
when determining the visibility state of the window and processes 
.PN VisibilityNotify
events according to the following:
.IP \(bu 5
When the window changes state from partially or fully obscured or not viewable 
to viewable and completely unobscured,
the X server generates the event with the state member of the
.PN XVisibilityEvent
structure set to
.PN VisibilityUnobscured.
.IP \(bu 5
When the window changes state from viewable and completely unobscured or 
from not viewable to viewable and partially obscured,
the X server generates the event with the state member of the
.PN XVisibilityEvent
structure set to
.PN VisibilityPartiallyObscured .
.IP \(bu 5
When the window changes state from viewable and completely unobscured or 
viewable and partially obscured or from not viewable to viewable and 
fully obscured,
the X server generates the event with the state member of the
.PN XVisibilityEvent
structure set to
.PN VisibilityFullyObscured .
.NH 3
Structure Control Event Processing
.XS
\*(SN Structure Control Event Processing 
.XE
.LP
The following sections
discuss the processing that occurs for these structure control events:
.PN CirculateRequest ,
.PN ConfigureRequest ,
.PN MapRequest ,
and
.PN ResizeRequest .
These are only generated when clients have structure control enabled
and are generally only of interest to window managers.
.\" .SH 3
.NH 4 
CirculateRequest Event
.XS
\*(SN CirculateRequest Event 
.XE
.LP
.IN "Event Processing" "CirculateRequest"
The X server can report
.PN CirculateRequest
events to clients wanting information about when another client initiates a circulate
window request on
a specified parent window. 
The X server generates this event type whenever a client initiates a circulate
window request on a parent window, and a window actually needs to be restacked. 
The client initiates a circulate window request on the parent window by calling
.PN XCirculateSubwindows ,
.PN XCirculateSubwindowsUp ,
or
.PN XCirculateSubwindowsDown .
.LP
To receive this event type in a client application, you pass the window ID of the
parent window and
.PN SubstructureRedirectMask
as the event_mask argument to
.PN XSelectInput .
In the future, 
the circulate window request for the specified window will not be not executed,
and, thus, the window's position in the stack is not changed.
For example, suppose a client application calls
.PN XCirculateSubwindowsUp
to raise a specified window to the top of the stack.
If you had selected
.PN SubstructureRedirectMask
on the parent window, the X server reports to you a
.PN CirculateRequest
event and does not raise the specified window to the top of the stack.
.LP
The members of the
.PN XCirculateRequestEvent
structure associated with this event are parent, window, and place.
The parent member is set to the window ID of the parent window.
The window member is set to the window ID of the window to be restacked.
The place member is set to what the new position in the stacking order should
be,
and is either
.PN PlaceOnTop
or
.PN PlaceOnBottom .
If
.PN PlaceOnTop ,
the window should be on top of all siblings.
If
.PN PlaceOnBottom ,
the window should be below all siblings.
.\" .SH 3
.NH 4
ConfigureRequest Event
.XS
\*(SN ConfigureRequest Event
.XE
.LP
.IN "Event Processing" "ConfigureRequest"
The X server can report
.PN ConfigureRequest
events to clients wanting information about when another client initiates a configure
window request on
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 client initiates
a configure window request on a window by calling
.PN XConfigureWindow ,
.PN XLowerWindow ,
.PN XRaiseWindow ,
.PN XMapRaised ,
.PN XMoveResizeWindow ,
.PN XMoveWindow ,
.PN XResizeWindow ,
.PN XRestackWindows ,
or
.PN XSetWindowBorderWidth .
.LP
To receive this event type in a client application, 
you pass the window ID of the parent window and
.PN SubstructureRedirectMask
as the event_mask argument to
.PN XSelectInput .
It is generated when a
.PN ConfigureWindow
request is issued on the window by another client.
For example, suppose a client application calls
.PN XLowerWindow
to lower a window.
If you had selected
.PN SubstructureRedirectMask 
on the parent window, and if the override_redirect member 
of the
.PN XSetWindowAttributes 
structure associated with the specified window is set to
.PN False ,
the X server reports a
.PN ConfigureRequest
event to you and does not lower the specified window.
.LP
The members of the
.PN XConfigureRequestEvent
structure associated with this event are parent, window, x, y, width,
height, border_width, above, detail, and value_mask.
The parent member is set to the window ID of the parent window.
The window member is set to the window ID whose size, position, border width, 
and/or stacking order is to be reconfigured.
The x and y members are set to the coordinates relative to the parent window's
origin and indicate the desired position of the upper left outside corner of 
the reconfigured window.
The width and height members are set to the desired inside size of the reconfigured 
window (not including the border) and are always a nonzero value.
The border_width member is set to the desired width of the 
reconfigured window's border, in pixels.
The above member is set to the window ID of the sibling window and is used 
for stacking operations.
If the X server sets this member to 
.PN None ,
then the reconfigured window should be placed on the bottom of the stack
with respect to sibling windows.
However, if this member is set to the ID of a sibling window, the reconfigured
window wants to be placed on top of this sibling window.
.LP
If not given in the request,
the detail member is set to 
.PN Above .
This member could also be set to the constants
.PN Below ,
.PN TopIf ,
.PN BottomIf ,
or
.PN Opposite .
The value_mask member is set to indicate which components were specified in
the request.
The value_mask and the corresponding values are reported as given in the request.
.\" .SH 3
.NH 4
MapRequest Event
.XS
\*(SN MapRequest Event 
.XE
.LP
.IN "Event Processing" "MapRequest"
The X server can report
.PN MapRequest
events to clients wanting information about another client's desire to map (place)
windows.
A window is considered mapped when a map window request completes.
The X server generates this event whenever a client initiates a map window
request on an unmapped window whose override_redirect member is set to
.PN False .
Clients initiate map window requests by calling
.PN XMapWindow ,
.PN XMapRaised ,
or
.PN XMapSubwindows .
.LP
To receive this event type in a client application, you pass the window ID of the
parent window and
.PN SubstructureRedirectMask
as the event_mask argument to
.PN XSelectInput .
This means another client's attempts to map the window by calling one of
the map window request functions will fail, and you will be sent a 
.PN MapRequest
instead.
For example, suppose a client application calls
.PN XMapWindow
to map a window.
If you (usually your window manager) had selected
.PN SubstructureRedirectMask 
on the parent window, and if the override_redirect member 
of the
.PN XSetWindowAttributes 
structure associated with the specified window is set to
.PN False ,
the X server reports to you a
.PN MapRequest
event 
and does not map the specified window.
Thus, this event gives your window manager client the ability to control the placement
of subwindows.
.LP
The members of the
.PN XMapRequestEvent
structure associated with this event are parent and window.
The parent member is set to the window ID of the parent window.
The window member is set to the window ID of the window to be mapped.
.NH 4
ResizeRequest Event Processing
.XS
\*(SN ResizeRequest Event Processing 
.XE
.LP
.IN "Event Processing" "ResizeRequest"
The X server can report
.PN ResizeRequest
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
.PN XConfigureWindow ,
.PN XResizeWindow ,
or
.PN XMoveResizeWindow .
.LP
To receive this event type in a client application, you pass a window ID 
and 
.PN ResizeRedirect
as the event_mask argument to
.PN XSelectInput .
You will be sent the 
.PN ResizeRedirect
event, and any attempts to change the size by other clients will fail.
.LP
The members of the
.PN XResizeRequestEvent
structure associated with this event are window, width, and height.
The window member is set to the window ID of the window whose size another 
client attempted to change.
The width and height members are set to the inside size of the window, not 
including the border.
.NH 3
Color Map State Notification Event Processing
.XS
\*(SN Color Map State Notification Event Processing
.XE
.LP
.IN "Event Processing" "ColormapNotify"
This section discusses the processing that occurs for the color map notification
event
.PN ColormapNotify .
The X server can report
.PN ColormapNotify
events to clients wanting information about when the color map changes and when a
color map is installed or uninstalled. 
The X server generates this event type whenever a client application:
.IP \(bu 5
Changes the colormap member of the
.PN XSetWindowAttributes
structure by 
calling
.PN XChangeWindowAttributes
or
.PN XFreeColormap . 
.IP \(bu 5
Installs or uninstalls the color map by calling
.PN XInstallColormap
or
.PN XUninstallColormap .
.LP
To receive this event type in a client application, you pass the window ID
of the window and
.PN ColormapChangeMask
to the event_mask argument of
.PN XSelectInput .
.LP
The members of the
.PN XColormapEvent
structure associated with this event are window, color map, new, and state.
The window member is set to the window ID of the window whose associated 
color map is changed, installed, or uninstalled.
For a color map that is changed by a call to
.PN XChangeWindowAttributes , 
installed, or uninstalled,
the colormap member is set to the color map resource ID of the color map 
associated with the window. 
For a color map that is changed by a call to
.PN XFreeColormap ,
the colormap member is set to
.PN None .
The new member is set to indicate whether the color map for the specified window was
changed or installed or uninstalled, and it can be either
.PN True
or
.PN False .
If
.PN True ,
the color map was changed.
If
.PN False ,
the color map was installed or uninstalled.
The state member is always set to indicate whether the color map is installed or
uninstalled, and it can be one of the corresponding constants
.PN ColormapInstalled
or
.PN ColormapUninstalled .
.NH 3
Client Communication Event Processing
.XS
\*(SN Client Communication Event Processing 
.XE
.LP
The following sections discuss the processing
that occurs for these client communication events:
.PN ClientMessage ,
.PN PropertyNotify ,
.PN SelectionClear ,
.PN SelectionNotify ,
and
.PN SelectionRequest .
.\".SH 3
.NH 4
ClientMessage Event Processing
.XS
\*(SN ClientMessage Event Processing 
.XE
.LP
.IN "Event Processing" "ClientMessage"
The X server generates
.PN ClientMessage
events only when a client calls the function
.PN XSendEvent .
See Section 8.8 in this chapter for information on how to
send an event.
.LP
The members of the
.PN XClientMessageEvent
structure associated with this event are window, message_type, format, and
data.
The window member is set to the window ID of the window to which the event was sent.
The message_type member is set to an atom that indicates how the data is
to 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 message_type or 
data members.
.NH 4
PropertyNotify Event Processing
.XS
\*(SN PropertyNotify Event Processing 
.XE
.LP
.IN "Event Processing" "PropertyNotify"
The X server can report
.PN PropertyNotify
events to clients wanting information about property changes for a specified window.
A property consists of an atom name, an atom type, a data format, and some
property data.
Generated with state
.PN PropertyNewValue
when a property of the window is changed using
.PN XChangeProperty
or
.PN XRotateProperties
(even when adding zero-length data using
.PN XChangeProperty )
and when replacing all or part of a property with identical data using
.PN XChangeProperty
or XRotateProperties .
Generated with state
.PN PropertyDeleted
when a property of the window is deleted using
.PN XDeleteProperty
or
.PN XGetProperty ,
if the delete argument is 
.PN True .
.LP
See Chapter 4 for more information.
.LP
To receive this event type, you pass the window ID and
.PN PropertyChangeMask
as the event_mask argument to
.PN XSelectInput .
.LP
The members of the
.PN XPropertyEvent
structure associated with this event are window, atom, time, and state. 
The window member is set to the window ID of 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 it can be one of the corresponding constants
.PN PropertyNewValue
or
.PN PropertyDelete .
.\" .SH 3
.NH 4
SelectionClear Event Processing
.XS
\*(SN SelectionClear Event Processing 
.XE
.LP
The X server reports
.PN SelectionClear
events to the current owner of a selection.
The X server generates this event type on the window losing ownership of the
selection to a new owner.
This sequence of events could occur whenever a client calls
.PN XSetSelectionOwner .
See Section 4.4 for information on this function and on selections.
.LP
The members of the
.PN XSelectionClearEvent
structure associated with this event are 
window, selection, and time.
The window member is set to the ID of the window losing ownership of the selection.
The selection member is set to the selection atom.
The time member is set to the last change time recorded for the 
selection.
The owner member is the window that was specified by the current owner
in its
.PN XSetSelectionOwner
call.
.\" .SH 3
.NH 4
SelectionRequest Event Processing
.XS
\*(SN SelectionRequest Event Processing 
.XE
.LP
The X server reports
.PN SelectionRequest
events to the owner of a selection.
The X server generates this event whenever a client 
requests a selection conversion by calling 
.PN XConvertSelection ,
and the specified selection is owned by a window.
.LP
The members of the
.PN XSelectionRequestEvent
structure associated with this event are owner, requestor, selection, 
target, property, and time.
The owner member is set to the window ID of the window owning the selection.
The owner member is the window that was specified by the current owner
in its
.PN XSetSelectionOwner
call.
The requestor member is set to the window ID of the 
window requesting the selection.
The selection member is set to the atom that indicates which 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 the atom or the property or 
.PN None .
The time member is set to the time
and is a timestamp, expressed in milliseconds, or 
.PN CurrentTime 
from the
.PN ConvertSelection
request.
.LP
The client whose window owns the selection
should do the following:
.IP \(bu 5
Convert the selection based on the atom contained in the target member.
.IP \(bu 5
If a property was specified (that is, the property member is set), 
the client should store the result as that property on
the requestor window and then send a
.PN SelectionNotify
event to the requestor by calling 
.PN XSendEvent
with an empty event-mask,
that is the event should be sent to the creator of the requestor window.
.IP \(bu 5
If the selection cannot be converted as requested, the client should send a
.PN SelectionNotify
event with the property set to
.PN None .
.NH 4
SelectionNotify Event Processing 
.XS
\*(SN SelectionNotify Event Processing 
.XE
.LP
This event is generated by the X server in response to a
.PN XConvertSelection 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
.PN XSendEvent .
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 (indicated with the property member set to
.PN None ).
.LP
If
.PN None
is specified as the property,
the owner should choose a property name,
store the result as that property on the requestor window,
and then send a 
.PN SelectionNotify
to give that actual property name.
.LP
The members of the
.PN XSelectionEvent
structure associated with this event are requestor, selection, target, 
property, and time.
The requestor member is set to the window ID of the window associated with
the requestor of the selection.
The selection member is set to the atom that indicates the kind of selection.
For example, PRIMARY is used for the primary selection.
The target member is set to the atom that indicates the desired 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 none were possible, then
the property member will be set to
.PN None .
The time member is set to the time in which the conversion took place and
can be a timestamp, expressed in milliseconds, or 
.PN CurrentTime .
.\" .SH 3
.NH 2
Selecting Events
.XS
\*(SN Selecting Events 
.XE
.LP
There are two ways to select the events you want reported to your client
application.
One way is to set the event_mask member of the
.PN XSetWindowAttributes
structure when you call
.PN XCreateWindow
and
.PN XChangeWindowAttributes .
See Chapter 3 for a discussion of
these functions.
Another way is to 
use
.PN XSelectInput . 
.IN "XSelectInput"
Section 8.4
discussed the processing that 
occurs for each event type associated with the event mask you pass to
.PN XSelectInput .
.IN "XSelectInput" "" "@DEF@"
.FD 0
.so ./Xsrc/XSelectInput.f
.FN	
.so ./Xsrc/display.a
.so ./Xsrc/w.a
Client applications interested in an event for a particular window pass that
window's ID.
.so ./Xsrc/eventmask.a
.LP 
.so ./Xdescrip/XSelectInput.d
Initially, X will not report any of these events.
See Section 8.3 for a discussion of these event masks.
.LP
Events are reported relative to a window.
If a window is not interested in an event, it usually propagates to
the closest ancestor that is interested,
unless the do_not_propagate mask prohibits it.
.IN "Event" "propagation"
.LP
.IN "XSelectInput"
A call to 
.PN XSelectInput
overrides any previous call to 
.PN XSelectInput
for the
same window from the same client but not for other clients.
Multiple clients can select for the same events on the same window
with the following restrictions:
.IP \(bu 5
Multiple clients can select events on the same window because their event masks
are disjoint.
After the X server generates an event, it reports it
to all interested clients.
.IP \(bu 5
Only one client at a time can select
.PN CirculateRequest ,
.PN ConfigureRequest ,
or
.PN MapRequest
events, which are associated with
the event mask
.PN SubstructureRedirectMask . 
.IP \(bu 5
Only one client at a time can select
a
.PN ResizeRequest
event, which is associated with
the event mask
.PN ResizeRedirectMask . 
.IP \(bu 5
Only one client at a time can select a 
.PN ButtonPress 
event, which is associated with
the event mask
.PN ButtonPressMask .
.LP
The server reports the event to to all interested clients.
.LP
If a client passes both 
.PN ButtonPressMask 
and 
.PN ButtonReleaseMask 
for a specified window,
a 
.PN ButtonPress
event in that window will automatically grab the
mouse until all buttons are released and 
.PN ButtonRelease 
events are sent to windows as
described for 
.PN XGrabPointer .
.IN "XGrabPointer"
This ensures that a window will see the 
.PN ButtonRelease
event
corresponding to the 
.PN ButtonPress
event,
even though the mouse may have exited the window in the meantime.
.LP
If a client passes 
.PN PointerMotionMask , 
the X server sends 
.PN MotionNotify
events independent of the state
of the pointer buttons.  
If, instead, the client passes one or more of 
.PN Button1MotionMask ,
.PN Button2MotionMask , 
.PN Button3MotionMask , 
.PN Button4MotionMask ,
.PN Button5MotionMask , 
the X server generates
.PN MotionNotify 
events only when one or more of the specified buttons is depressed.
These are used to request 
.PN MotionNotify 
events only when particular buttons
are held down.
.LP
.ds fd .PN XSelectInput
.so ./Xsrc/errsent.com
.PN BadValue
and
.PN BadWindow 
errors.
.NH 2
Handling the Output Buffer
.XS
\*(SN Handling the Output Buffer
.XE
.LP
Under some circumstances,
many event functions discuss in the remainder of this chapter
also flush the output buffer.
.\".NH 3
.\"Flushing the Output Buffer
.\".XS
.\"\*(SN lushing the Output Buffer 
.\".XE
.LP
The output buffer is an area used by the Xlib library to store requests.
The functions described in this section can flush the input queue
if the function would block or not return an event.
That is, all requests residing in the output buffer that
have not yet been sent are transmitted to the X server.
Conversely, these functions differ in the additional tasks they might perform.
For example,
.PN XSync
not only flushes the output buffer, but it can also discard all events on
the event queue.
The following paragraphs describe the 
.PN XFlush 
and
.PN XSync 
functions.
.LP
.sp
To flush the output buffer, use 
.PN XFlush .
.IN "XFlush" "" "@DEF@"
.FD 0
.so ./Xsrc/XFlush.f
.FN
.so ./Xsrc/display.a
.LP
.so ./Xdescrip/XFlush.d
Most client applications need not use this function because the output
buffer is automatically flushed the next time an event or reply is read from
the output buffer by a call to
.PN XPending ,
.PN XNextEvent ,
or
.PN XWindowEvent .
.IN "XPending"
.IN "XNextEvent"
.IN "XWindowEvent"
.LP
.sp
To flush the output buffer and then wait until all requests have been processed,
use 
.PN XSync .
.IN "XSync" "" "@DEF@"
.FD 0
.so ./Xsrc/XSync.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/discard.a
.LP
.so ./Xdescrip/XSync.d
Any errors generated must be handled by the the error handler.
For each error event received and processed by the X server,
.PN XSync
calls the client application's
.PN XError
routine.
.IN "XError"
Any events generated by the server are enqued into the the library's 
event queue.
.LP
Finally, if you passed the value 0 to the discard argument,
.PN XSync
does not discard the events on the queue.
If you passed the value 1, this function discards all events on the queue,
including those events that were on the queue before
.PN XSync
was called.
Client applications seldom need to call
.PN XSync .
.NH 2
Event Queue Management
.LP
Xlib maintains an event queue.
However, the operating system may be buffering data in its network connection
that is not yet read into the event queue.
The following paragraphs describe the
.PN XEventsQueued
and
.PN XPending
functions.
.LP
.sp
To check the number of events in the event queue, use
.PN XEventsQueued .
.IN "XEventsQueued" "" "@DEF@"
.FD 0
.so ./Xsrc/XEvntQue.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/mode_queue.a
.LP
.so ./Xdescrip/XEvntQue.d
.LP
.PN XEventsQueued 
always returns immediately without I/O if there are events already in the 
queue.
.PN XEventsQueued 
with mode 
.PN QueuedAfterFlush 
is identical in behavior to
.PN XPending .
.PN XEventsQueued 
with mode 
.PN QueuedAlready 
is identical to the
.PN XQLength 
function (see Chapter 2).
.LP
.sp
To return the number of events that are pending, use 
.PN XPending .
.IN "XPending" "" "@DEF@"
.FD 0
.so ./Xsrc/XPending.f
.FN	
.so ./Xsrc/display.a
.LP
.so ./Xdescrip/XPending.d
(You remove events from the queue by calling 
.PN XNextEvent 
or
.PN XWindowEvent .)
.IN "XNextEvent"
.IN "XWindowEvent"
.IN "XPending"
.IN "Unix System Call" "select"
.LP
.PN XPending
is identical to 
.PN XEventsQueued
with the mode 
.PN QueuedAfterFlush .
.NH 2
Manipulating the Event Queue
.XS
\*(SN Manipulating the Event Queue 
.XE
.LP
Xlib provides functions that let you manipulate the event queue
The next three sections discuss how to:
.IP \(bu 5
Obtain events, in order, and remove them from the queue.
.IP \(bu 5
Peek at events in the queue without removing them.
.IP \(bu 5
Obtain events that match the event mask or the arbitrary
functions you provide.
.NH 3
Returning the Next Event
.XS
\*(SN Returning the Next Event
.XE
.LP
.sp
To get the next event and remove it from the queue, use
.PN XNextEvent .
.IN "XNextEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XNextEvent.f
.FN
.so ./Xsrc/display.a
.ds fd .PN XNextEvent
.so ./Xsrc/event2.a
.LP
.so ./Xdescrip/XNextEvent.d
If the event queue is empty, 
.PN XNextEvent
flushes the output buffer and blocks until an event is received.
For example, if a
.PN CreateNotify
event is at the head of the queue,
this function
removes it and then
copies the structure
.PN XCreateWindowEvent
into
.PN XEvent .
.LP
.sp
To peek at the event queue, use
.PN XPeekEvent .
.IN "XPeekEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XPeekEvent.f
.FN
.so ./Xsrc/display.a
.ds fd .PN XPeekEvent
.so ./Xsrc/event2.a
.LP
.so ./Xdescrip/XPeekEvent.d
If the queue is empty, 
.PN XPeekEvent
flushes the output buffer and blocks until an event is received.
It then copies the event into the client-supplied
.PN XEvent
structure without removing it from the event queue.
For example, if a
.PN CreateNotify
event is at the head of the queue,
this function
peeks at it but does not remove it and then
copies the structure
.PN XCreateWindowEvent
into
.PN XEvent .
.IN "QLength"
You can use the 
.PN QLength
macro to determine if there are any events to peek at.
For further information,
see Chapter 2.
.NH 3
Selecting Events Using a Predicate Procedure
.XS
\*(SN Selecting Events Using a Predicate Procedure
.XE
.LP
Each of the functions discussed in this section requires you to
pass a predicate procedure that determines if the event matches the one
specified in the corresponding function.
Your predicate procedure must decide only if the event is useful
and must not call Xlib functions.
In particular,
it is called from inside the event routine,
which must be locked so that the event queue is consistent in a 
multi-threaded environment.
.LP
The predicate procedure and its associated arguments are:
.FD 0
.so ./Xsrc/Predicate.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/event_ptr.a
.so ./Xsrc/arg_ptr.a
.LP
The predicate procedure is called once for each
event in the queue until it finds a match between the event in the queue and
the event specified by the corresponding function.
After finding a match, the predicate procedure must return 
.PN True
or 
.PN False
if it did not find a match. 
.LP
.sp
To check the event queue for the specified
event and, if the events match, remove the event from the queue, use
.PN XIfEvent .
.IN "XIfEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XIfEvent.f
.FN
.so ./Xsrc/display.a
.ds fd .PN XIfEvent
.so ./Xsrc/event.a
.so ./Xsrc/predicate.a
.so ./Xsrc/args.a
.LP
The
.PN XIfEvent
function completes only when the specified predicate
procedure returns a nonzero (true) for an event, 
which indicates an event on the queue matches the specified event.
This predicate procedure is also called each time an event is added 
to the queue.
.PN XIfEvent
flushes the output buffer if it blocks waiting for an event.
.PN XIfEvent
removes the event from the queue and, when it returns, copies the structure
into the client-supplied
.PN XEvent
structure.
.LP
.sp
To check the event queue for the specified event without blocking, use
.PN XCheckIfEvent .
.IN "XCheckIfEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XCkIfEvent.f
.FN
.so ./Xsrc/display.a
.ds fd .PN XCheckIfEvent
.so ./Xsrc/event.a
.so ./Xsrc/predicate.a
.so ./Xsrc/args.a
.LP
When the predicate procedure finds a match,
.PN XCheckIfEvent
copies the matched event into the client-supplied
.PN XEvent
structure and returns 
.PN True 
(This event is removed from the queue.)
If the predicate procedure finds no match,
.PN XCheckIfEvent
returns
.PN False 
and flushes the output buffer.
All earlier events stored in the queue are not discarded.
.LP
.sp
To check the event queue for the specified event
but not remove the event from the queue, use
.PN XPeekIfEvent .
.IN "XPeekIfEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XPkIfEvent.f
.FN
.so ./Xsrc/display.a
.ds fd .PN XPeekIfEvent
.so ./Xsrc/event.a
.so ./Xsrc/predicate.a
.so ./Xsrc/args.a
.LP
.so ./Xdescrip/XPkIfEvent.d
This predicate procedure is called each time an event is added to the queue.
After the predicate procedure finds a match,
.PN XPeekIfEvent
copies the matched event into the client-supplied
.PN XEvent
structure without removing the event from the queue.
.PN XPeekIfEvent
flushes the output buffer if it blocks waiting for an event.
.NH 3
Selecting Events Using a Window or Event Mask
.XS
\*(SN Selecting Events Using a Window or Event Mask
.XE
.LP
These functions let you to select events by window or event types,
which lets you to process events out of order.
See Section 8.3. for a discussion of the valid event mask names.
.LP
.sp
To remove the next event that matches both a window and an event mask, use
.PN XWindowEvent .
.IN "XWindowEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XWindowEvent.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w.a
This is the window whose next matched event you want to remove.
.so ./Xsrc/eventmask.a
.ds fd .PN XWindowEvent
.so ./Xsrc/event.a
.LP
.so ./Xdescrip/XWindowEvent.d
The other events stored in the queue are not discarded.
If the event you requested is not in the queue,
.PN XWindowEvent
flushes the output buffer and blocks until one is received.
.LP
.sp
To remove the next event that matches both the passed window and the passed
mask, use
.PN XCheckWindowEvent .
.IN "XCheckWindowEvent"
This function is similar to
.PN XWindowEvent ,
except it never blocks, and it returns a Boolean indicating if the
event was returned.
.IN "XCheckWindowEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XChkWinEvnt.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w.a
This is the window whose next matched event you want to remove.
.so ./Xsrc/eventmask.a
.ds fd .PN XCheckWindowEvent
.so ./Xsrc/event.a
.LP
.so ./Xdescrip/XChkWinEvnt.d
The other events stored in the queue are not discarded.
If the event you requested is not available,
.PN XCheckWindowEvent
flushes the output buffer and returns
.PN False .
.LP
.sp
To remove the next event that matches an event mask, use
.PN XMaskEvent .
.IN "XMaskEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XMaskEvent.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/eventmask.a
.ds fd .PN XMaskEvent
.so ./Xsrc/event.a
.LP
.so ./Xdescrip/XMaskEvent.d
The other events stored in the queue are not discarded.
If the event you requested is not in the queue,
.PN XMaskEvent
flushes the output buffer and blocks until one is received.
.LP
.sp
To remove the next event, if any, that matches an event mask, use
.PN XCheckMaskEvent .
.IN "XCheckMaskEvent"
This function is similar to 
.PN XMaskEvent ,
except that it never blocks, and it returns a Boolean indicating
if the event was returned.
.IN "XCheckMaskEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XChkMskEvnt.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/eventmask.a
.ds fd .PN XCheckMaskEvent
.so ./Xsrc/event.a
.LP
.so ./Xdescrip/XChkMskEvnt.d
The other events stored in the queue are not discarded.
If the event you requested is not available,
.PN XCheckMaskEvent
flushes the output buffer and returns 
.PN False .
.LP
.sp 
To return the next event in the queue that matches an event type, use
.PN XCheckTypedEvent .
.IN "XCheckTypedEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XChkTypEvnt.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/event_type.a
.ds fd .PN XCheckTypedEvent
.so ./Xsrc/event.a
.LP
.so ./Xdescrip/XChkTypEvnt.d
The other events in the queue are not discarded.
If the event is not available, 
.PN XCheckTypedEvent
flushes the output buffer and returns
.PN False .
.LP
.sp
To return the next matched event in the queue for the specified window, use
.PN XCheckTypedWindowEvent .
.IN "XCheckTypedWindowEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XChkTypWEvnt.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w.a
.so ./Xsrc/event_type.a
.ds fd .PN XCheckTypedWindowEvent
.so ./Xsrc/event.a
.LP
.so ./Xdescrip/XChkTypWEvnt.d
The other events in the queue are not discarded.
If the event is not avialable,
.PN XCheckTypedWindowEvent
flushes the output buffer and returns
.PN False .
.NH 2
Putting an Event Back onto the Queue
.XS
\*(SN Putting an Event Back onto the Queue 
.XE
.LP
To push an event back to the top of the event queue, use
.PN XPutBackEvent .
.IN "XPutBackEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XPutBckEvent.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/event_put.a
.LP 
.so ./Xdescrip/XPutBckEvent.d
This can be useful if you have read an event and then decide that you
would rather deal with it later.
There is no limit to how many times in succession you can call 
.PN XPutBackEvent .
.NH 2
Sending Events to Other Applications
.XS
\*(SN Sending Events to Other Applications
.XE
.LP
To send an event to a specified window, use
.PN XSendEvent .
.IN "XSendEvent"
This function is often used in selection processing.
For example, the owner of a selection should use
.PN XSendEvent
to send a
.PN SelectionNotify
event to a requestor when a selection has been converted and stored as a property.
.IN "XSendEvent" "" "@DEF@"
.FD 0
.so ./Xsrc/XSendEvent.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w.a
This is the window interested in the event, and is referred to as the destination
window.
You can pass the window ID or either
.PN PointerWindow 
or 
.PN InputFocus .
.so ./Xsrc/propagate.a
.so ./Xsrc/eventmask.a
.so ./Xsrc/event_send.a
.LP
The
.PN XSendEvent
function identifies the destination window, determines which clients should receive
the specified events, and ignores any active grabs.
This function requires you to pass an event mask.
See Section 8.3 for a discussion of the valid event mask names.
This function uses the w argument to identify the destination window as follows:
.IP \(bu 5
If you pass 
.PN PointerWindow 
to w, 
the destination window is the window that contains the pointer.
.IP \(bu 5
If you pass 
.PN InputFocus 
to w, and
if the focus window contains the pointer, 
the destination window is the window that contains the pointer. 
If the focus window does not contain the pointer, the destination window is
the focus window.
.LP
To determine which clients should receive the specified events,
.PN XSendEvent
uses the propagate argument as follows:
.IP \(bu 5
If propagate is 
.PN False ,
the event is sent to every client selecting on destination any of the event
types in the event_mask argument.
.IP \(bu 5
If propagate is 
.PN True , 
and no clients have selected on destination any of
the event types in event-mask, the destination is replaced with the
closest ancestor of destination for which some client has selected a
type in event-mask and for which no intervening window has that type in its
do_not_propagate_mask. 
If no such window exists or if the window is
an ancestor of the focus window and 
.PN InputFocus 
was originally specified
as the destination, the event is not sent to any clients.
Otherwise, the event is reported to every client selecting on the final
destination any of the types specified in event_mask.
.LP
The events in the
.PN XEvent
structure must be one of the core events or one of the events
defined by a loaded extension, so that the X server can correctly byte
swap the contents as necessary.  
The contents of the event are
otherwise unaltered and unchecked by the X server except to force send_event to
.PN True
in the forwarded event and to set the sequence number in the event correctly.
.LP
.PN XSendEvent
returns zero if the conversion-to-wire protocol failed, otherwise, nonzero.
.LP
.ds fd .PN XSendEvent
.so ./Xsrc/errsent.com
.PN BadValue
and 
.PN BadWindow 
errors.
.NH 2
Getting Pointer Motion History
.XS
\*(SN Getting Pointer Motion History
.XE
.LP
Many X server implementations will maintain a more precise
history of pointer motion between event notification.
The pointer position at each pointer hardware interrupt may be
stored into a buffer for later retrieval.
This is called the motion history buffer.
For example, a few applications, best
exemplified by paint programs,
want to have a precise history of where the pointer
traveled. 
However, this is highly excessive for most applications.
.LP
.sp
To get the motion history for a specified window and time, use
.PN XGetMotionEvents .
.IN "XGetMotionEvents" "" "@DEF@"
.FD 0
.so ./Xsrc/XGetMoEvents.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w.a
This is the window whose associated pointer motion events you want to retrieve.
.so ./Xsrc/startstop.a
.so ./Xsrc/nevents.a
.LP
.so ./Xdescrip/XGetMoEvents.d
If the start time is later than the stop time or if the start time is in the
future, no events are returned.
The return type for this function is a structure defined as follows:
.LP
.Ds 0
.TA .5i
.ta .5i
typedef struct {
	Time time;
	unsigned short x, y;
} XTimeCoord;
.De
.IN "XTimeCoord" "" "@DEF@"
.LP
The time member is set to the time, in milliseconds. 
The x and y members are set to the coordinates of the pointer and
are reported relative to the origin
of the specified window.
You should use
.PN XFree
to free the data returned from this call.
(See Section 2.4 for further information.)
.LP
.ds fd .PN XGetMotionEvents
.so ./Xsrc/errsent4.com
.PN BadWindow 
error.
.NH 2
Handling Error Events
.XS
\*(SN Handling Error Events 
.XE
.LP
Xlib provides functions with which you can:
.IP \(bu 5
Enable or disable synchronization
.IP \(bu 5
Use the default error handlers
.LP
The following sections discuss the functions associated with these tasks.
.NH 3
Enabling or Disabling Synchronization
.XS
\*(SN Enabling or Disabling Synchronization 
.XE
.LP
When debugging X applications, it can be very convenient to require the
library to behave synchronously, so that errors are reported at the time
they occur.
The routine below allows you to disable or enable synchronous behavior.
Note that graphics may occur dramatically slower when enabled
(30 or more times slower).
.IN "_Xdebug"
On UNIX-based systems,
there is also a global variable _Xdebug that if set
to nonzero before starting a program under a debugger will force
synchronous library behavior.
.LP
To enable or disable synchronization, use 
.PN XSynchronize .
.IN "Debugging" "Synchronous Mode"
.IN "XSynchronize" "" "@DEF@"
.FD 0
.so ./Xsrc/XSynchronize.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/onoff.a
.LP
The
.PN XSynchronize
function returns 
the previous after function.
If onoff is nonzero, 
.PN XSynchronize
turns on synchronous behavior.
A value of zero resets the state to off (disable synchronous behavior).
.LP
.so ./Xdescrip/XSyncHandler.d
.IN "XSetAfterFunction" "" "@DEF@"
.FD 0
.so ./Xsrc/XSyncHandler.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/func.a
.LP
The specified proc will be called with only a display pointer.
It returns the previous after function.
.NH 3
Using the Default Error Handlers
.XS
\*(SN Using the Default Error Handlers 
.XE
.LP
.IN "Debugging" "error handlers"
.IN "Error" "handlers"
There are two default error handlers in the library, one to handle
typically fatal conditions (for example, the connection to a display
server
dying due to a machine crash), and one to handle error events from the X server.
These error handlers can be changed to user-supplied routines if you
prefer your own error handling and can be changed as often as you like.
If either of these routines are passed a NULL pointer, it will
reinvoke the default handler.
The default action of the supplied routine is to print an explanatory
message and exit.
This section discusses:
.PN XSetErrorHandler ,
.PN XGetErrorText ,
.PN XGetErrorDatabaseText ,
.PN XDisplayName ,
and
.PN XSetIOErrorHandler .
.LP
.sp
To handle error events, use
.PN XSetErrorHandler .
.IN "XSetErrorHandler" "" "@DEF@"
.FD 0
.so ./Xsrc/XErrHndlr.f
.FN
.so ./Xsrc/handler.a
.LP 
The program's
supplied error hander generally is called by Xlib whenever an 
.PN XError
event is received.
It is not called on
.PN BadName
errors from
.PN OpenFont ,
.PN LookupColor ,
.PN AllocNamedColor ,
protocol requests, on
.PN BadFont
errors from a
.PN QueryFont
protocol request, or on 
.PN BadAlloc
or 
.PN BadAccess
errors.
These errors generally are reflected back to the program through the
procedureal interface.
.PN 
This is not assumed to be a fatal condition. 
It is acceptable for this procedure to return.
However, the error handler should not
perform any operations (directly or indirectly) on the display.
The fields of the 
.PN XErrorEvent
structure passed to 
.PN XError
.IN "Debugging" "error event"
should be interpreted as follows:
.sp
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef struct {
	int type
	Display *display;	/* Display the event was read from */
	unsigned long serial;		/* serial number of failed request */
	char error_code;	/* error code of failed request */
	char request_code;	/* Major op-code of failed request */
	char minor_code;	/* Minor op-code of failed request */
	XID resourceid;		/* resource id */
} XErrorEvent;
.De
.IN "XErrorEvent" "" "@DEF"
.IN "Serial Number"
.LP
The serial member is the number of requests starting
from one sent over the network connection
since it was opened. 
It is the number that was the
value of the request sequence number immediately after the 
failing call was made.  
The request_code member is a protocol representation of the name 
of the procedure that failed and are defined in 
.Pn < X11/X.h >.
The following error codes can be returned by the functions described in this
chapter:
.IN "Debugging" "error numbers"
.IN "Error" "codes"
.\".CP T 3
.\"Error Codes
.IN "BadAccess" "" "@DEF@"
.IN "BadAlloc" "" "@DEF@"
.IN "BadAtom" "" "@DEF@"
.IN "BadColor" "" "@DEF@"
.IN "BadCursor" "" "@DEF@"
.IN "BadDrawable" "" "@DEF@"
.IN "BadFont" "" "@DEF@"
.IN "BadGC" "" "@DEF@"
.IN "BadIDChoice" "" "@DEF@"
.TS H
l c
lw(1.75i) lw(4i).
_
.sp 6p
.TB
Error Code	Description
.sp 6p
_
.sp 6p
.TH
.R
T{
.PN BadAccess
T}	T{
A client attempted
to grab a key/button combination already grabbed by another client.
.sp 6p
A client attempted
to free a color map entry that it did not already allocate.
.sp 6p
A client attempted
to store into a read-only color map entry.
.sp 6p
A client attempted
to modify the access control list from other than the local 
(or otherwise authorized) host.
.sp 6p
A client attempted
to select an event type that another client has already selected, 
and, that at most, one client can
select at a time. 
T}
.sp 6p
T{
.PN BadAlloc
T}	T{
The server failed to allocate the requested resource or server memory.
T}
.sp 6p
T{
.PN BadAtom
T}	T{
A value for an Atom argument does not name a defined Atom.
T}
.sp 6p
T{
.PN BadColor
T}	T{
A value for a Colormap argument does not name a defined Colormap.
T}
.sp 6p
T{
.PN BadCursor
T}	T{
A value for a Cursor argument does not name a defined Cursor.
T}
.sp 6p
T{
.PN BadDrawable
T}	T{
A value for a Drawable argument does not name a defined Window or Pixmap.
T}
.sp 6p
T{
.PN BadFont
T}	T{
A value for a Font or GContext argument does not name a defined Font.
T}
.sp 6p
T{
.PN BadGC
T}	T{
A value for a GContext argument does not name a defined GContext.
T}
.sp 6p
T{
.PN BadIDChoice
T}	T{
The value chosen for a resource identifier is either not included in the 
range assigned to the client or is already in use.
Under normal circumstances this cannot occur and should be considered a server
or X Library error.
T}
.sp 6p
T{
.PN BadImplementation
T}	T{
The server does not implement some aspect of the request.
A server that generates this error for a core request is deficient.
As such, this error is not listed for any of the requests.
However, clients should be prepared to receive such errors 
and either handle or discard them.
T}
.sp 6p
T{
.PN BadLength
T}	T{
The length of a request is shorter or longer than that minimally required to 
contain the arguments.  This usually means an internal Xlib error.
T}
.sp 6p
T{
.PN BadMatch
T}	T{
In a graphics request,
the root and depth of the GC does not match that of the drawable.
.sp 6p
An InputOnly window is used as a Drawable.
.sp 6p
Some argument or pair of arguments has the correct type and range but fails 
to match in some other way required by the request.
.sp 6p
An InputOnly window locks this attribute.
.sp 6p
The values do not exist for an InputOnly window.
T}
.sp 6p
T{
.PN BadName
T}	T{
A font or color of the specified name does not exist.
T}
.sp 6p
T{
.PN BadPixmap
T}	T{
A value for a Pixmap argument does not name a defined Pixmap.
T}
.sp 6p
T{
.PN BadRequest
T}	T{
The major or minor opcode does not specify a valid request.
T}
.sp 6p
T{
.PN BadValue
T}	T{
Some numeric value falls outside the range of values accepted by the request.  
Unless a specific range is specified for an argument, the full range defined 
by the argument's type is accepted.  Any argument defined as a set of 
alternatives can generate this error.
T}
.sp 6p
T{
.PN BadWindow
T}	T{
A value for a Window argument does not name a defined Window.
T}
.sp 6p
_
.TE
.IN "BadImplementation" "" "@DEF@"
.IN "BadLength" "" "@DEF@"
.IN "BadMatch" "" "@DEF@"
.IN "BadName" "" "@DEF@"
.IN "BadPixmap" "" "@DEF@"
.IN "BadRequest" "" "@DEF@"
.IN "BadValue" "" "@DEF@"
.IN "BadWindow" "" "@DEF@"
.NT
The 
.PN BadAtom , 
.PN BadColor , 
.PN BadCursor , 
.PN BadDrawable , 
.PN BadFont , 
.PN BadGC , 
.PN BadPixmap , 
and 
.PN BadWindow
errors are also used when the argument type is extended by union with a set of
fixed alternatives (for example, 
.PN Window 
or 
.PN PointerRoot 
or 
.PN None .)
.NE
.sp
.LP
To obtain textual descriptions of the specified error code, use 
.PN XGetErrorText .
.IN "XGetErrorText" "" "@DEF@"
.IN "Debugging" "Error Message Strings"
.FD 0
.so ./Xsrc/XErrDescrip.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/code.a
.so ./Xsrc/buffer_err.a
.so ./Xsrc/length_err.a
.LP 
.so ./Xdescrip/XErrDescrip.d
It is recommended that you use this routine to obtain an error description 
because extensions to the Xlib library may define their own error codes 
and error strings.
.LP
.sp
To obtain error messages from the error data base, use
.PN XGetErrorDatabaseText .
.IN "XGetErrorDatabaseText" "" "@DEF@"
.FD 0
.so ./Xsrc/XGEDText.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/name_err.a
.so ./Xsrc/type_err.a
.so ./Xsrc/default.a
.so ./Xsrc/buffer_err.a
.so ./Xsrc/length_err.a
.LP
.so ./Xdescrip/XGEDText.d
Given a pair of strings as keys,
.PN XGetErrorDatabaseText
uses the resource manager to look up a string and returns in the
buffer argument.
Xlib uses this function internally to look up its error messages.
On a UNIX-based system,
the error message database is
.PN /usr/lib/XerrorDB .
.IN "Files" "/usr/lib/XerrorDB"
.LP
The name argument should generally be the name of your application.
The message argument should indicate which type of error message you want.
Three predefined sets of names are used by Xlib to report errors:
.IP XProtoError 1i
The protocol error number is used as a string for the message argument.
.IP XlibMessage 1i
These are the message strings that are used internally by the library.
.IP XRequestMajor 1i
The major request protocol number is used for the message argument.
If no string is found in the error data base,
the default_string is returned to the buffer argument.
.LP
.sp
To report an error to the user when the requested display does not exist, use
.PN XDisplayName .
.IN "XDisplayName" "" "@DEF@"
.FD 0
.so ./Xsrc/XDispName.f
.FN
.so ./Xsrc/string.a
.LP
.so ./Xdescrip/XDispName.d
If a NULL string is specified,
.PN XDisplayName
looks in the environment for the display and returns the display name that
the user was requesting.
This makes it easier to report to the user precisely which display the
program attempted to open when the initial connection attempt failed.
.LP
.sp
To handle fatal I/O errors, use
.PN XSetIOErrorHandler .
.IN "XSetIOErrorHandler" "" "@DEF@"
.FD 0
.so ./Xsrc/XIOErrHnd.f
.FN
.so ./Xsrc/handler.a
.LP
.so ./Xdescrip/XIOErrHnd.d
The program's
supplied error handler will be called by Xlib if any sort of system call error
occurs. 
For example, the connection to the server was lost.
This is assumed to
be a fatal condition. 
That is, the called routine should not return.
If the IO error handler
does return, the client process will exit.
.bp
