1Tcl_DoWhenIdle(3)           Tcl Library Procedures           Tcl_DoWhenIdle(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_DoWhenIdle,  Tcl_CancelIdleCall - invoke a procedure when there are
9       no pending events
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_DoWhenIdle(proc, clientData)
15
16       Tcl_CancelIdleCall(proc, clientData)
17

ARGUMENTS

19       Tcl_IdleProc   *proc        (in)      Procedure to invoke.
20
21       ClientData     clientData   (in)      Arbitrary one-word value to  pass
22                                             to proc.
23_________________________________________________________________
24
25

DESCRIPTION

27       Tcl_DoWhenIdle  arranges  for  proc  to be invoked when the application
28       becomes  idle.   The  application  is  considered  to  be   idle   when
29       Tcl_DoOneEvent has been called, couldn't find any events to handle, and
30       is about to go to sleep waiting for an event to occur.  At  this  point
31       all  pending  Tcl_DoWhenIdle  handlers  are  invoked.  For each call to
32       Tcl_DoWhenIdle there will be a single call  to  proc;   after  proc  is
33       invoked  the  handler is automatically removed.  Tcl_DoWhenIdle is only
34       usable in programs that use Tcl_DoOneEvent to dispatch events.
35
36       Proc should have arguments and result that match the type Tcl_IdleProc:
37              typedef void Tcl_IdleProc(ClientData clientData);
38       The clientData parameter to proc is a copy of the  clientData  argument
39       given to Tcl_DoWhenIdle.  Typically, clientData points to a data struc‐
40       ture containing application-specific information about what proc should
41       do.
42
43       Tcl_CancelIdleCall  may be used to cancel one or more previous calls to
44       Tcl_DoWhenIdle:  if there is a Tcl_DoWhenIdle  handler  registered  for
45       proc  and clientData, then it is removed without invoking it.  If there
46       is more than one handler on the idle  list  that  refers  to  proc  and
47       clientData,  all  of the handlers are removed.  If no existing handlers
48       match proc and clientData then nothing happens.
49
50       Tcl_DoWhenIdle is most useful in situations where (a) a piece  of  work
51       will  have  to be done but (b) it's possible that something will happen
52       in the near future that will change what has  to  be  done  or  require
53       something  different to be done.  Tcl_DoWhenIdle allows the actual work
54       to be deferred until all pending events have been processed.   At  this
55       point  the exact work to be done will presumably be known and it can be
56       done exactly once.
57
58       For example, Tcl_DoWhenIdle might be used by an editor to defer display
59       updates  until  all pending commands have been processed.  Without this
60       feature, redundant redisplays might occur in some situations,  such  as
61       the processing of a command file.
62

BUGS

64       At  present  it  is  not safe for an idle callback to reschedule itself
65       continuously.  This will interact badly with  certain  features  of  Tk
66       that  attempt to wait for all idle callbacks to complete.  If you would
67       like for an idle callback to reschedule itself continuously, it is bet‐
68       ter to use a timer handler with a zero timeout period.
69
70

KEYWORDS

72       callback, defer, idle callback
73
74
75
76Tcl                                   7.5                    Tcl_DoWhenIdle(3)
Impressum