Tcl_DoWhenIdle(3tcl)

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, 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 structure  containing  application-specific
     information about what proc should do.

     Tcl_CancelIdleCall may be used to cancel one or more  previ-
     ous  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

Tcl                     Last change: 7.5                        1

Tcl_DoWhenIdle(3)    Tcl Library Procedures     Tcl_DoWhenIdle(3)

     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 com-
     mand 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
     handler with a zero timeout period.

KEYWORDS

     callback, defer, idle callback

Tcl                     Last change: 7.5                        2