'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" SCCS: @(#) CrtModalTmt.3 1.3 96/03/25 20:00:19
'\" 
.so man.macros
.TH Tcl_CreateModalTimeout 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateModalTimeout, Tcl_DeleteModalTimeout \- special timer for modal operations
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_CreateModalTimeout\fR(\fImilliseconds, proc, clientData\fR)
.sp
\fBTcl_DeleteModalTimeout\fR(\fIproc, clientData\fR)
.SH ARGUMENTS
.AS Tcl_TimerToken milliseconds
.AP int milliseconds  in
How many milliseconds to wait before invoking \fIproc\fR.
.AP Tcl_TimerProc *proc in
Procedure to invoke after \fImilliseconds\fR have elapsed.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE

.SH DESCRIPTION
.PP
\fBTcl_CreateModalTimeout\fR provides an alternate form of timer
from those provided by \fBTcl_CreateTimerHandler\fR.
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.
.PP
\fBTcl_CreateModalTimeout\fR behaves just like \fBTcl_CreateTimerHandler\fR
except that it creates a modal timeout.
Its arguments have the same meaning as for \fBTcl_CreateTimerHandler\fR
and \fIproc\fR is invoked just as for \fBTcl_CreateTimerHandler\fR.
\fBTcl_DeleteModalTimeout\fR deletes the most recently created
modal timeout;  its arguments must match the corresponding arguments
to the most recent call to \fBTcl_CreateModalTimeout\fR.
.PP
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 \fBTcl_DoOneEvent\fR.
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 \fBTcl_DoOneEvent\fR
is called, until the timeout is deleted by calling
\fBTcl_DeleteModalTimeout\fR.
.PP
Modal timeouts are only needed in a few special situations, and they
should be used with caution.

.SH KEYWORDS
callback, clock, handler, modal timeout