util/src/TclTk/tcl8.6.12/doc/DoWhenIdle.3

   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 .TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tcl.h>\fR
  16 .sp
  17 \fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR)
  18 .sp
  19 \fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR)
  20 .SH ARGUMENTS
  21 .AS Tcl_IdleProc clientData
  22 .AP Tcl_IdleProc *proc in
  23 Procedure to invoke.
  24 .AP ClientData clientData in
  25 Arbitrary one-word value to pass to \fIproc\fR.
  26 .BE
  27 .SH DESCRIPTION
  28 .PP
  29 \fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
  30 when the application becomes idle.  The application is
  31 considered to be idle when \fBTcl_DoOneEvent\fR has been
  32 called, could not find any events to handle, and is about
  33 to go to sleep waiting for an event to occur.  At this
  34 point all pending \fBTcl_DoWhenIdle\fR handlers are
  35 invoked.  For each call to \fBTcl_DoWhenIdle\fR there will
  36 be a single call to \fIproc\fR;  after \fIproc\fR is
  37 invoked the handler is automatically removed.
  38 \fBTcl_DoWhenIdle\fR is only usable in programs that
  39 use \fBTcl_DoOneEvent\fR to dispatch events.
  40 .PP
  41 \fIProc\fR should have arguments and result that match the
  42 type \fBTcl_IdleProc\fR:
  43 .PP
  44 .CS
  45 typedef void \fBTcl_IdleProc\fR(
  46         ClientData \fIclientData\fR);
  47 .CE
  48 .PP
  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 .SH "SEE ALSO"
  85 after(n), Tcl_CreateFileHandler(3), Tcl_CreateTimerHandler(3)
  86 .SH KEYWORDS
  87 callback, defer, idle callback