Tcl_DoOneEvent(3) Tcl Library Procedures Tcl_DoOneEvent(3)

____________________________________________________________________________

NAME

Tcl_DoOneEvent - wait for events and invoke event handlers

SYNOPSIS

#include <tcl.h>

int
Tcl_DoOneEvent(flags)

ARGUMENTS

int flags (in) This parameter is normally zero. It may be
an OR-ed combination of any of the following
flag bits: TCL_WINDOW_EVENTS,
TCL_FILE_EVENTS, TCL_TIMER_EVENTS,
TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or
TCL_DONT_WAIT.
____________________________________________________________________________

DESCRIPTION

This procedure is the entry point to Tcl's event loop; it is
responsible for waiting for events and dispatching event handlers
created with procedures such as Tk_CreateEventHandler,
Tcl_CreateFileHandler, Tcl_CreateTimerHandler, and Tcl_DoWhenIdle.
Tcl_DoOneEvent checks to see if events are already present on the Tcl
event queue; if so, it calls the handler(s) for the first (oldest)
event, removes it from the queue, and returns. If there are no
events ready to be handled, then Tcl_DoOneEvent checks for new events
from all possible sources. If any are found, it puts all of them on
Tcl's event queue, calls handlers for the first event on the queue,
and returns. If no events are found, Tcl_DoOneEvent checks for
Tcl_DoWhenIdle callbacks; if any are found, it invokes all of them
and returns. Finally, if no events or idle callbacks have been
found, then Tcl_DoOneEvent sleeps until an event occurs; then it adds
any new events to the Tcl event queue, calls handlers for the first
event, and returns. The normal return value is 1 to signify that
some event was processed (see below for other alternatives).

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

TCL_WINDOW_EVENTS - Process window system events.

TCL_FILE_EVENTS - Process file events.

TCL_TIMER_EVENTS - Process timer events.

TCL_IDLE_EVENTS - Process idle callbacks.

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

TCL_DONT_WAIT - Do not sleep: process only events that
are ready at the time of the call.

If any of the flags TCL_WINDOW_EVENTS, TCL_FILE_EVENTS,
TCL_TIMER_EVENTS, or TCL_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 TCL_ALL_EVENTS, which
causes all event types to be processed. If an application has
defined additional event sources with Tcl_CreateEventSource, then
additional flag values may also be valid, depending on those event
sources.

The TCL_DONT_WAIT flag causes Tcl_DoOneEvent 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. Tcl_DoOneEvent will also return 0 without doing anything
if the only alternative is to block forever (this can happen, for
example, if flags is TCL_IDLE_EVENTS and there are no Tcl_DoWhenIdle
callbacks pending, or if no event handlers or timer handlers exist).

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

KEYWORDS

callback, event, handler, idle, timer

Tcl 7.5 Tcl_DoOneEvent(3)