Name

XtAppPeekEvent — nondestructively examine the head of an application’s input queue. 

Synopsis

Boolean XtAppPeekEvent(app_context, event_return)

    XtAppContext app_context;
    XEvent ∗event_return;

Arguments

app_context
Specifies the application context that identifies the application.

event_return
Returns the event information from the head event structure in the queue.

Description

XtAppPeekEvent returns the value from the head of a given application’s input queue without removing input from the queue. 

If a server has queued an event for the application, XtAppPeekEvent fills in the event and returns a nonzero value.  It returns True if the event returned is an X event and False otherwise (i.e., if it is a Timer or alternate input event). 

If there is an event in the queue, XtAppPeekEvent fills in the event and returns True.  If no X input is on the queue, XtAppPeekEvent flushes the output buffers of each Display in the application context and blocks until input is available (possibly calling some timeout callbacks in the process).  If the next input is an event, XtAppPeekEvent fills in the event and returns True.  Otherwise, the input is for an alternate input source, and XtAppPeekEvent returns False. 

Programs rarely need this much control over the event dispatching mechanism.  Most programs use XtAppMainLoop. 

However, all event sources depend on idle time in the application to return to XtAppMainLoop where Xt can check to see if input is available from any of the various sources.  If an application has long calculations to make, the program may not return to XtAppMainLoop frequently enough to detect important input in a timely fashion.  The application itself should, if possible, suspend important calculations for a moment to check whether input is available.  Then it can determine whether to process the input before continuing or finish the calculation. 

To detect whether input from any input source is available, you can call XtAppPending. 

To find out what the first event in the queue contains, you can call XtAppPeekEvent.  This function returns an event structure without removing the event from Xlib’s queue. 

It is also possible to remove and process a single event.  XtAppProcessEvent combines some (but not all) of the functions from XtAppNextEvent and XtDispatchEvent.  That is, whereas XtAppNextEvent takes the next event from the queue—whatever it is, XtAppProcessEvent allows you to specify as a mask a bitwise OR of the symbolic constants XtIMXEvent, XtIMTimer, and XtIMAlternateInput.  This lets you select only some of these event types for processing.  In addition, XtAppProcessEvent actually calls XtDispatchEvent to dispatch X events, so only this one call is necessary. 

See Also

XtAppMainLoop(1), XtAppNextEvent(1), XtAppPending(1), XtAppProcessEvent(1), XtDispatchEvent(1).