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

FreeBSD Manual Pages


home | help
Tcl_DoWhenIdle(3)	    Tcl	Library	Procedures	     Tcl_DoWhenIdle(3)


       Tcl_DoWhenIdle,	Tcl_CancelIdleCall - invoke a procedure	when there are
       no pending events

       #include	<tcl.h>

       Tcl_DoWhenIdle(proc, clientData)

       Tcl_CancelIdleCall(proc,	clientData)

       Tcl_IdleProc *proc (in)		     Procedure to invoke.

       ClientData clientData (in)	     Arbitrary one-word	value to  pass
					     to	proc.

       Tcl_DoWhenIdle arranges for proc	to be invoked when the application be-
       comes  idle.   The  application	is  considered	 to   be   idle	  when
       Tcl_DoOneEvent  has  been  called, could	not find any events to handle,
       and is about to go to sleep waiting for an event	 to  occur.   At  this
       point  all  pending Tcl_DoWhenIdle handlers are invoked.	 For each call
       to Tcl_DoWhenIdle there will be a single	call to	proc;  after  proc  is
       invoked	the  handler is	automatically removed.	Tcl_DoWhenIdle is only
       usable in programs that use Tcl_DoOneEvent to dispatch events.

       Proc should have	arguments and result that match	the type Tcl_IdleProc:

	      typedef void Tcl_IdleProc(
		      ClientData clientData);

       The clientData parameter	to proc	is a copy of the  clientData  argument
       given to	Tcl_DoWhenIdle.	 Typically, clientData points to a data	struc-
       ture containing application-specific information	about what proc	should

       Tcl_CancelIdleCall  may be used to cancel one or	more previous calls to
       Tcl_DoWhenIdle:	if there is a Tcl_DoWhenIdle  handler  registered  for
       proc  and clientData, then it is	removed	without	invoking it.  If there
       is more than one	handler	on the idle  list  that	 refers	 to  proc  and
       clientData,  all	 of the	handlers are removed.  If no existing handlers
       match proc and clientData then nothing happens.

       Tcl_DoWhenIdle is most useful in	situations where (a) a piece  of  work
       will  have to be	done but (b) it	is possible that something will	happen
       in the near future that will change what	has  to	 be  done  or  require
       something  different to be done.	 Tcl_DoWhenIdle	allows the actual work
       to be deferred until all	pending	events have been processed.   At  this
       point  the exact	work to	be done	will presumably	be known and it	can be
       done exactly once.

       For example, Tcl_DoWhenIdle might be used by an editor to defer display
       updates	until  all pending commands have been processed.  Without this
       feature,	redundant redisplays might occur in some situations,  such  as
       the processing of a command file.

       At  present  it	is  not	safe for an idle callback to reschedule	itself
       continuously.  This will	interact badly with  certain  features	of  Tk
       that  attempt to	wait for all idle callbacks to complete.  If you would
       like for	an idle	callback to reschedule itself continuously, it is bet-
       ter to use a timer handler with a zero timeout period.

       after(n), Tcl_CreateFileHandler(3), Tcl_CreateTimerHandler(3)

       callback, defer,	idle callback

Tcl				      7.5		     Tcl_DoWhenIdle(3)


Want to link to this manual page? Use this URL:

home | help