Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 responsi-
       ble 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  han-
       dlers  for  the first event, and	returns.  The normal return value is 1
       to signify that some event was processed	(see below for other  alterna-
       tives).

       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	situa-
       tions, such as when a notification dialog has been popped up and	an ap-
       plication 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)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_DoOneEvent.tcl85&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help