Tcl_CreateModalTimeoutTcl Library ProcedTcl_CreateModalTimeout(3)_________________________________________________________________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
milliseconds
have elapsed.
ClientData clientData (in) Arbitrary one-
word value to
pass to proc.
_________________________________________________________________DESCRIPTIONTcl_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_CreateTimer-
Handler except that it creates a modal timeout. Its argu-
ments 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_CreateModalTime-
out.
Modal timeouts differ from a normal timers in three ways.
Tcl 7.5 1
Tcl_CreateModalTimeoutTcl Library ProcedTcl_CreateModalTimeout(3)
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 situa-
tions, and they should be used with caution.
KEYWORDS
callback, clock, handler, modal timeout
Tcl 7.5 2
