TclDoWhenIdle(3) Tcl Library Procedures TclDoWhenIdle(3)

NAME
       TclDoWhenIdle,  TclCancelIdleCall - invoke a procedure when there are
       no pending events

SYNOPSIS
       ##iinncclluuddee <>

       TTccllDDooWWhheennIIddllee(proc, clientData)

       TTccllCCaanncceellIIddlleeCCaallll(proc, clientData)

AARRGGUUMMEENNTTSS
       TclIdleProc   *proc        (in)      Procedure to invoke.

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



DESCRIPTION
       TTccllDDooWWhheennIIddllee  arranges  for  proc  to be invoked when the application
       becomes  idle.   The  application  is  considered  to  be   idle   when
       TTccllDDooOOnneeEEvveenntt 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  TTccllDDooWWhheennIIddllee  handlers  are  invoked.  For each call to
       TTccllDDooWWhheennIIddllee there will be a single call  to  proc;   after  proc  is
       invoked  the  handler is automatically removed.  TTccllDDooWWhheennIIddllee is only
       usable in programs that use TTccllDDooOOnneeEEvveenntt to dispatch events.

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

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

       TTccllDDooWWhheennIIddllee  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.  TTccllDDooWWhheennIIddllee 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, TTccllDDooWWhheennIIddllee 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.

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 bet-
       ter to use a timer handler with a zero timeout period.


KKEEYYWWOORRDDSS
       callback, defer, idle callback



Tcl                                   7.5                    TclDoWhenIdle(3)