Description
The method creates a new Timer object with the specified attributes, adds this object to the TimersObj collection and returns a reference to the new object.
Declaration
TimersObj.Add(Interval, TimerProc, Enabled)
| TimersObj | An expression, variable or parameter that specifies a reference to a Timers object | |||
| Interval | [in] | Required | Integer | |
| TimerProc | [in] | Required | String | |
| Enabled | [in] | Required | Boolean | |
| Result | A Timer object |
|||
Applies To
The method is applied to the following object:
Parameters
The method has the following parameters:
Interval
Specifies the number of milliseconds the timer will wait before executing the timer routine. Interval should be greater than 0. The value of 0 is possible, but the timer will not execute the timer routine.
Windows XP: If Interval is greater than 2147483647, it is set to 1. If Interval is less than 10, it is set to 10.
Windows Server 2003: If Interval is greater than 2147483647, it is set to 2147483647.
| Note: | The Interval parameter specifies the approximate time period needed to call the timer routine. The actual period passed between two calls to the timer routine depends on several factors: the number of active timers, the execution time of other timers’ rotuines, the current load of the system, etc. |
TimerProc
Specifies the script routine that will be executed after the specified number of milliseconds has passed. The script routine must be specified in the format “unit_name.routine_name” and it must not use any parameters.
Enabled
Specifies whether the timer is enabled. If this parameter is True, the timer is enabled and it calls the script routine periodically at time intervals specified by the Interval parameter. If the Enabled parameter is False, the timer is inactive and the timer’s script routine is not called.
Result Value
The method returns a referene to the new Timer object. If a new timer cannot be created, the method posts an error message to the test log and returns a null Variant value.
Remarks
The method creates a new Timer object and adds it to the Timers collection specified by TimerObj. To address the new timer in scripts, you can use the Items property of the Timers collection, or you can store a reference to the timer returned by this method to a variable.
The created Timer object exists until you delete it using the Delete or Clear method of the Timers collection, or until the script run is over.
After you created a new Timer object, you can assign a name to it. You can then obtain the timer from the Timers collection by this name. See Timers.Items.
A new Timer object starts counting milliseconds only after it has been enabled. The timer’s script routine is not called at the moment of timer creation.
Example
The code below demonstrates how you can add a new Timer object to the Timers collection and modify the timer’s properties.
JavaScript, JScript
function TestProc()
{
// Adds a new object to the Timers collection
Timer1 = Utils.Timers.Add(10000, "Unit1.TimerRoutine", true);
// Modifies the timer’s properties
Timer1.Name = "MyTimer";
Timer1.Interval = 20000;
Timer1.TimerProc = "Timers.NewTimerRoutine";
}
function TimerRoutine()
{
// Specify your code here.
// This routine will be executed after the specified timeout expires.
}
function NewTimerRoutine()
{
// Specify your code here.
// This is a new timer routine.
}
Python
def TestProc():
# Adds a new object to the Timers collection
Timer1 = Utils.Timers.Add(10000, "Unit1.TimerRoutine", True)
# Modifies the timer's properties
Timer1.Name = "MyTimer"
Timer1.Interval = 20000
Timer1.TimerProc = "Timers.NewTimerRoutine"
def TimerRoutine():
# Specify your code here.
# This routine will be executed after the specified timeout expires.
pass
def NewTimerRoutine():
# Specify your code here.
# This is a new timer routine.
passVBScript
Sub TestProc
' Adds a new object to the Timers collection
Set Timer1 = Utils.Timers.Add(10000, "Unit1.TimerRoutine", True)
' Modifies the timer’s properties
Timer1.Name = "MyTimer"
Timer1.Interval = 20000
Timer1.TimerProc = "Timers.NewTimerRoutine"
End Sub
Sub TimerRoutine
' Specify your code here.
' This routine will be executed after the specified timeout expires.
End Sub
Sub NewTimerRoutine
' Specify your code here.
' This is a new timer routine.
End Sub
DelphiScript
procedure TestProc;
begin
// Adds a new object to the Timers collection
Timer1 := Utils.Timers.Add(10000, 'Unit1.TimerRoutine', true);
// Modifies the timer’s properties
Timer1.Name := 'MyTimer';
Timer1.Interval := 20000;
Timer1.TimerProc := 'Timers.NewTimerRoutine';
end;
procedure TimerRoutine;
begin
// Specify your code here.
// This routine will be executed after the specified timeout expires.
end;
procedure NewTimerRoutine;
begin
// Specify your code here.
// This is a new timer routine.
end;
C++Script, C#Script
function TestProc()
{
// Adds a new object to the Timers collection
Timer1 = Utils["Timers"]["Add"](10000, "Unit1.TimerRoutine", true);
// Modifies the timer’s properties
Timer1["Name"] = "MyTimer";
Timer1["Interval"] = 20000;
Timer1["TimerProc"] = "Timers.NewTimerRoutine";
}
function TimerRoutine()
{
// Specify your code here.
// This routine will be executed after the specified timeout expires.
}
function NewTimerRoutine()
{
// Specify your code here.
// This is a new timer routine.
}
See Also
Using Timers
Timer Object
Timers.Items
Timers.Delete
Timers.Clear
Timer.Enabled
Timer.Interval
Timer.TimerProc
Timer.Name