Tcl_DoOneEvent

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 ew 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 -            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 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)