Tk_DoWhenIdle(3Tk)Tk_DoWhenIdle(3Tk)NAME
Tk_DoWhenIdle, Tk_CancelIdleCall - invoke a procedure when there are no
pending events
SYNOPSIS
#include <tk.h>
Tk_DoWhenIdle(proc, clientData)
Tk_CancelIdleCall(proc, clientData)
ARGUMENTS
Tk_IdleProc *proc (in) Procedure to invoke.
ClientData clientData (in) Arbitrary one-word value to pass to
proc.
DESCRIPTION
Tk_DoWhenIdle arranges for proc to be invoked when the application
becomes idle. The application is considered to be idle when
Tk_DoOneEvent 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 Tk_DoWhenIdle handlers are invoked. For each call to
Tk_DoWhenIdle there will be a single call to proc; after proc is invoked
the handler is automatically removed. Tk_DoWhenIdle is only useable in
programs that use Tk_DoOneEvent to dispatch events.
Proc should have arguments and result that match the type Tk_IdleProc:
typedef void Tk_IdleProc(ClientData clientData);
The clientData parameter to proc is a copy of the clientData argument
given to Tk_DoWhenIdle. Typically, clientData points to a data structure
containing application-specific information about what proc should do.
Tk_CancelIdleCall may be used to cancel one or more previous calls to
Tk_DoWhenIdle: if there is a Tk_DoWhenIdle handler registered for proc
and clientData, then it is removed without invoking it. If there is more
than one handler on the idle list that refers to proc and clientData, all
of the handlers are removed. If no existing handlers match proc and
clientData then nothing happens.
Tk_DoWhenIdle 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. Tk_DoWhenIdle 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.
For example, Tk_DoWhenIdle 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
Page 1
Tk_DoWhenIdle(3Tk)Tk_DoWhenIdle(3Tk)
processing of a command file.
KEYWORDS
callback, defer, handler, idle
Page 2
