Tcl_CreateModalTimeout(3)   Tcl Library Procedures   Tcl_CreateModalTimeout(3)


       Tcl_CreateModalTimeout, Tcl_DeleteModalTimeout - special timer for
       modal operations

       #include <tcl.h>

       Tcl_CreateModalTimeout(milliseconds, proc, clientData)

       Tcl_DeleteModalTimeout(proc, clientData)

       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_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

       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.

       callback, clock, handler, modal timeout

Tcl                                   7.5            Tcl_CreateModalTimeout(3)