Tk_DoWhenIdle(3Tk)					    Tk_DoWhenIdle(3Tk)

NAME    [Toc]    [Back]

     Tk_DoWhenIdle, Tk_CancelIdleCall -	invoke a procedure when	there are no
     pending events

SYNOPSIS    [Toc]    [Back]

     #include <tk.h>

     Tk_DoWhenIdle(proc, clientData)

     Tk_CancelIdleCall(proc, clientData)

ARGUMENTS    [Toc]    [Back]

     Tk_IdleProc   *proc	(in)	  Procedure to invoke.

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

DESCRIPTION    [Toc]    [Back]

     Tk_DoWhenIdle arranges for	proc to	be invoked when	the application
     becomes idle.  The	application is considered to be	idle when
     Tk_DoOneEvent has been called, it couldn't	find any events	to handle, and
     it	is about to go to sleep	waiting	for an event to	occur.	At this	point
     all pending Tk_DoWhenIdle handlers	are invoked.  For each call to
     Tk_DoWhenIdle there will be a single call to proc;	 after proc is invoked
     the handler is automatically removed.  Tk_DoWhenIdle is only useable in
     programs that use Tk_DoOneEvent to	dispatch events.

     Proc should have arguments	and result that	match the type Tk_IdleProc:
	  typedef void Tk_IdleProc(ClientData clientData);
     The clientData parameter to proc is a copy	of the clientData argument
     given to Tk_DoWhenIdle.  Typically, clientData points to a	data structure
     containing	application-specific information about what proc should	do.

     Tk_CancelIdleCall may be used to cancel one or more previous calls	to
     Tk_DoWhenIdle:  if	there is a Tk_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.

     Tk_DoWhenIdle is most useful in situations	where (a) a piece of work will
     have to be	done but (b) it's possible that	something will happen in the
     near future that will change what has to be done, or require something
     different to be done.  Tk_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, Tk_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



									Page 1






Tk_DoWhenIdle(3Tk)					    Tk_DoWhenIdle(3Tk)



     processing	of a command file.

KEYWORDS    [Toc]    [Back]

     callback, defer, handler, idle


									PPPPaaaaggggeeee 2222