tcl7.6 C API - CrtModalTmt
NAME
Tcl_CreateModalTimeout, Tcl_DeleteModalTimeout - special
timer for modal operations
SYNOPSIS
#include <tcl.h>
Tcl_CreateModalTimeout(milliseconds, proc, clientData)
Tcl_DeleteModalTimeout(proc, clientData)
ARGUMENTS
int milliseconds (in) How many mil-
liseconds to wait
before invoking
proc.
Tcl_TimerProc *proc (in) Procedure to
invoke after mil-
liseconds have
elapsed.
ClientData clientData (in) Arbitrary one-word
value to pass to
proc.
DESCRIPTION
Tcl_CreateModalTimeout provides an alternate form of timer
from those provided by Tcl_CreateTimerHandler. These timers
are called ``modal'' because they are typically used in
situations where a particular operation must be completed
before the application does anything else. If such an
operation needs a timeout, it cannot use normal timer
events: if normal timer events were processed, arbitrary
Tcl scripts might be invoked via other event handlers, which
could interfere with the completion of the modal operation.
The purpose of modal timers is to allow a single timeout to
occur without allowing any normal timer events to occur.
Tcl_CreateModalTimeout behaves just like
Tcl_CreateTimerHandler except that it creates a modal
timeout. Its arguments have the same meaning as for
Tcl_CreateTimerHandler and proc is invoked just as for
Tcl_CreateTimerHandler. Tcl_DeleteModalTimeout deletes the
most recently created modal timeout; its arguments must
match the corresponding arguments to the most recent call to
Tcl_CreateModalTimeout.
Modal timeouts differ from a normal timers in three ways.
First, they will trigger regardless of whether the
TCL_TIMER_EVENTS flag has been passed to Tcl_DoOneEvent.
Typically modal timers are used with the TCL_TIMER_EVENTS
flag off so that normal timers don't fire but modal ones do.
Second, if several modal timers have been created they
stack: only the top timer on the stack (the most recently
created one) is active at any point in time. Modal timeouts
must be deleted in inverse order from their creation.
Third, modal timeouts are not deleted when they fire: once
a modal timeout has fired, it will continue firing every
time Tcl_DoOneEvent is called, until the timeout is deleted
by calling Tcl_DeleteModalTimeout.
Modal timeouts are only needed in a few special situations,
and they should be used with caution.
KEYWORDS
callback, clock, handler, modal timeout