tcl7.6 C API - CrtModalTmt






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 mil-
                                               liseconds     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_CreateTimerHandler   except  that  it  creates  a  modal
     timeout.   Its  arguments  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_CreateModalTimeout.

     Modal timeouts differ from a normal timers  in  three  ways.
     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  situations,
     and they should be used with caution.



KEYWORDS

     callback, clock, handler, modal timeout