_________________________________________________________________

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

     SYNOPSIS
          #include <tk.h>

          Tk_DoWhenIdle(proc, clientData)

          Tk_CancelIdleCall(proc, clientData)

     ARGUMENTS
          Tk_IdleProc   *proc        (in)      Procedure to invoke.

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


     DESCRIPTION
          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 processing of a
          command file.


     KEYWORDS
          callback, defer, handler, idle