| 1 |
578 |
markom |
'\"
|
| 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.1.1.1 2002-01-16 10:25:23 markom 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 \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, couldn't 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's
|
| 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
|
