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_WIN-
			       DOW_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 con-
       sidered 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)