timer Starts a timer
Usage
timer [-s] [-p] (<name>,<delay_in_msecs>[,<callback_param1>[,<callback_param2>[,...]]]) { <callback_command> }
Description

Starts a new timer named <name> with the specified delay (in milliseconds).
The timer periodically calls the specified <callback_command> code passing the eventual <callback_param> strings as positional parameters.
If a timer with the same name already exists, it is replaced by this one.
The <callback_command> is evaluated at timer shot time and not while this command is being parsed. This means that the identifiers that you put inside <callback_command> will not have the current values. The values will be assigned at timer shot time.
This is a common scripters error and problem: if it is not clear, look at the examples below.
The timer is bound to the window in that this command is executed in.
If the window gets destroyed, the timer is stopped; unless the -p switch is used.
The -p switch causes the timer to be persistent across the application and exists until the last window has been closed: it is basically rebound to another (random) window when the original window is destroyed.
The -s switch causes this timer to trigger only once: it will be automatically destroyed after that.
The time has an associated set of extended scope variables: the variables that begin with %: have their life extended to the whole life of the timer.
Using a very low delay is a common method to perform some background processing: you basically split a huge job in small slices and execute them when the timer is triggered until you run out of slices. A delay of 0 will cause the timer to be called whenever KVIrc has some idle time to spend. On the other hand, remember that timers are precious resources: many timers running with a very low delay will cause KVIrc to slow down.
Since all the KVIrc timers share the same namespace it is a good idea to use descriptive timer names: a timer named a is likely to be used by two or more scripts at once causing one (or both) of them to fail.
A timer can be stopped at any time by using the killtimer command.

Switches

-s | --single-shot
Causes the timer to trigger only once (single shot timer)
-p | --persistent
Creates a persistent timer bound to any existing window

Examples

# Just a plain timer
timer(test,1000){ echo "Hello!"; }
# Now watch the timer running
killtimer test
# Single shot timer
timer -s (test,1000){ echo "This will fire only once!"; }
# The call above is equivalent to
timer(test,1000){ echo "This will file only once!"; killtimer test; }
# Callback parameters: consider the following code
%parameter = "some string value"
echo "Before calling /timer \%parameter is \"%parameter\""
timer -s (test,1000,%parameter){ echo "inside the callback \%parameter is \"%parameter\" but \$0 is \"$0\""; }
# watch the timer running, and note the behaviour of the %parameter variable
killtimer test
# Use the extended scope timer variables
timer(test,1000)
{
# Use the extended scope %:count variable to keep track
# of the times that this timer has been called
if("%:count" == "")%:count = 1
else %:count++
echo "This timer has fired %:count times"
if(%:count == 10)
{
# This will kill the current timer, we don't need to specify the name
killtimer
}
}
# Use isTimer to check if the timer exists
echo $istimer(test)
# Repeat the command above after the 10th timeout...

# Execute a command at a precise time
%secsfrom= $($date("H")*3600+$date("M")*60+$date("S")); #now
%secsto= $(7*3600+10*60+0); #end time: 07:10:00
%secsdiff=$(%secsto-%secsfrom); #difference
if(%secsdiff <= 0)
{
#we're past that time for today
%secsdiff+=86400; #60 secs * 60 mins * 24 hours
}
# timer wants msecs
%msecs = $(%secsdiff*1000);
timer -s -p (reminder, %msecs)
{
echo "Hey man it's ten past seven am, time to wake up!"
}

See also
killtimer

Index, Commands