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  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_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