bionic (3) Tcl_DoOneEvent.3tcl.gz

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