ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

This manual page is associated with the Mac OS X developer tools. The software or headers described may not be present on your Mac OS X installation until you install the developer tools package. This package is available on your Mac OS X installation DVD, and the latest versions can be downloaded from developer.apple.com.

For more information about the manual page format, see the manual page for manpages(5).



Tcl_DoWhenIdle(3)                          Tcl Library Procedures                          Tcl_DoWhenIdle(3)



____________________________________________________________________________________________________________

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

SYNOPSIS
       #include <tcl.h>

       Tcl_DoWhenIdle(proc, clientData)

       Tcl_CancelIdleCall(proc, clientData)

ARGUMENTS
       Tcl_IdleProc   *proc        (in)      Procedure to invoke.

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


DESCRIPTION
       Tcl_DoWhenIdle arranges for proc to be invoked when the application becomes idle.  The application is
       considered to be idle when Tcl_DoOneEvent has been called, couldn't 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 han-dlers handlers
       dlers 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.  Typi-cally, Typically,
       cally,  clientData  points to a data structure containing application-specific information about what
       proc should do.

       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'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.  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  situa-tions, situations,
       tions, such as the processing of a command file.

BUGS
       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 better to use a timer han-dler handler
       dler with a zero timeout period.


KEYWORDS
       callback, defer, idle callback



Tcl                                                  7.5                                   Tcl_DoWhenIdle(3)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.