152 lines
5.5 KiB
Plaintext
152 lines
5.5 KiB
Plaintext
|
'\"
|
||
|
|
'\" Copyright (c) 1990-1994 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.
|
||
|
|
'\"
|
||
|
|
.TH after n 7.5 Tcl "Tcl Built-In Commands"
|
||
|
|
.so man.macros
|
||
|
|
.BS
|
||
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
||
|
|
.SH NAME
|
||
|
|
after \- Execute a command after a time delay
|
||
|
|
.SH SYNOPSIS
|
||
|
|
\fBafter \fIms\fR
|
||
|
|
.sp
|
||
|
|
\fBafter \fIms \fR?\fIscript script script ...\fR?
|
||
|
|
.sp
|
||
|
|
\fBafter cancel \fIid\fR
|
||
|
|
.sp
|
||
|
|
\fBafter cancel \fIscript script script ...\fR
|
||
|
|
.sp
|
||
|
|
\fBafter idle \fR?\fIscript script script ...\fR?
|
||
|
|
.sp
|
||
|
|
\fBafter info \fR?\fIid\fR?
|
||
|
|
.BE
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
This command is used to delay execution of the program or to execute
|
||
|
|
a command in background sometime in the future. It has several forms,
|
||
|
|
depending on the first argument to the command:
|
||
|
|
.TP
|
||
|
|
\fBafter \fIms\fR
|
||
|
|
.
|
||
|
|
\fIMs\fR must be an integer giving a time in milliseconds.
|
||
|
|
The command sleeps for \fIms\fR milliseconds and then returns.
|
||
|
|
While the command is sleeping the application does not respond to
|
||
|
|
events.
|
||
|
|
.TP
|
||
|
|
\fBafter \fIms \fR?\fIscript script script ...\fR?
|
||
|
|
.
|
||
|
|
In this form the command returns immediately, but it arranges
|
||
|
|
for a Tcl command to be executed \fIms\fR milliseconds later as an
|
||
|
|
event handler.
|
||
|
|
The command will be executed exactly once, at the given time.
|
||
|
|
The delayed command is formed by concatenating all the \fIscript\fR
|
||
|
|
arguments in the same fashion as the \fBconcat\fR command.
|
||
|
|
The command will be executed at global level (outside the context
|
||
|
|
of any Tcl procedure).
|
||
|
|
If an error occurs while executing the delayed command then
|
||
|
|
the background error will be reported by the command
|
||
|
|
registered with \fBinterp bgerror\fR.
|
||
|
|
The \fBafter\fR command returns an identifier that can be used
|
||
|
|
to cancel the delayed command using \fBafter cancel\fR.
|
||
|
|
.TP
|
||
|
|
\fBafter cancel \fIid\fR
|
||
|
|
.
|
||
|
|
Cancels the execution of a delayed command that
|
||
|
|
was previously scheduled.
|
||
|
|
\fIId\fR indicates which command should be canceled; it must have
|
||
|
|
been the return value from a previous \fBafter\fR command.
|
||
|
|
If the command given by \fIid\fR has already been executed then
|
||
|
|
the \fBafter cancel\fR command has no effect.
|
||
|
|
.TP
|
||
|
|
\fBafter cancel \fIscript script ...\fR
|
||
|
|
.
|
||
|
|
This command also cancels the execution of a delayed command.
|
||
|
|
The \fIscript\fR arguments are concatenated together with space
|
||
|
|
separators (just as in the \fBconcat\fR command).
|
||
|
|
If there is a pending command that matches the string, it is
|
||
|
|
canceled and will never be executed; if no such command is
|
||
|
|
currently pending then the \fBafter cancel\fR command has no effect.
|
||
|
|
.TP
|
||
|
|
\fBafter idle \fIscript \fR?\fIscript script ...\fR?
|
||
|
|
.
|
||
|
|
Concatenates the \fIscript\fR arguments together with space
|
||
|
|
separators (just as in the \fBconcat\fR command), and arranges
|
||
|
|
for the resulting script to be evaluated later as an idle callback.
|
||
|
|
The script will be run exactly once, the next time the event
|
||
|
|
loop is entered and there are no events to process.
|
||
|
|
The command returns an identifier that can be used
|
||
|
|
to cancel the delayed command using \fBafter cancel\fR.
|
||
|
|
If an error occurs while executing the script then the
|
||
|
|
background error will be reported by the command
|
||
|
|
registered with \fBinterp bgerror\fR.
|
||
|
|
.TP
|
||
|
|
\fBafter info \fR?\fIid\fR?
|
||
|
|
.
|
||
|
|
This command returns information about existing event handlers.
|
||
|
|
If no \fIid\fR argument is supplied, the command returns
|
||
|
|
a list of the identifiers for all existing
|
||
|
|
event handlers created by the \fBafter\fR command for this
|
||
|
|
interpreter.
|
||
|
|
If \fIid\fR is supplied, it specifies an existing handler;
|
||
|
|
\fIid\fR must have been the return value from some previous call
|
||
|
|
to \fBafter\fR and it must not have triggered yet or been canceled.
|
||
|
|
In this case the command returns a list with two elements.
|
||
|
|
The first element of the list is the script associated
|
||
|
|
with \fIid\fR, and the second element is either
|
||
|
|
\fBidle\fR or \fBtimer\fR to indicate what kind of event
|
||
|
|
handler it is.
|
||
|
|
.LP
|
||
|
|
The \fBafter \fIms\fR and \fBafter idle\fR forms of the command
|
||
|
|
assume that the application is event driven: the delayed commands
|
||
|
|
will not be executed unless the application enters the event loop.
|
||
|
|
In applications that are not normally event-driven, such as
|
||
|
|
\fBtclsh\fR, the event loop can be entered with the \fBvwait\fR
|
||
|
|
and \fBupdate\fR commands.
|
||
|
|
.SH "EXAMPLES"
|
||
|
|
This defines a command to make Tcl do nothing at all for \fIN\fR
|
||
|
|
seconds:
|
||
|
|
.PP
|
||
|
|
.CS
|
||
|
|
proc sleep {N} {
|
||
|
|
\fBafter\fR [expr {int($N * 1000)}]
|
||
|
|
}
|
||
|
|
.CE
|
||
|
|
.PP
|
||
|
|
This arranges for the command \fIwake_up\fR to be run in eight hours
|
||
|
|
(providing the event loop is active at that time):
|
||
|
|
.PP
|
||
|
|
.CS
|
||
|
|
\fBafter\fR [expr {1000 * 60 * 60 * 8}] wake_up
|
||
|
|
.CE
|
||
|
|
.PP
|
||
|
|
The following command can be used to do long-running calculations (as
|
||
|
|
represented here by \fI::my_calc::one_step\fR, which is assumed to
|
||
|
|
return a boolean indicating whether another step should be performed)
|
||
|
|
in a step-by-step fashion, though the calculation itself needs to be
|
||
|
|
arranged so it can work step-wise. This technique is extra careful to
|
||
|
|
ensure that the event loop is not starved by the rescheduling of
|
||
|
|
processing steps (arranging for the next step to be done using an
|
||
|
|
already-triggered timer event only when the event queue has been
|
||
|
|
drained) and is useful when you want to ensure that a Tk GUI remains
|
||
|
|
responsive during a slow task.
|
||
|
|
.PP
|
||
|
|
.CS
|
||
|
|
proc doOneStep {} {
|
||
|
|
if {[::my_calc::one_step]} {
|
||
|
|
\fBafter idle\fR [list \fBafter\fR 0 doOneStep]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
doOneStep
|
||
|
|
.CE
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
concat(n), interp(n), update(n), vwait(n)
|
||
|
|
.SH KEYWORDS
|
||
|
|
cancel, delay, idle callback, sleep, time
|
||
|
|
'\" Local Variables:
|
||
|
|
'\" mode: nroff
|
||
|
|
'\" End:
|