⟦257338886⟧

TextFile

.NH
Input Event Handling
.XS
Input Event Handling
.XE
.PP
.IN "Input Control"
.IN "Output" "Control"
Input from the window system is asynchronous, but the window
system never gives you information you did not ask for.
.IN "Definitions" "Event"
This input comes in the form of `events'.
There are keyboard, mouse button, window crossing, mouse motion,
exposure, unmap and focus change events.
.IN "File" "<X/Xlib.h>"
There are structures defined for these events in \fI<X/Xlib.h>\fP.
These may arrive at any time in the input stream even between the
time you send a command and get a reply.
Accordingly, the library queues any events received while waiting for
a reply for later use.
.PP
Only the type and window fields are defined for all types of events.
.IN "Definitions" "XEvent"
There is a generic structure declared called \fIXEvent\fP defined in
.IN "File" "<X/Xlib.h>"
\fI<X/Xlib.h>\fP.
Once the type has been determined, future references to the event structure
should be made using the structures declared in the library.
.FD
.IN "Definitions" "XCompressEvents"
.IN "XCompressEvents"
.IN "Definitions" "XExpandEvents"
.IN "XExpandEvents"
XCompressEvents()
.sp
XExpandEvents()
.FN
.PP
.IN "Event Compression"
If the X server sends multiple \fIMouseMoved\fP events without any other
intervening events or replies, the X library by default suppresses all but
the last such event.
.PP
If you want to see all events, you can call \fIXExpandEvents\fP
and the library
will supply all events without compression.
.NH 2
Event Handling
.PP
Before the window system will send an event, you must
request it.
You can request events in particular circumstances,
for example,
mouse motion when a mouse button is held down.
In this example,
mouse motion events are generated;
X does not distinguish between different types of mouse events,
even though you can request them under different circumstances.
.IN "Event" "Types"
.FD
.IN "Definitions" "XSelectInput"
.IN "XSelectInput"
XSelectInput (w, mask)
	Window w;
	int mask;	/* event mask */
.FN	
\fIXSelectInput\fP defines which input events the window is interested in.  If
a window is not interested in an event, it usually will propagate up to
the closest ancestor that is interested.
.IN "Event" "Propagation"
The bits of the mask are
.IN "File" "<X/X.h>"
defined in \fI<X/X.h>\fP:
.IN "Event Types" "EnterWindow"
.IN "Event Types" "LeaveWindow"
.IN "Event Types" "MouseMoved"
.IN "Event Types" "ExposeWindow"
.IN "Event Types" "ExposeRegion"
.IN "Event Types" "ExposeCopy"
.IN "Event Types" "ExposeRegion"
.IN "Event Types" "MouseMoved"
.IN "Event Types" "FocusChange"
.IN "Event Types" "UnmapWindow"
.IN "Event Types" "Keyboard"
.IN "Event Types" "Button"
.IN "Key Event"
.IN "Button Event"
.IN "EnterWindow Event"
.IN "LeaveWindow Event"
.IN "MouseMoved Event"
.IN "ExposeWindow Event"
.IN "ExposeRegion Event"
.IN "ExposeCopy Event"
.IN "MouseMoved Event"
.IN "Mouse" "Event"
.IN "FocusChange Event"
.in "UnmapWindow Event"
.LP
.TS
center,box;
c c c
___
l c l.
Request	Hex Code	Circumstances
KeyPressed	0x0001	keyboard key pressed
KeyReleased	0x0002	keyboard key released
ButtonPressed	0x0004	mouse button pressed
ButtonReleased	0x0008	mouse button released
EnterWindow	0x0010	mouse entering window
LeaveWindow	0x0020	mouse leaving window
MouseMoved	0x0040	mouse moves within window
ExposeWindow	0x0080	full window changed and/or exposed
ExposeRegion	0x0100	region of window exposed
ExposeCopy	0x0200	region exposed by XCopyArea
RightDownMotion	0x0400	mouse moves with right button down
MiddleDownMotion	0x0800	mouse moves with middle button down
LeftDownMotion	0x1000	mouse moves with left button down
UnmapWindow	0x2000	window is unmapped
FocusChange	0x4000	keyboard focus changed
.TE
Selecting \fIExposeRegion\fP also selects \fIExposeWindow\fP.
.PP
.IN "XSelectInput"
A call on \fIXSelectInput\fP overrides any previous call on \fIXSelectInput\fP
for the
same window, whether from the same client or a different one.
It is not
possible for two clients to each select events simultaneously
from the same window.
Initially,
no events will be generated on a window.
.PP
If a window has both \fIButtonPressed\fP and \fIButtonReleased\fP selected,
then
a \fIButtonPressed\fP event in that window will automatically `grab' the
mouse until all buttons are released, with events sent to windows as
.IN "XGrabMouse"
described for \fIXGrabMouse\fP.
This ensures that a window will see the release event
corresponding to the pressed event,
even though the mouse may have exited the window in the meantime.
.PP
If \fIMouseMoved\fP is selected, events will be sent independent of the state
of the mouse buttons.  If instead, one or more of \fIRightDownMotion\fP,
\fIMiddleDownMotion\fP, \fILeftDownMotion\fP is selected,
\fIMouseMoved\fP events will be
generated only when one or more of the specified buttons is depressed.
(There are NO events of type \fIRightDownMotion\fP, \fIMiddleDownMotion\fP, or
\fILeftDownMotion\fP; 
these are ways to request \fIMouseMoved\fP events only when particular buttons
are held down).
.FD
.IN "Definitions" "XFlush"
.IN "XFlush"
XFlush ()
.FN
\fIXFlush\fP sends (`flushes') all output requests that have been buffered but
not yet sent.
Flushing is done automatically the next time input is
.IN "XPending"
.IN "XNextEvent"
.IN "XWindowEvent"
read (with \fIXPending\fP, \fIXNextEvent\fP, or \fIXWindowEvent\fP),
so most clients
should not need to use this subroutine.
.FD
.IN "Definitions" "XSync"
.IN "XSync"
XSync (discard)
	int discard;	/* 0 or 1 */
.FN
\fIXSync\fP flushes the output buffer, then waits until all events and errors
resulting from previous calls have been received and processed by
the X server.
Events are placed on
the input queue.
.IN "XError"
The client's \fIXError\fP subroutine is called once for EACH
error received. 
.IN "XFlush"
Even fewer clients need to use this subroutine than \fIXFlush\fP.
.PP
If discard is true, \fIXSync\fP then discards all events on the input queue
(including those events that were on the queue before \fIXSync\fP was called).
.FD
.IN "Definitions" "XPending"
.IN "XPending"
int XPending ()
.FN	
\fIXPending\fP flushes the output buffer, then returns the number of input
events that have been received from the server, but not yet removed from
.IN "XNextEvent"
.IN "XWindowEvent"
the queue. (Events are removed from the queue by calling \fIXNextEvent\fP or
\fIXWindowEvent\fP, described below.)
.PP
.IN "XPending"
.IN "Unix System Call" "select"
You should always call \fIXPending\fP before doing a select(2) on the
file descriptor contained in the display structure.
The input you are trying to wait for may have already arrived and be
sitting in Xlib's queue.
.IN "XFlush"
Another strategy might be to call \fIXFlush\fP after
finding out if there are any unprocessed events on the queue by
.IN "Macro" "QLength"
using the \fIQLength()\fP macro before calling \fIselect(2)\fP.
.FD
.IN "Definitions" "XNextEvent"
XNextEvent (rep)
	XEvent *rep;	/* RETURN */
.FN
\fIXNextEvent\fP flushes the output buffer, then removes an input event from
.IN "XEvent"
the head of the queue and copies it into an \fIXEvent\fP
supplied by the caller.
If the queue is empty, \fIXNextEvent\fP blocks until an event is received.
.FD
.IN "Definitions" "XPutBackEvent"
.IN "XPutBackEvent"
XPutBackEvent(event)
	XEvent *event;
.FN
\fIXPutBackEvent\fP pushes an event back onto the head of the current
display's input queue.
This can be useful if you have read an event and then decide that you'd
rather deal with it later.
.FD
.IN "Definitions" "XPeekEvent"
.IN "XPeekEvent"
XPeekEvent (rep)
	XEvent *rep;	/* RETURN */
.FN
\fIXPeekEvent\fP flushes the output buffer, then peeks at an input event from
the head of the queue and copies it into an 
\fIXEvent\fP supplied by the caller,
without removing it from the input queue.
If the queue is empty, \fIXPeekEvent\fP blocks until an event is received.
.IN "Macro" "QLength()"
You can use the \fIQLength()\fP macro to determine if there are any
events to peek at.
.PP
Note:  We may add more specialized peek functions later as the need arises.
.FD
.IN "Definitions" "XWindowEvent"
.IN "XWindowEvent"
XWindowEvent (w, mask, rep)
	Window w;
	int mask;	/* event mask */
	XEvent *rep;	/* RETURN */
.FN
This subroutine is used to look for specific events from specific windows.
\fIXWindowEvent\fP flushes the output buffer, then removes the next event in
the queue which matches both the passed window and the passed \fImask\fP.
The
.IN "XEvent"
event is copied into an \fIXEvent\fP supplied by the caller.
Events earlier in
the queue are not discarded.  If no such event has been queued,
\fIXWindowEvent\fP blocks until one is received.
.FD
.IN "Definitions" "XMaskEvent"
.IN "XMaskEvent"
XMaskEvent (mask, rep)
	int mask;	/* event mask */
	XEvent *rep;	/* RETURN */
.FN
This subroutine is used to look for specific events.
\fIXMaskEvent\fP flushes the output buffer, then removes the next event in
the queue which matches the passed mask.  The
event is copied into an \fIXEvent\fP supplied by the caller.  Events earlier in
the queue are not discarded.  If no such event has been queued,
\fIXMaskEvent\fP blocks until one is received.
.FD
.IN "Definitions" "XCheckWindowEvent"
.IN "XCheckWindowEvent"
int XCheckWindowEvent (w, mask, rep)
	Window w;
	int mask;	/* event mask */
	XEvent *rep;	/* RETURN */
.FN
This subroutine is used to look for specific events from specific windows.
XCheckWindowEvent flushes the output buffer, then removes the next event in
the queue which matches both the passed window and the passed mask.  The
.IN "XEvent"
event is copied into an XEvent supplied by the caller and XCheckWindowEvent
returns 1.  Events earlier in the queue are not discarded.  If no such
event has been queued, XCheckWindowEvent immediately returns 0.
.FD
.IN "Definitions" "XCheckMaskEvent"
.IN "XCheckMaskEvent"
int XCheckMaskEvent (mask, rep)
	int mask;	/* event mask */
	XEvent *rep;	/* RETURN */
.FN
This subroutine is used to look for specific events.
XCheckMaskEvent flushes the output buffer, then removes the next event in
the queue which matches the passed mask.  The
event is copied into an XEvent supplied by the caller and
XCheckMaskEvent returns 1.  Events earlier in
the queue are not discarded.  If no such event has been queued,
XCheckMaskEvent immediately returns 0.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦257338886⟧ TextFile

Derivation

TextFile
