1Tcl_DoWhenIdle(3) Tcl Library Procedures Tcl_DoWhenIdle(3)
2______________________________________________________________________________
6
8 Tcl_DoWhenIdle, Tcl_CancelIdleCall - invoke a procedure when there are
9 no pending events
10
12 #include <tcl.h>
13 Tcl_DoWhenIdle(proc, clientData)
15 Tcl_CancelIdleCall(proc, clientData)
17
19 Tcl_IdleProc *proc (in) Procedure to invoke.
20 ClientData clientData (in) Arbitrary one-word value to pass
22 to proc.
23_________________________________________________________________
24
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 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 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 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 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
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
72 callback, defer, idle callback
73Tcl 7.5 Tcl_DoWhenIdle(3)