diff options
Diffstat (limited to 'doc/DoWhenIdle.3')
-rw-r--r-- | doc/DoWhenIdle.3 | 172 |
1 files changed, 86 insertions, 86 deletions
diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3 index 239878e..f2a962d 100644 --- a/doc/DoWhenIdle.3 +++ b/doc/DoWhenIdle.3 @@ -1,86 +1,86 @@ -'\"
-'\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.3 2007/10/28 14:17:38 dkf Exp $
-'\"
-.so man.macros
-.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
-.BS
-.SH NAME
-Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR)
-.sp
-\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR)
-.SH ARGUMENTS
-.AS Tcl_IdleProc clientData
-.AP Tcl_IdleProc *proc in
-Procedure to invoke.
-.AP ClientData clientData in
-Arbitrary one-word value to pass to \fIproc\fR.
-.BE
-
-.SH DESCRIPTION
-.PP
-\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
-when the application becomes idle. The application is
-considered to be idle when \fBTcl_DoOneEvent\fR has been
-called, could not find any events to handle, and is about
-to go to sleep waiting for an event to occur. At this
-point all pending \fBTcl_DoWhenIdle\fR handlers are
-invoked. For each call to \fBTcl_DoWhenIdle\fR there will
-be a single call to \fIproc\fR; after \fIproc\fR is
-invoked the handler is automatically removed.
-\fBTcl_DoWhenIdle\fR is only usable in programs that
-use \fBTcl_DoOneEvent\fR to dispatch events.
-.PP
-\fIProc\fR should have arguments and result that match the
-type \fBTcl_IdleProc\fR:
-.CS
-typedef void Tcl_IdleProc(ClientData \fIclientData\fR);
-.CE
-The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
-argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR
-points to a data structure containing application-specific information about
-what \fIproc\fR should do.
-.PP
-\fBTcl_CancelIdleCall\fR
-may be used to cancel one or more previous
-calls to \fBTcl_DoWhenIdle\fR: if there is a \fBTcl_DoWhenIdle\fR
-handler registered for \fIproc\fR and \fIclientData\fR, then it
-is removed without invoking it. If there is more than one
-handler on the idle list that refers to \fIproc\fR and \fIclientData\fR,
-all of the handlers are removed. If no existing handlers match
-\fIproc\fR and \fIclientData\fR then nothing happens.
-.PP
-\fBTcl_DoWhenIdle\fR is most useful in situations where
-(a) a piece of work will have to be done but (b) it is
-possible that something will happen in the near future
-that will change what has to be done or require something
-different to be done. \fBTcl_DoWhenIdle\fR allows the
-actual work to be deferred until all pending events have
-been processed. At this point the exact work to be done
-will presumably be known and it can be done exactly once.
-.PP
-For example, \fBTcl_DoWhenIdle\fR might be used by an editor
-to defer display updates until all pending commands have
-been processed. Without this feature, redundant redisplays
-might occur in some situations, such as the processing of
-a command file.
-.SH BUGS
-.PP
-At present it is not safe for an idle callback to reschedule itself
-continuously. This will interact badly with certain features of Tk
-that attempt to wait for all idle callbacks to complete. If you would
-like for an idle callback to reschedule itself continuously, it is
-better to use a timer handler with a zero timeout period.
-
-.SH KEYWORDS
-callback, defer, idle callback
+'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.4 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR) +.sp +\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR) +.SH ARGUMENTS +.AS Tcl_IdleProc clientData +.AP Tcl_IdleProc *proc in +Procedure to invoke. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked +when the application becomes idle. The application is +considered to be idle when \fBTcl_DoOneEvent\fR has been +called, could not find any events to handle, and is about +to go to sleep waiting for an event to occur. At this +point all pending \fBTcl_DoWhenIdle\fR handlers are +invoked. For each call to \fBTcl_DoWhenIdle\fR there will +be a single call to \fIproc\fR; after \fIproc\fR is +invoked the handler is automatically removed. +\fBTcl_DoWhenIdle\fR is only usable in programs that +use \fBTcl_DoOneEvent\fR to dispatch events. +.PP +\fIProc\fR should have arguments and result that match the +type \fBTcl_IdleProc\fR: +.CS +typedef void Tcl_IdleProc(ClientData \fIclientData\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR +argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR +points to a data structure containing application-specific information about +what \fIproc\fR should do. +.PP +\fBTcl_CancelIdleCall\fR +may be used to cancel one or more previous +calls to \fBTcl_DoWhenIdle\fR: if there is a \fBTcl_DoWhenIdle\fR +handler registered for \fIproc\fR and \fIclientData\fR, then it +is removed without invoking it. If there is more than one +handler on the idle list that refers to \fIproc\fR and \fIclientData\fR, +all of the handlers are removed. If no existing handlers match +\fIproc\fR and \fIclientData\fR then nothing happens. +.PP +\fBTcl_DoWhenIdle\fR is most useful in situations where +(a) a piece of work will have to be done but (b) it is +possible that something will happen in the near future +that will change what has to be done or require something +different to be done. \fBTcl_DoWhenIdle\fR allows the +actual work to be deferred until all pending events have +been processed. At this point the exact work to be done +will presumably be known and it can be done exactly once. +.PP +For example, \fBTcl_DoWhenIdle\fR might be used by an editor +to defer display updates until all pending commands have +been processed. Without this feature, redundant redisplays +might occur in some situations, such as the processing of +a command file. +.SH BUGS +.PP +At present it is not safe for an idle callback to reschedule itself +continuously. This will interact badly with certain features of Tk +that attempt to wait for all idle callbacks to complete. If you would +like for an idle callback to reschedule itself continuously, it is +better to use a timer handler with a zero timeout period. + +.SH KEYWORDS +callback, defer, idle callback |