NAME

timer - tcl library package for stopwatch/countdown timers.

DESCRIPTION

The timer package provides easy access to Tcl's built-in clock with millisecond accuracy. It facilitates the writing of stopwatch and countdown timer applications.

The timer::create command creates a timer, and returns a token whose value is the name of an array in the ::timer namespace. The elements of this array are described in the STATE ARRAY section.

SYNOPSIS

package require timer ?0.3.0?

timer::cget token option
timer::configure token ?option? ?value option value ...?
timer::create ?options?
timer::delete token
timer::reset token ?time?
timer::start token
timer::startstop token
timer::stop token
timer::unload

timer::fmt token time
timer::init
timer::tick token last
timer::tick32 token
timer::tick64 token

COMMANDS

timer::cget token option
The timer::cget command returns the current value of the configuration option given by option. Option may have any of the values accepted by the timer::configure command.

timer::configure token ?option? ?value option value ...?
The timer::configure command queries or modifies the timer with state array variable given by token. If no option is specified, returns a list describing all the available options for the timer. If option is specified with no value, returns the current value of that configuration option. If one or more option-value pairs are specified, then the command modifies the given timer option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the following options:
-alarm command
The specified command is invoked whenever a countdown timer reaches time 0.

-interval time
This option specifies the time (in milliseconds) between consecutive updates of the elapsed time. It defaults to 1 millisecond.

-reset time
This option sets the default reset time of the timer to time, in milliseconds. The default reset time is 0. The timer is set to this value when the timer::reset command is called without specifying the optional time value. The timer is initially set to this value (if specified at creation time).

-stop command
The specified command is invoked whenever the timer is stopped, either by calling the timer::stop command, or when a countdown timer reaches time 0.

-update command
The specified command is invoked whenever the timer updates the elapsed time. Normally, only the time index to the state array variable is updated.

timer::create ?options?
The timer::create command creates a new timer, and returns a token value that can be used to get information. See the STATE ARRAY section for details. All options are passed to the command timer::configure.

timer::delete token
The timer::delete command deletes the timer with state array variable given by token. The timer is stopped (if running), and the state array variable is deleted.

timer::reset token ?time?
The timer::reset command resets the timer with state array variable given by token. If the optional time parameter is specified, the timer is set to that time, otherwise the timer is set to its default reset time (as specified by the -reset option to the timer::create or timer::configure command). If the reset time is positive (or 0), the timer (when started with the timer::start command) will count upwards like a stopwatch, until the timer::stop command is given. Otherwise, if the reset time is negative, the timer (when started) will act as a countdown timer, counting upwards until time 0, whereupon the alarm callback (if specified with the -alarm option) will be invoked.

timer::start token
The timer::start command starts the timer with state array variable given by token. The timer is started from the current value of the time index to the state array variable, and increases or decreases as defined by the reset value.

timer::startstop token
The timer::startstop command toggles the running state of the timer with state array variable given by token.

timer::stop token
The timer::stop command stops the timer with state array variable given by token. The timer is stopped and the stop callback command (if defined) is invoked.

timer::unload
The timer::unload command unloads the timer package. It deletes all existing timers, deletes all procedures in the package, deletes the timer namespace, and removes all information about the timer package from the interpreter.

timer::fmt token time
The timer::fmt private command sets various elements of the state array variable given by token. It reads the value of time (in milliseconds), and sets the state array elements hours, minutes, seconds and milliseconds. It returns the value of time in the format 00:00:00.000

timer::init
The timer::init private command initializes the timer package.

timer::tick token last
The timer::tick private command updates the timer with state array variable given by token. The elapsed time (in milliseconds) since the timer was started is calculated. The argument last specifies the time at which the last tick occured.

timer::tick32 token
The timer::tick32 private command is a wrapper procedure around the timer::tick command, with arithmetic designed for 32-bit integers. This is the default for Tcl versions prior to 8.4. Support for 32-bit integers is calculated in the timer::init procedure.

timer::tick64 token
The timer::tick64 private command is a wrapper procedure around the timer::tick command, with arithmetic designed for 64-bit integers. This is the default for Tcl version 8.4 and above. Support for 64-bit integers is calculated in the timer::init procedure.

STATE ARRAY

The timer::create command returns a token that can be used to get the state of the timer in the form of a Tcl array. Use this construct to create an easy-to-use array variable:

upvar #0 $token state

Once the data associated with the timer is no longer needed, the state array variable should be deleted to free up storage space. The timer::delete command is provided for that purpose. The following elements of the state array are used:

clicks
The number of clock clicks (calculated to millisecond accuracy) since the timer was (effectively) started.
zero
The number of absolute clock clicks at the time the timer was (effectively) started.
running
Indicates if the timer is currently running or not.
reset
The default reset value for the timer. This value is used when the timer::reset command is invoked without specifying the optional time value.
afterid
The id of the delayed Tcl event which updates the timer's elapsed time.
time
The value of the timer's current time, formatted as 00:00:00.000.
now
The number of milliseconds corresponding to the timer's current time.
hours
The number of hours (>= 0) corresponding to the timer's current time.
minutes
The number of minutes (0-59) corresponding to the timer's current time.
seconds
The number of seconds (0-59) corresponding to the timer's current time.
milliseconds
The number of milliseconds (0-999) corresponding to the timer's current time.
-alarm
The command callback invoked whenever a countdown timer reaches 0.
-interval
The interval (in milliseconds) between updates of the timer's current time. Defaults to 1 millisecond.
-reset
The default time (in milliseconds) that the timer will be reset to.
-stop
The command callback invoked whenever the timer is stopped.
-update
The command callback invoked whenever the timer's current time is updated.

EXAMPLE

  package require timer

  set timer [timer::create]

  entry  .value -textvariable ${timer}(time) -width 12
  button .start -text "Start/Stop" -command [list timer::startstop $timer]
  button .reset -text "Reset"      -command [list timer::reset     $timer]

  pack .value .start .reset -side left

BUGS

Does not handle negative time values.
Multiple timers running simultaneously with small update intervals may cause problems with the tcl event loop.


Copyright (C) 2002-2003, Mark G. Saye <markgsaye@yahoo.com>