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_Cre-
ateEventHandler, Tcl_CreateFileHandler, Tcl_CreateTimer-
Handler, 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 ew events to the Tcl event queue,
calls handlers for the first event, and returns. The nor-
mal return value is 1 to signify that some event was pro-
cessed (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 7.5 1
Tcl_DoOneEvent(3) Tcl Library Procedures Tcl_DoOneEvent(3)
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 spec-
ifying none of them.
TCL_DONT_WAIT - Don't 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 hap-
pen, 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 notifi-
cation 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 2
