1 | '\" |
---|
2 | '\" Copyright (c) 1990 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: DoWhenIdle.3,v 1.5 2007/12/13 15:22:31 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures" |
---|
12 | .BS |
---|
13 | .SH NAME |
---|
14 | Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events |
---|
15 | .SH SYNOPSIS |
---|
16 | .nf |
---|
17 | \fB#include <tcl.h>\fR |
---|
18 | .sp |
---|
19 | \fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR) |
---|
20 | .sp |
---|
21 | \fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR) |
---|
22 | .SH ARGUMENTS |
---|
23 | .AS Tcl_IdleProc clientData |
---|
24 | .AP Tcl_IdleProc *proc in |
---|
25 | Procedure to invoke. |
---|
26 | .AP ClientData clientData in |
---|
27 | Arbitrary one-word value to pass to \fIproc\fR. |
---|
28 | .BE |
---|
29 | |
---|
30 | .SH DESCRIPTION |
---|
31 | .PP |
---|
32 | \fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked |
---|
33 | when the application becomes idle. The application is |
---|
34 | considered to be idle when \fBTcl_DoOneEvent\fR has been |
---|
35 | called, could not find any events to handle, and is about |
---|
36 | to go to sleep waiting for an event to occur. At this |
---|
37 | point all pending \fBTcl_DoWhenIdle\fR handlers are |
---|
38 | invoked. For each call to \fBTcl_DoWhenIdle\fR there will |
---|
39 | be a single call to \fIproc\fR; after \fIproc\fR is |
---|
40 | invoked the handler is automatically removed. |
---|
41 | \fBTcl_DoWhenIdle\fR is only usable in programs that |
---|
42 | use \fBTcl_DoOneEvent\fR to dispatch events. |
---|
43 | .PP |
---|
44 | \fIProc\fR should have arguments and result that match the |
---|
45 | type \fBTcl_IdleProc\fR: |
---|
46 | .CS |
---|
47 | typedef void Tcl_IdleProc(ClientData \fIclientData\fR); |
---|
48 | .CE |
---|
49 | The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR |
---|
50 | argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR |
---|
51 | points to a data structure containing application-specific information about |
---|
52 | what \fIproc\fR should do. |
---|
53 | .PP |
---|
54 | \fBTcl_CancelIdleCall\fR |
---|
55 | may be used to cancel one or more previous |
---|
56 | calls to \fBTcl_DoWhenIdle\fR: if there is a \fBTcl_DoWhenIdle\fR |
---|
57 | handler registered for \fIproc\fR and \fIclientData\fR, then it |
---|
58 | is removed without invoking it. If there is more than one |
---|
59 | handler on the idle list that refers to \fIproc\fR and \fIclientData\fR, |
---|
60 | all of the handlers are removed. If no existing handlers match |
---|
61 | \fIproc\fR and \fIclientData\fR then nothing happens. |
---|
62 | .PP |
---|
63 | \fBTcl_DoWhenIdle\fR is most useful in situations where |
---|
64 | (a) a piece of work will have to be done but (b) it is |
---|
65 | possible that something will happen in the near future |
---|
66 | that will change what has to be done or require something |
---|
67 | different to be done. \fBTcl_DoWhenIdle\fR allows the |
---|
68 | actual work to be deferred until all pending events have |
---|
69 | been processed. At this point the exact work to be done |
---|
70 | will presumably be known and it can be done exactly once. |
---|
71 | .PP |
---|
72 | For example, \fBTcl_DoWhenIdle\fR might be used by an editor |
---|
73 | to defer display updates until all pending commands have |
---|
74 | been processed. Without this feature, redundant redisplays |
---|
75 | might occur in some situations, such as the processing of |
---|
76 | a command file. |
---|
77 | .SH BUGS |
---|
78 | .PP |
---|
79 | At present it is not safe for an idle callback to reschedule itself |
---|
80 | continuously. This will interact badly with certain features of Tk |
---|
81 | that attempt to wait for all idle callbacks to complete. If you would |
---|
82 | like for an idle callback to reschedule itself continuously, it is |
---|
83 | better to use a timer handler with a zero timeout period. |
---|
84 | |
---|
85 | .SH KEYWORDS |
---|
86 | callback, defer, idle callback |
---|