| 1 | '\" |
|---|
| 2 | '\" Copyright (c) 1990 The Regents of the University of California. |
|---|
| 3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
|---|
| 4 | '\" |
|---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
|---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
|---|
| 7 | '\" |
|---|
| 8 | '\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.6 2007/12/13 15:22:30 dgp Exp $ |
|---|
| 9 | '\" |
|---|
| 10 | .so man.macros |
|---|
| 11 | .TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures" |
|---|
| 12 | .BS |
|---|
| 13 | .SH NAME |
|---|
| 14 | Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a given time |
|---|
| 15 | .SH SYNOPSIS |
|---|
| 16 | .nf |
|---|
| 17 | \fB#include <tcl.h>\fR |
|---|
| 18 | .sp |
|---|
| 19 | Tcl_TimerToken |
|---|
| 20 | \fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR) |
|---|
| 21 | .sp |
|---|
| 22 | \fBTcl_DeleteTimerHandler\fR(\fItoken\fR) |
|---|
| 23 | .SH ARGUMENTS |
|---|
| 24 | .AS Tcl_TimerToken milliseconds |
|---|
| 25 | .AP int milliseconds in |
|---|
| 26 | How many milliseconds to wait before invoking \fIproc\fR. |
|---|
| 27 | .AP Tcl_TimerProc *proc in |
|---|
| 28 | Procedure to invoke after \fImilliseconds\fR have elapsed. |
|---|
| 29 | .AP ClientData clientData in |
|---|
| 30 | Arbitrary one-word value to pass to \fIproc\fR. |
|---|
| 31 | .AP Tcl_TimerToken token in |
|---|
| 32 | Token for previously created timer handler (the return value |
|---|
| 33 | from some previous call to \fBTcl_CreateTimerHandler\fR). |
|---|
| 34 | .BE |
|---|
| 35 | |
|---|
| 36 | .SH DESCRIPTION |
|---|
| 37 | .PP |
|---|
| 38 | \fBTcl_CreateTimerHandler\fR arranges for \fIproc\fR to be |
|---|
| 39 | invoked at a time \fImilliseconds\fR milliseconds in the |
|---|
| 40 | future. |
|---|
| 41 | The callback to \fIproc\fR will be made by \fBTcl_DoOneEvent\fR, |
|---|
| 42 | so \fBTcl_CreateTimerHandler\fR is only useful in programs that |
|---|
| 43 | dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands |
|---|
| 44 | such as \fBvwait\fR. |
|---|
| 45 | The call to \fIproc\fR may not be made at the exact time given by |
|---|
| 46 | \fImilliseconds\fR: it will be made at the next opportunity |
|---|
| 47 | after that time. For example, if \fBTcl_DoOneEvent\fR is not |
|---|
| 48 | called until long after the time has elapsed, or if there |
|---|
| 49 | are other pending events to process before the call to |
|---|
| 50 | \fIproc\fR, then the call to \fIproc\fR will be delayed. |
|---|
| 51 | .PP |
|---|
| 52 | \fIProc\fR should have arguments and return value that match |
|---|
| 53 | the type \fBTcl_TimerProc\fR: |
|---|
| 54 | .CS |
|---|
| 55 | typedef void Tcl_TimerProc(ClientData \fIclientData\fR); |
|---|
| 56 | .CE |
|---|
| 57 | The \fIclientData\fR parameter to \fIproc\fR is a |
|---|
| 58 | copy of the \fIclientData\fR argument given to |
|---|
| 59 | \fBTcl_CreateTimerHandler\fR when the callback |
|---|
| 60 | was created. Typically, \fIclientData\fR points to a data |
|---|
| 61 | structure containing application-specific information about |
|---|
| 62 | what to do in \fIproc\fR. |
|---|
| 63 | .PP |
|---|
| 64 | \fBTcl_DeleteTimerHandler\fR may be called to delete a |
|---|
| 65 | previously created timer handler. It deletes the handler |
|---|
| 66 | indicated by \fItoken\fR so that no call to \fIproc\fR |
|---|
| 67 | will be made; if that handler no longer exists |
|---|
| 68 | (e.g. because the time period has already elapsed and \fIproc\fR |
|---|
| 69 | has been invoked then \fBTcl_DeleteTimerHandler\fR does nothing. |
|---|
| 70 | The tokens returned by \fBTcl_CreateTimerHandler\fR never have |
|---|
| 71 | a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR |
|---|
| 72 | then the procedure does nothing. |
|---|
| 73 | |
|---|
| 74 | .SH KEYWORDS |
|---|
| 75 | callback, clock, handler, timer |
|---|
