[25] | 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 |
---|