Tcl_DoOneEvent(3)

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 res-
     tricts  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                     Last change: 7.5                        1

Tcl_DoOneEvent(3)    Tcl Library Procedures     Tcl_DoOneEvent(3)

     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  pro-
     cessed.   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                     Last change: 7.5                        2