72 lines
2.8 KiB
Groff
72 lines
2.8 KiB
Groff
'\"
|
|
'\" 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
|