XtAppNextEvent(3Xt) XT FUNCTIONS XtAppNextEvent(3Xt)
NAME
XtAppNextEvent, XtAppPending, XtAppPeekEvent, XtAppProcess-
Event, XtDispatchEvent, XtAppMainLoop - query and process
events and input
SYNTAX
void XtAppNextEvent(XtAppContext app_context, XEvent
*event_return);
Boolean XtAppPeekEvent(XtAppContext app_context, XEvent
*event_return);
XtInputMask XtAppPending(XtAppContext app_context);
void XtAppProcessEvent(XtAppContext app_context, XtInputMask
mask);
Boolean XtDispatchEvent(XEvent *event);
void XtAppMainLoop(XtAppContext app_context);
ARGUMENTS
app_context
Specifies the application context that identifies
the application .
event Specifies a pointer to the event structure that is
to be dispatched to the appropriate event handler.
event_return
Returns the event information to the specified
event structure.
mask Specifies what types of events to process. The
mask is the bitwise inclusive OR of any combina-
tion of XtIMXEvent, XtIMTimer, XtIMAlternateInput,
and XtIMSignal. As a convenience, the X Toolkit
defines the symbolic name XtIMAll to be the bit-
wise inclusive OR of all event types.
DESCRIPTION
If the X event queue is empty, XtAppNextEvent flushes the X
output buffers of each Display in the application context
and waits for an event while looking at the other input
sources, timeout timeout values, and signal handlers and
calling any callback procedures triggered by them. This
wait time can be used for background processing (see Section
7.8).
If there is an event in the queue, XtAppPeekEvent fills in
the event and returns a nonzero value. If no X input is on
the queue, XtAppPeekEvent flushes the output buffer and
XFree86 Version 4.5.0 1
XtAppNextEvent(3Xt) XT FUNCTIONS XtAppNextEvent(3Xt)
blocks until input is available (possibly calling some
timeout callbacks in the process). If the input is an event,
XtAppPeekEvent fills in the event and returns a nonzero
value. Otherwise, the input is for an alternate input
source, and XtAppPeekEvent returns zero.
The XtAppPending function returns a nonzero value if there
are events pending from the X server, timer pending, or
other input sources pending. The value returned is a bit
mask that is the OR of XtIMXEvent, XtIMTimer, XtIMAlterna-
teInput, and XtIMSignal (see XtAppProcessEvent). If there
are no events pending, XtAppPending flushes the output
buffer and returns zero.
The XtAppProcessEvent function processes one timer, alter-
nate input, signal source, or X event. If there is nothing
of the appropriate type to process, XtAppProcessEvent blocks
until there is. If there is more than one type of thing
available to process, it is undefined which will get pro-
cessed. Usually, this procedure is not called by client
applications (see XtAppMainLoop). XtAppProcessEvent
processes timer events by calling any appropriate timer
callbacks, alternate input by calling any appropriate alter-
nate input callbacks, signal source by calling any appropri-
ate signal callbacks, and X events by calling XtDispatch-
Event.
When an X event is received, it is passed to XtDispatch-
Event, which calls the appropriate event handlers and passes
them the widget, the event, and client-specific data
registered with each procedure. If there are no handlers for
that event registered, the event is ignored and the
dispatcher simply returns. The order in which the handlers
are called is undefined.
The XtDispatchEvent function sends those events to the event
handler functions that have been previously registered with
the dispatch routine. XtDispatchEvent returns True if it
dispatched the event to some handler and False if it found
no handler to dispatch the event to. The most common use of
XtDispatchEvent is to dispatch events acquired with the
XtAppNextEvent procedure. However, it also can be used to
dispatch user-constructed events. XtDispatchEvent also is
responsible for implementing the grab semantics for
XtAddGrab.
The XtAppMainLoop function first reads the next incoming X
event by calling XtAppNextEvent and then it dispatches the
event to the appropriate registered procedure by calling
XtDispatchEvent. This constitutes the main loop of X Toolkit
applications, and, as such, it does not return unless
XtAppSetExitFlag is called. Applications are expected to
XFree86 Version 4.5.0 2
XtAppNextEvent(3Xt) XT FUNCTIONS XtAppNextEvent(3Xt)
exit in response to some user action. There is nothing spe-
cial about XtAppMainLoop; it is simply an loop that calls
XtAppNextEvent and then XtDispatchEvent, until XtAppGetExit-
Flag() returns true.
Applications can provide their own version of this loop,
which tests some global termination flag or tests that the
number of top-level widgets is larger than zero before cir-
cling back to the call to XtAppNextEvent.
SEE ALSO
X Toolkit Intrinsics - C Language Interface
Xlib - C Language X Interface
XFree86 Version 4.5.0 3