Tcl_CreateTimerHandler (3)
call a procedure at a
given time
SYNOPSIS
#include <tcl.h>
Tcl_TimerToken
Tcl_CreateTimerHandler(milliseconds, proc, clientData)
Tcl_DeleteTimerHandler(token)
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.
Tcl_TimerToken token in
Token for previously-created timer handler (the return value
from some previous call to Tcl_CreateTimerHandler).
DESCRIPTION
Tcl_CreateTimerHandler arranges for proc to be
invoked at a time milliseconds milliseconds in the
future.
The callback to proc will be made by Tcl_DoOneEvent,
so Tcl_CreateTimerHandler is only useful in programs that
dispatch events through Tcl_DoOneEvent or through Tcl commands
such as vwait.
The call to proc may not be made at the exact time given by
milliseconds: it will be made at the next opportunity
after that time. For example, if Tcl_DoOneEvent isn't
called until long after the time has elapsed, or if there
are other pending events to process before the call to
proc, then the call to proc will be delayed.
Proc should have arguments and return value that match
the type Tcl_TimerProc:
typedef void Tcl_TimerProc(ClientData clientData);
The clientData parameter to proc is a
copy of the clientData argument given to
Tcl_CreateTimerHandler when the callback
was created. Typically, clientData points to a data
structure containing application-specific information about
what to do in proc.
Tcl_DeleteTimerHandler may be called to delete a
previously-created timer handler. It deletes the handler
indicated by token so that no call to proc
will be made; if that handler no longer exists
(e.g. because the time period has already elapsed and proc
has been invoked then Tcl_DeleteTimerHandler does nothing.
The tokens returned by Tcl_CreateTimerHandler never have
a value of NULL, so if NULL is passed to Tcl_DeleteTimerHandler
then the procedure does nothing.
KEYWORDS
callback, clock, handler, timer
'\"
'\" Copyright (c) 1989-1993 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: CrtTrace.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
|