Class

# Timer

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

A <span class="title-ref">Timer</span> 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

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                     | Type                               | Read-Only | Shared |
|--------------------------|------------------------------------|-----------|--------|
| `Enabled<timer.enabled>` | `Boolean</api/data_types/boolean>` |           |        |
| `Period<timer.period>`   | `Integer</api/data_types/integer>` |           |        |
| `RunMode<timer.runmode>` | `RunModes<timer.runmodes>`         |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                                       | Parameters                                                                                                                                                                     | Returns | Shared |
|----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|--------|
| `AddActionNotificationReceiver<timer.addactionnotificationreceiver>`       | receiver As `ActionNotificationReceiver</api/language/actionnotificationreceiver>`                                                                                             |         |        |
| `CallLater<timer.calllater>`                                               | afterMilliseconds As `Integer</api/data_types/integer>`, method As `Timer.TimerCallLater<timer.timercalllater>`                                                                |         | ✓      |
|                                                                            | afterMilliseconds As `Integer</api/data_types/integer>`, method As `Timer.TimerCallLaterWithValue<timer.timercalllaterwithvalue>`, value As `Variant</api/data_types/variant>` |         | ✓      |
| `CancelCallLater<timer.cancelcalllater>`                                   | method As `Timer.TimerCallLater<timer.timercalllater>`                                                                                                                         |         | ✓      |
|                                                                            | method As `Timer.TimerCallLaterWithValue<timer.timercalllaterwithvalue>`                                                                                                       |         | ✓      |
| `RemoveActionNotificationReceiver<timer.removeactionnotificationreceiver>` | receiver As `ActionNotificationReceiver</api/language/actionnotificationreceiver>`                                                                                             |         |        |
| `Reset<timer.reset>`                                                       |                                                                                                                                                                                |         |        |

## Events

<div class="rst-class">

table-centered_column_4

</div>

| Name                   | Parameters | Returns |
|------------------------|------------|---------|
| `Action<timer.action>` |            |         |
| `Run<timer.run>`       |            |         |

## Delegate Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                     | Parameters                                  | Returns |
|----------------------------------------------------------|---------------------------------------------|---------|
| `TimerCallLater<timer.timercalllater>`                   |                                             |         |
| `TimerCallLaterWithValue<timer.timercalllaterwithvalue>` | value As `Variant</api/data_types/variant>` |         |

## Enumerations

<div id="timer.runmodes">

<div class="rst-class">

forsearch

</div>

</div>

Timer.RunModes

### RunModes

> Specifies the mode (off, single or multiple) in which the <span class="title-ref">Timer</span> will run.
>
> | Enum     | Description                                                                                                                      |
> |----------|----------------------------------------------------------------------------------------------------------------------------------|
> | Off      | Disables the <span class="title-ref">Timer</span>. 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 <span class="title-ref">Timer</span> to Off. |
> | Multiple | Call the Action/Run event handler each time the Period is reached.                                                               |

## Property descriptions

<div id="timer.enabled">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.Enabled

**Enabled** As `Boolean</api/data_types/boolean>`

> Enables you to turn the <span class="title-ref">Timer</span> on or off.
>
> When Enabled is `True</api/language/true>`, the <span class="title-ref">Timer</span> is on. Enabled is set to `True</api/language/true>` when you instantiate a <span class="title-ref">Timer</span>. If you turn the <span class="title-ref">Timer</span> off and then turn it on, it resets itself to the start of the period. Defaults to `True</api/language/true>`.
>
> This example is in the Pressed event of a button control.
>
> ``` xojo
> Timer1.Enabled = False
> ```

<div id="timer.period">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.Period

**Period** As `Integer</api/data_types/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 <span class="title-ref">Timer</span> 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 Windows Opening event) sets the Period to 500 milliseconds.
>
> ``` xojo
> Timer1.Period = 500
> ```

<div id="timer.runmode">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.RunMode

**RunMode** As `RunModes<timer.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<timer.runmodes>` for a list of possible modes.
>
> Setting RunMode will restart the <span class="title-ref">Timer</span>, the same as calling `Reset<timer.reset>`, even if the value hasn't changed.
>
> Set the mode to Single:
>
> ``` xojo
> Timer1.RunMode = Timer.RunModes.Single
> ```

## Method descriptions

<div id="timer.addactionnotificationreceiver">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.AddActionNotificationReceiver

**AddActionNotificationReceiver**(receiver As `ActionNotificationReceiver</api/language/actionnotificationreceiver>`)

> Registers an `ActionNotificationReceiver</api/language/actionnotificationreceiver>`.

<div id="timer.calllater">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.CallLater

**CallLater**(afterMilliseconds As `Integer</api/data_types/integer>`, method As `Timer.TimerCallLater<timer.timercalllater>`)

> Used to call a method (without parameters) once after the specified delay in milliseconds.
>
> This method is `shared</api/language/shared>`.
>
> Multiple uses of CallLater for the same Delegate method will schedule multiple calls to the method.

**CallLater**(afterMilliseconds As `Integer</api/data_types/integer>`, method As `Timer.TimerCallLaterWithValue<timer.timercalllaterwithvalue>`, value As `Variant</api/data_types/variant>`)

> Used to call a method (with a parameter) once after the specified delay in milliseconds.
>
> This method is `shared</api/language/shared>`.
>
> Multiple uses of CallLater for the same Delegate method will schedule multiple calls to the method.
>
> To pass a parameter to your CallLater method, the method signature must exactly match the <span class="title-ref">Timer</span> Delegate signature. Specifically this means that the method must have a single parameter that is of type `Variant</api/data_types/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):
>
> ``` xojo
> 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:
>
> ``` xojo
> 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</api/data_types/variant>` as shown here:
>
> ``` xojo
> 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:
>
> ``` xojo
> MyLabel.Text = "First help text goes here"
> Timer.CallLater(2000, AddressOf SetLabel, "Second help text goes here")
> ```

<div id="timer.cancelcalllater">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.CancelCallLater

**CancelCallLater**(method As `Timer.TimerCallLater<timer.timercalllater>`)

**CancelCallLater**(method As `Timer.TimerCallLaterWithValue<timer.timercalllaterwithvalue>`)

> Used to cancel a previously scheduled CallLater that has not yet been run.
>
> This method is `shared</api/language/shared>`.
>
> If there are multiple pending calls for the Delegate method, all will be canceled.
>
> Cancel the ClearLabel callback:
>
> ``` xojo
> Timer.CancelCallLater(AddressOf ClearLabel)
> ```
>
> Cancel the SetLabel callback:
>
> ``` xojo
> Timer.CancelCall(AddressOf SetLabel)
> ```

<div id="timer.removeactionnotificationreceiver">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.RemoveActionNotificationReceiver

**RemoveActionNotificationReceiver**(receiver As `ActionNotificationReceiver</api/language/actionnotificationreceiver>`)

> Unregisters an ActionNotificationReceiver.

<div id="timer.reset">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.Reset

**Reset**

> Restarts the <span class="title-ref">Timer</span>, but does not change its settings.
>
> Setting `RunMode<timer.runmode>` will also restart the <span class="title-ref">Timer</span>, even if its value has not changed.
>
> This code is in the Pressed event of a button:
>
> ``` xojo
> Timer1.Reset
> ```

## Event descriptions

<div id="timer.action">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.Action

**Action**

> The Action event handler contains the code that will execute after the specified Period and in the specified RunMode.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> This event is supported for desktop and console projects only. For mobile projects, use the `Run<timer.run>` event.
>
> </div>
>
> This example reports the arrow key the user pressed.
>
> ``` xojo
> 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
> ```

<div id="timer.run">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.Run

**Run**

> The Run event handler contains the code that will execute after the specified Period and in the specified RunMode.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> This event is supported for mobile projects only. For desktop and console projects, use the `Action<timer.action>` event.
>
> </div>

## Delegate descriptions

<div id="timer.timercalllater">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.TimerCallLater

**TimerCallLater**

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

<div id="timer.timercalllaterwithvalue">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Timer.TimerCallLaterWithValue

**TimerCallLaterWithValue**(value As `Variant</api/data_types/variant>`)

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

## Notes

Because it is subclassed from `Object</api/data_types/additional_types/object>` rather than `DesktopUIControl</api/user_interface/desktop/desktopuicontrol>`, you can instantiate it via code with the `New</api/language/new>` operator.

<span class="title-ref">Timer</span> code runs in the main thread, the same as all other non-`Thread</api/language/threading/thread>` code. This means a <span class="title-ref">Timer</span> 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 <span class="title-ref">Timer</span> from running at the intervals specified.

Although the <span class="title-ref">Timer</span> 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 <span class="title-ref">Timer</span> is not a control. It is subclassed from `Object</api/data_types/additional_types/object>`. This means you can create <span class="title-ref">Timers</span> in your code via the `New</api/language/new>` operator, just as with other objects.

The `RunMode<timer.runmode>` property controls the interval used to execute the <span class="title-ref">Timer</span>'s Action/Run event handler. If the `RunMode<timer.runmode>` is not `RunModes<timer.runmodes>`.Off, the <span class="title-ref">Timer</span> waits for the Period to pass before executing the Action/Run event handler. If the `RunMode<timer.runmode>` is set to `RunModes<timer.runmodes>`.Off at Runtime, the <span class="title-ref">Timer</span> will immediately cease waiting and the Action/Run event handler will no longer be executed.

The <span class="title-ref">Timer</span> will continue to execute its Action/Run event handler (assuming the `RunMode<timer.runmode>` property is not set to `RunModes<timer.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 <span class="title-ref">Timer</span>'s Action/Run event handler. The <span class="title-ref">Timer</span> has been designed so that it yields time to other applications running on the computer so as not to bog down the machine.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### <span class="title-ref">Timers</span> in web projects

<span class="title-ref">Timers</span> in web projects will execute outside of all sessions. If you need a <span class="title-ref">Timer</span> that knows the session in which it is executing, use a `WebTimer</api/web/webtimer>` instead.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Using a <span class="title-ref">Timer</span> with AddHandler

When creating a <span class="title-ref">Timer</span> in code, the <span class="title-ref">Timer</span> starts when you set the mode to either `RunModes<timer.runmodes>`.Single or `RunModes<timer.runmodes>`.Multiple. Refer to the `AddHandler</api/language/addhandler>` command for an example on how to use a method to handle the <span class="title-ref">Timer</span>'s Action/Run event.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Limitations on Microsoft Windows

On Windows, the standard system <span class="title-ref">Timer</span> is used which has a default resolution of about 15ms.

Source: [Stack Overflow](http://stackoverflow.com/questions/3744032/why-are-net-timers-limited-to-15-ms-resolution)

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<div id="/api/language/timer/updating_the_user_interface_using_a_timer">

Updating the user interface using a <span class="title-ref">Timer</span> \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*

</div>

Because a <span class="title-ref">Timer</span> (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</api/language/threading/thread>` to keep the user interface responsive. See the `Thread</api/language/threading/thread>` class for information on how to properly update your application's user interface from a `Thread</api/language/threading/thread>`.

## Sample code

A <span class="title-ref">Timer</span> can be used to monitor keydown events. The following code in the `Action<timer.action>` event of a <span class="title-ref">Timer</span> (`RunModes<timer.runmodes>`.Multiple, `Period<timer.period>` = 100) detects whether the Up, Down, Left, or Right arrow keys are pressed.

``` xojo
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

|                       |     |
|-----------------------|-----|
| **Project Types**     | All |
| **Operating Systems** | All |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `Object</api/data_types/additional_types/object>`, `Thread</api/language/threading/thread>`, `WebTimer</api/web/webtimer>` classes; `AddHandler</api/language/addhandler>` command.

</div>