DoOneEvent man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



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_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 ew events to the Tcl event queue,
       calls handlers for the first event, and returns.	 The nor-
       mal return value is 1 to signify that some event was  pro-
       cessed (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			       7.5				1

Tcl_DoOneEvent(3)     Tcl Library Procedures	Tcl_DoOneEvent(3)

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

Tcl			       7.5				2

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net