manpagez: man pages & more
man DoWhenIdle(3)
Home | html | info | man
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

       Procedure to invoke.  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 param-
       eter   to   proc  is  a  copy  of  the  clientData  argument  given  to
       Tcl_DoWhenIdle.  Typically, clientData points to a data structure  con-
       taining 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 is 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 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.



KEYWORDS

       callback, defer, idle callback



Tcl                                   7.5                    Tcl_DoWhenIdle(3)

DoWhenIdle 8.5.4 - Generated Mon Aug 18 06:06:14 CDT 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.