NAME

       after - Execute a command after a time delay

SYNOPSIS

       after ms

       after ms ?script script script ...?

       after cancel id

       after cancel script script script ...

       after idle ?script script script ...?

       after info ?id?
_________________________________________________________________

DESCRIPTION

       This  command  is  used  to  delay  execution  of  the  program or to execute a command in
       background sometime in the future.  It has several forms, depending on the first  argument
       to the command:

       after ms
              Ms  must  be  an  integer giving a time in milliseconds.  The command sleeps for ms
              milliseconds and then returns.  While the command is sleeping the application  does
              not respond to events.

       after ms ?script script script ...?
              In  this form the command returns immediately, but it arranges for a Tcl command to
              be executed ms milliseconds later  as  an  event  handler.   The  command  will  be
              executed  exactly  once,  at  the  given  time.   The  delayed command is formed by
              concatenating all the script arguments in the same fashion as the  concat  command.
              The  command  will  be  executed  at  global  level (outside the context of any Tcl
              procedure).  If an error occurs  while  executing  the  delayed  command  then  the
              bgerror  mechanism  is  used  to  report  the  error.  The after command returns an
              identifier that can be used to cancel the delayed command using after cancel.

       after cancel id
              Cancels the execution of a delayed  command  that  was  previously  scheduled.   Id
              indicates  which  command  should  be canceled;  it must have been the return value
              from a previous after command.  If  the  command  given  by  id  has  already  been
              executed then the after cancel command has no effect.

       after cancel script script ...
              This command also cancels the execution of a delayed command.  The script arguments
              are concatenated together with space separators (just as in  the  concat  command).
              If  there  is  a  pending command that matches the string, it is cancelled and will
              never be executed;  if no such command is currently pending then the  after  cancel
              command has no effect.

       after idle script ?script script ...?
              Concatenates  the  script  arguments together with space separators (just as in the
              concat command), and arranges for the resulting script to be evaluated later as  an
              idle  callback.   The script will be run exactly once, the next time the event loop
              is entered and there are no events to process.  The command returns  an  identifier
              that  can  be  used  to cancel the delayed command using after cancel.  If an error
              occurs while executing the script then the bgerror mechanism is used to report  the
              error.

       after info ?id?
              This  command returns information about existing event handlers.  If no id argument
              is supplied, the command returns a list of the identifiers for all  existing  event
              handlers  created by the after command for this interpreter.  If id is supplied, it
              specifies an existing handler; id  must  have  been  the  return  value  from  some
              previous  call  to  after and it must not have triggered yet or been cancelled.  In
              this case the command returns a list with two elements.  The first element  of  the
              list  is  the  script  associated with id, and the second element is either idle or
              timer to indicate what kind of event handler it is.

       The after ms and after idle forms of the command assume  that  the  application  is  event
       driven:  the delayed commands will not be executed unless the application enters the event
       loop.  In applications that are not normally event-driven, such as tclsh, the  event  loop
       can be entered with the vwait and update commands.

EXAMPLES

       This defines a command to make Tcl do nothing at all for N seconds:
              proc sleep {N} {
                 after [expr {int($N * 1000)}]
              }

       This  arranges  for the command wake_up to be run in eight hours (providing the event loop
       is active at that time):
              after [expr {1000 * 60 * 60 * 8}] wake_up

       The following command can be used to do long-running calculations (as represented here  by
       ::my_calc::one_step,  which is assumed to return a boolean indicating whether another step
       should be performed) in a step-by-step fashion, though the calculation itself needs to  be
       arranged  so  it  can  work step-wise.  This technique is extra careful to ensure that the
       event loop is not starved by the rescheduling of processing steps (arranging for the  next
       step  to be done using an already-triggered timer event only when the event queue has been
       drained) and is useful when you want to ensure that a Tk GUI remains responsive  during  a
       slow task.
              proc doOneStep {} {
                 if {[::my_calc::one_step]} {
                    after idle [list after 0 doOneStep]
                 }
              }
              doOneStep

SEE ALSO

       bgerror(3tcl), concat(3tcl), update(3tcl), vwait(3tcl)

KEYWORDS

       cancel, delay, idle callback, sleep, time