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(3tcl)