diff options
Diffstat (limited to 'contrib/tcl/doc/CrtModalTmt.3')
| -rw-r--r-- | contrib/tcl/doc/CrtModalTmt.3 | 71 |
1 files changed, 71 insertions, 0 deletions
diff --git a/contrib/tcl/doc/CrtModalTmt.3 b/contrib/tcl/doc/CrtModalTmt.3 new file mode 100644 index 000000000000..85f079fc85cc --- /dev/null +++ b/contrib/tcl/doc/CrtModalTmt.3 @@ -0,0 +1,71 @@ +'\" +'\" 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 |