Tk_DoOneEvent

int
Tk_DoOneEvent(flags)

Tk_MainLoop()

Tk_HandleEvent(eventPtr)

ARGUMENTS

int flags (in)

This parameter is normally zero. It may be an OR-ed combination
of any of the following flag bits: TK_X_EVENTS, TK_FILE_EVENTS,
TK_TIMER_EVENTS, TK_IDLE_EVENTS, TK_ALL_EVENTS, or TK_DONT_WAIT.

XEvent *eventPtr (in)

Pointer to X event to dispatch to relevant handler(s).

These three procedures are responsible for waiting for events
and dispatching to event handlers created with the procedures
Tk_CreateEventHandler, Tk_CreateFileHandler,
Tk_CreateTimerHandler, and Tk_DoWhenIdle.
Tk_DoOneEvent is the key procedure. It waits for a single
event of any sort to occur, invokes the handler(s) for that
event, and then returns. Tk_DoOneEvent first checks
for X events and file-related events; if one is found then
it calls the handler(s) for the event and returns. If there
are no X or file events pending, then Tk_DoOneEvent
checks to see if timer callbacks are ready; if so, it
makes a single callback and returns. If no timer callbacks
are ready, Tk_DoOneEvent checks for Tk_DoWhenIdle
callbacks; if any are found, it invokes all of them and returns.
Finally, if events or work have been found found, Tk_DoOneEvent
sleeps until a timer, file, or X event occurs; then it processes
the first event found (in the order given above) and returns.
The normal return value is 1 to signify that some event or callback
was processed.

If the flags argument to Tk_DoOneEvent is non-zero then
it restricts the kinds of events that will be processed by
Tk_DoOneEvent.
Flags may be an OR-ed combination of any of the following bits:

TK_X_EVENTS -

Process X events.

TK_FILE_EVENTS -

Process file events.

TK_TIMER_EVENTS -

Process timer events.

TK_IDLE_EVENTS -

Process Tk_DoWhenIdle callbacks.

TK_ALL_EVENTS -

Process all kinds of events: equivalent to OR-ing together all of the
above flags or specifying none of them.

TK_DONT_WAIT -

Don't sleep: process only events that are ready at the time of the
call.

If any of the flags TK_X_EVENTS, TK_FILE_EVENTS,
TK_TIMER_EVENTS, or TK_IDLE_EVENTS is set, then the only
events that will be considered are those for which flags are set.
Setting none of these flags is equivalent to the value
TK_ALL_EVENTS, which causes all event types to be processed.

The TK_DONT_WAIT flag causes Tk_DoWhenIdle not to put
the process to sleep: it will check for events but if none are found
then it returns immediately with a return value of 0 to indicate
that no work was done.
Tk_DoOneEvent will also return 0 without doing anything if
flags is TK_IDLE_EVENTS and there are no
Tk_DoWhenIdle callbacks pending.

Tk_MainLoop is a procedure that loops repeatedly
calling Tk_DoOneEvent. It returns only when there
are no applications left in this process (i.e. no main windows
exist anymore). Most X applications will
call Tk_MainLoop after initialization; the main
execution of the application will consist entirely of
callbacks invoked by Tk_DoOneEvent.

Tk_HandleEvent is a lower-level procedure invoked
by Tk_DoOneEvent. It makes callbacks to any event
handlers (created by calls to Tk_CreateEventHandler)
that match eventPtr and then returns. In some cases
it may be useful for an application to read events directly
from X and dispatch them by calling Tk_HandleEvent,
without going through the additional mechanism provided
by Tk_DoOneEvent.

These procedures may be invoked recursively. For example,
it is possible to invoke Tk_DoOneEvent recursively
from a handler called by Tk_DoOneEvent. This sort
of operation is useful in some modal situations, such
as when a
notifier has been popped up and an application wishes to
wait for the user to click a button in the notifier before
doing anything else.

KEYWORDS