Add Method

Applies to TestComplete 15.10, last modified on December 15, 2021

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:

Timers

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
Python
VBScript
DelphiScript
C++Script, C#Script

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.
  pass

VBScript

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

Highlight search results