Tcl_CreateModalTimeoutTcl Library ProcedTclsCreateModalTimeout(3)

_________________________________________________________________

NAME
       Tcl_CreateModalTimeout,  Tcl_DeleteModalTimeout  - special
       timer for modal operations

SYNOPSIS
       #include <tcl.h>

       Tcl_CreateModalTimeout(milliseconds, proc, clientData)

       Tcl_DeleteModalTimeout(proc, clientData)

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.
_________________________________________________________________

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_CreateTimer-
       Handler except that it creates a modal timeout.  Its argu-
       ments  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_CreateModalTime-
       out.

       Modal timeouts differ from a normal timers in three  ways.

Tcl                            7.5                              1

Tcl_CreateModalTimeoutTcl Library ProcedTclsCreateModalTimeout(3)

       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  situa-
       tions, and they should be used with caution.

KEYWORDS
       callback, clock, handler, modal timeout

Tcl                            7.5                              2