Class

Timer

Description

A Timer is an object that can run code after a specified period of time has elapsed or at repeated time intervals. If added to a layout, it is not visible in the UI since it is not a control.

Properties

Name	Type	Read-Only	Shared
Enabled	Boolean
Period	Integer
RunMode	RunModes

Methods

Name	Parameters	Shared
AddActionNotificationReceiver	theReceiver As ActionNotificationReceiver
CallLater	afterMilliseconds As Integer, method As Timer.TimerCallLater	✓
	afterMilliseconds As Integer, method As Timer.TimerCallLaterWithValue, value As Variant	✓
CancelCallLater	method As Timer.TimerCallLater	✓
	method As Timer.TimerCallLaterWithValue	✓
RemoveActionNotificationReceiver	theReceiver As ActionNotificationReceiver
Reset

Events

Name	Parameters	Returns
Action
Run

Delegate Methods

Name	Parameters	Returns
TimerCallLater
TimerCallLaterWithValue	value As Variant

Enumerations

Timer.RunModes

RunModes

Specifies the mode (off, single or multiple) in which the Timer will run.

Enum	Description
Off	Disables the Timer. The Action/Run event handler is no longer called. This is the default.
Single	Calls the Action/Run event handler once after the Period is reached, then turns the Timer to Off.
Multiple	Call the Action/Run event handler each time the Period is reached.

Property descriptions

Timer.Enabled

Enabled As Boolean

Enables you to turn the Timer on or off.

When Enabled is True, the Timer is on. Enabled is set to True when you instantiate a Timer. If you turn the Timer off and then turn it on, it resets itself to the start of the period. Defaults to True.

This example is in the Pressed event of a button control.

Timer1.Enabled = False

Timer.Period

Period As Integer

The time (in milliseconds) between executions.

Periods of less than or equal to zero default to a value of 1 millisecond. The default value is 1000. The rate that a Timer can actually fire depends on the speed of the host computer, the operating system, and other tasks the computer is doing. It is possible to set Period to a value that cannot be achieved by the computer that is running the application.

This example (in the Timer.Opening event) sets the Period to 500 milliseconds.

Me.Period = 500

Timer.RunMode

RunMode As RunModes

The interval at which the Action/Run event will be executed. The default is Multiple for Timers added as a control. The default is Off for Timers created in code.

See RunModes for a list of possible modes.

Setting RunMode will restart the Timer, the same as calling Reset, even if the value hasn't changed.

Set the mode to Single:

Timer1.RunMode = Timer.RunModes.Single

Method descriptions

Timer.AddActionNotificationReceiver

AddActionNotificationReceiver(theReceiver As ActionNotificationReceiver)

Registers an ActionNotificationReceiver.

Timer.CallLater

CallLater(afterMilliseconds As Integer, method As Timer.TimerCallLater)

Used to call a method (without parameters) once after the specified delay in milliseconds.

CallLater(afterMilliseconds As Integer, method As Timer.TimerCallLaterWithValue, value As Variant)

Used to call a method (with a parameter) once after the specified delay in milliseconds.

This method is shared.

To pass a parameter to your CallLater method, the method signature must exactly match the Timer Delegate signature. Specifically this means that the method must have a single parameter that is of type Variant. No other type will work (even if it can convert to Variant).

Refer to the sample below to see how this is done.

Suppose you want to display some help text for a few seconds and then hide it. You can do this by creating a method to clear a Label (ClearLabel):

Sub ClearLabel
  MyLabel.Text = ""
End Sub

In the initial method, you set the Label help text and then use CallLater to set it to clear it after 2 seconds:

MyLabel.Text = "Help text goes here"
Timer.CallLater(2000, AddressOf ClearLabel)

Suppose you want to display some help text for a few seconds and then replace it with different text. You can do this by creating a method that takes the text to display as a parameter (SetLabel). Remember the Delegate method parameter must be of type Variant as shown here:

Sub SetLabel(helpText As Variant)
  MyLabel.Text = helpText
End Sub

In the initial method, you set up the Label help text and use CallLater to change it after 2 seconds:

MyLabel.Text = "First help text goes here"
Timer.CallLater(2000, AddressOf SetLabel, "Second help text goes here")

Timer.CancelCallLater

CancelCallLater(method As Timer.TimerCallLater)

CancelCallLater(method As Timer.TimerCallLaterWithValue)

Used to cancel a previously scheduled CallLater that has not yet been run.

This method is shared.

Cancel the ClearLabel callback:

Timer.CancelCallLater(AddressOf ClearLabel)

Cancel the SetLabel callback:

Timer.CancelCall(AddressOf SetLabel)

Timer.RemoveActionNotificationReceiver

RemoveActionNotificationReceiver(theReceiver As ActionNotificationReceiver)

Unregisters an ActionNotificationReceiver.

Timer.Reset

Reset

Restarts the Timer, but does not change its settings.

Setting RunMode will also restart the Timer, even if its value has not changed.

This code is in the Pressed event of a button:

Timer1.Reset

Event descriptions

Timer.Action

Action

The Action event handler contains the code that will execute after the specified Period and in the specified RunMode.

Important

This event is supported for desktop and console projects only. For mobile projects, use the Run event.

This example reports the arrow key the user pressed.

If Keyboard.AsyncKeyDown(&h7B) Then
  ' do something with the left arrow key
  MessageBox("Left")
End If
If Keyboard.AsyncKeyDown(&h7C) Then
  ' do something with the right arrow key...
  MessageBox("Right")
End If
If Keyboard.AsyncKeyDown(&h7D) Then
  ' do something with the down arrow key...
  MessageBox("Down")
End If
If Keyboard.AsyncKeyDown(&h7E) Then
  ' do something with the Up arrow key...
  MessageBox("Up")
End If

Timer.Run

Run

The Run event handler contains the code that will execute after the specified Period and in the specified RunMode.

Important

This event is supported for mobile projects only. For desktop and console projects, use the Action event.

Delegate descriptions

Timer.TimerCallLater

TimerCallLater

Any method that does not have a parameter can be used with CallLater and CancelCallLater.

Timer.TimerCallLaterWithValue

TimerCallLaterWithValue(value As Variant)

Any method with a single Variant parameter can be used with CallLater or CancelCallLater.

Notes

Because it is subclassed from Object rather than DesktopUIControl, you can instantiate it via code with the New operator.

Timer code runs in the main thread, the same as all other non-Thread code. This means a Timer cannot run if other code in the main thread is running. If you have a long-running process in the main thread, it could prevent your Timer from running at the intervals specified.

Although the Timer appears in the list of Built-in controls in the Library, this is done only as a convenience to programmers. In terms of the object hierarchy, the Timer is not a control. It is subclassed from Object. This means you can create Timers in your code via the New operator, just as with other objects.

The RunMode property controls the interval used to execute the Timer's Action/Run event handler. If the RunMode is not RunModes.Off, the Timer waits for the Period to pass before executing the Action/Run event handler. If the RunMode is set to RunModes.Off at Runtime, the Timer will immediately cease waiting and the Action/Run event handler will no longer be executed.

The Timer will continue to execute its Action/Run event handler (assuming the RunMode property is not set to RunModes.Off) regardless of whether the window is frontmost or not. The visibility of the window also has no impact on the execution of a Timer's Action/Run event handler. The Timer has been designed so that it yields time to other applications running on the computer so as not to bog down the machine.

Timers in web projects

Timers in web projects will execute outside of all sessions. If you need a Timer that knows the session in which it is executing, use a WebTimer instead.

Using a Timer with Addhandler

When creating a Timer in code, the Timer starts when you set the mode to either RunModes.Single or RunModes.Multiple. Refer to the AddHandler command for an example on how to use a method to handle the Timer's Action/Run event.

Limitations on Microsoft Windows

On Windows, the standard system Timer is used which has a default resolution of about 15ms.

Source: Stack Overflow

Updating the user interface using a Timer

Because a Timer (and thus its Run event handler) always runs in the main thread, it can be used to update the user interface for long-running processes within threads.

Typically you put long-running processes within a Thread to keep the user interface responsive. See the Thread class for information on how to properly update your application's user interface from a Thread.

Sample code

A Timer can be used to monitor keydown events. The following code in the Action event of a Timer (RunModes.Multiple, Period = 100) detects whether the Up, Down, Left, or Right arrow keys are pressed.

If Keyboard.AsyncKeyDown(123) Then
  Label1.Text = "left arrow key"
End If
If Keyboard.AsyncKeyDown(124) Then
  Label1.Text = "right arrow key"
End If
If Keyboard.AsyncKeyDown(125) Then
  Label1.Text = "down arrow key"
End If
If Keyboard.AsyncKeyDown(126) Then
  Label1.Text = "Up arrow key"
End If

Compatibility

All project types on all supported operating systems.