NAME

       Tcl_CreateTimerHandler,  Tcl_DeleteTimerHandler  -  call a
       procedure at a given time


SYNOPSIS

       #include <tcl.h>

       Tcl_TimerToken
       Tcl_CreateTimerHandler(milliseconds, proc, clientData)

       Tcl_DeleteTimerHandler(token)


ARGUMENTS

       int              milliseconds   (in)      How  many   mil­
                                                 liseconds     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 previ­
                                                 ously-created
                                                 timer    handler
                                                 (the      return
                                                 value from  some
                                                 previous call to
                                                 Tcl_CreateTimer­
                                                 Handler).
_________________________________________________________________



DESCRIPTION

       Tcl_CreateTimerHandler  arranges for proc to be invoked at
       a time milliseconds milliseconds in the future.  The call­
       back  to  proc will be made by Tcl_DoOneEvent, so Tcl_Cre­
       ateTimerHandler 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.
       type Tcl_TimerProc:
              typedef void Tcl_TimerProc(ClientData clientData);
       The  clientData parameter to proc is a copy of the client­
       Data 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 previ­
       ously-created timer handler.  It deletes the handler indi­
       cated  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  pro­
       cedure does nothing.



KEYWORDS

       callback, clock, handler, timer