Name

XtAppPending — determine whether any events are in an application’s input queue. 

Synopsis

XtInputMask XtAppPending(app_context)

    XtAppContext app_context;

Arguments

app_context
Specifies the application context for the application to check.

Description

XtAppPending returns a nonzero value if there are pending events from the X server, timer, or other input sources.  The return value is a bit mask that is the OR of XtIMXEvent (an X event), XtIMTimer (a timer event introduced onto the queue by a call to XtAppAddTimeOut), and XtIMAlternateInput (an alternate input event introduced onto the queue by a call to XtAppAddInput).  As a convenience, the symbolic name XtIMAll is defined as the bitwise inclusive OR of all event types.  If no events are pending, XtAppPending flushes the output buffers of each display in the application context and returns zero.  This call is the Intrinsics equivalent to the Xlib call XPending. 

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 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 XtPending. 

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, while 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

XtAppAddInput(1), XtAppAddTimeOut(1), XtAppMainLoop(1), XtAppNextEvent(1), XtAppPeekEvent(1), XtAppProcessEvent(1), XtDispatchEvent(1).