'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" All rights reserved.
'\"
'\" Permission is hereby granted, without written agreement and without
'\" license or royalty fees, to use, copy, modify, and distribute this
'\" documentation for any purpose, provided that the above copyright
'\" notice and the following two paragraphs appear in all copies.
'\"
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
'\"
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
'\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
'\" 
'\" $Header: /user6/ouster/wish/man/RCS/DoWhenIdle.3,v 1.8 93/04/01 09:41:19 ouster Exp $ SPRITE (Berkeley)
'\" 
.so man.macros
.HS Tk_DoWhenIdle tkc
.BS
.SH NAME
Tk_DoWhenIdle, Tk_CancelIdleCall \- invoke a procedure when there are no pending events
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_DoWhenIdle\fR(\fIproc, clientData\fR)
.sp
.VS
\fBTk_CancelIdleCall\fR(\fIproc, clientData\fR)
.VE
.SH ARGUMENTS
.AS Tk_IdleProc clientData
.AP Tk_IdleProc *proc in
Procedure to invoke.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE

.SH DESCRIPTION
.PP
\fBTk_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
when the application becomes idle.  The application is
considered to be idle when \fBTk_DoOneEvent\fR has been
called, it couldn't find any events to handle, and it is about
to go to sleep waiting for an event to occur.  At this
point all pending \fBTk_DoWhenIdle\fR handlers are
invoked.  For each call to \fBTk_DoWhenIdle\fR there will
be a single call to \fIproc\fR;  after \fIproc\fR is
invoked the handler is automatically removed.
\fBTk_DoWhenIdle\fR is only useable in programs that
use \fBTk_DoOneEvent\fR to dispatch events.
.PP
\fIProc\fP should have arguments and result that match the
type \fBTk_IdleProc\fR:
.nf
.RS
typedef void Tk_IdleProc(ClientData \fIclientData\fR);
.RE
.fi
The \fIclientData\fP parameter to \fIproc\fR is a copy of the \fIclientData\fP
argument given to \fBTk_DoWhenIdle\fR.  Typically, \fIclientData\fR
points to a data structure containing application-specific information about
what \fIproc\fR should do.
.PP
\fBTk_CancelIdleCall\fR
.VS
may be used to cancel one or more previous
calls to \fBTk_DoWhenIdle\fR:  if there is a \fBTk_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.
.VE
.PP
\fBTk_DoWhenIdle\fR is most useful in situations where
(a) a piece of work will have to be done but (b) it's
possible that something will happen in the near future
that will change what has to be done, or require something
different to be done.  \fBTk_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, \fBTk_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 KEYWORDS
callback, defer, handler, idle