Tcl_CreateModalTimeout (3)
special timer for modal operations
SYNOPSIS
#include <tcl.h>
Tcl_CreateModalTimeout(milliseconds, proc, clientData)
Tcl_DeleteModalTimeout(proc, clientData)
ARGUMENTS
Tcl_TimerToken milliseconds
int milliseconds in
How many milliseconds 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.
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
'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-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.
'\"
'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.2 1998/09/14 18:39:47 stanton Exp $
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\" Start paragraph describing an argument to a library procedure.
'\" type is type of argument (int, etc.), in/out is either "in", "out",
'\" or "in/out" to describe whether procedure reads or modifies arg,
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
'\" needed; use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\" Give maximum sizes of arguments for setting tab stops. Type and
'\" name are examples of largest possible arguments that will be passed
'\" to .AP later. If args are omitted, default tab stops are used.
'\"
'\" .BS
'\" Start box enclosure. From here until next .BE, everything will be
'\" enclosed in one large box.
'\"
'\" .BE
'\" End of box enclosure.
'\"
'\" .CS
'\" Begin code excerpt.
'\"
'\" .CE
'\" End code excerpt.
'\"
'\" .VS ?version? ?br?
'\" Begin vertical sidebar, for use in marking newly-changed parts
'\" of man pages. The first argument is ignored and used for recording
'\" the version when the .VS was added, so that the sidebars can be
'\" found and removed when they reach a certain age. If another argument
'\" is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\" End of vertical sidebar.
'\"
'\" .DS
'\" Begin an indented unfilled display.
'\"
'\" .DE
'\" End of indented unfilled display.
'\"
'\" .SO
'\" Start of list of standard options for a Tk widget. The
'\" options follow on successive lines, in four columns separated
'\" by tabs.
'\"
'\" .SE
'\" End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\" Start of description of a specific option. cmdName gives the
'\" option's name as specified in the class command, dbName gives
'\" the option's name in the option database, and dbClass gives
'\" the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\" Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.2 1998/09/14 18:39:54 stanton Exp $
'\"
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
t .wh -1.3i ^B
^l \n(.l
b
'\" # Start an argument description
AP
!"\\$4"" .TP \\$4
\{\
!"\\$2"" .TP \\n()Cu
.TP 15
|
