UserGuide:Timers

Types of Timers

Desktop projects can use the Timer or the Xojo.Core.Timer class to create timers.

Web projects can use the WebTimer, Timer or the Xojo.Core.Timer class to create timers. In most case you will want to use the WebTimer class which creates a timer that runs in the browser. Timers created using Timer or Xojo.Core.Timer run on the server.

iOS projects can use the Xojo.Core.Timer class to create timers.

Each type of Timer has an Action event handler where you can put the code you want to run along with Period and Mode properties that let you specify how often the Action event handler is called. In all cases, code run from a timer runs in the main (UI) thread so it is best to not have long-running code called by a timer as it will block the rest of your app from being able to do anything. This also means that if your app is busy doing processing it will be unable to call the Timer when its period is reached. If you need more precise control of your processing you will want to use Threading.

Avoid having long-running code called by a timer as it will block the rest of your app.

Using a Timer in a Desktop Project

For desktop projects, you can use the Timer class or the Xojo.Core.Timer class to create a timer.

The code that you want to run periodically goes in the Action event. You specify the period in milliseconds using the Period property. It tells the timer how frequently the Action event is called. The Mode property is used in conjunction with this to specify if the timer is set to run multiple times, just a single time or is off completely.

You can drag a Timer from the Library onto your layout to create a Timer subclass that you can use. When you do this you get the classic Timer class. You put the code you want to run when the timer period is reached in its Action event handler. For a Timer that is set to run multiple times (Mode = ModeMultiple) and with a Period of 500 (1/2 second).

The following code in a timer will increase a counter displayed in a Label about every 1/2 second:

Dim value As Integer
value = Val(CounterLabel.Text)
value = value + 1
CounterLabel.Text = Str(value)

Xojo.Core.Timer is an alternative Timer class that works similarly. To add a Xojo.Core.Timer to a layout, drag the Generic Object control from the Library and change its Super to "Xojo.Core.Timer". You can then set its properties in the Window Open event and add the Action event handler to run code as above.

Xojo.Core.Timer has a few additional capabilities which might make you prefer it over a standard Timer. You can set a Tolerance to tell the OS how precise you need the timer to be. A less precise timer makes better use of system resources and will not impact the battery on portable devices as much. Xojo.Core.Timer also has CallLater methods that are handy for when you need a one-time timer (for example to update the UI after a short period of time) and don't want to create a subclass.

For example, 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 another method, you set the Label help text and then use CallLater to tell the Timer to call the Clear method after 2 seconds: MyLabel.Text = "Help text goes here"

Xojo.Core.Timer.CallLater(2000, AddressOf ClearLabel)

Using a Timer in a Web Project

Web projects can use the WebTimer class to create a timer that runs in the web browser. This is useful for creating a session-specific timer that updates the UI. The simplest way to do this is to drag a Timer from the Library onto your layout, set the Period and Mode properties and add the Action event.

The same code from above also works with a web project increase a counter displayed in a Label every 1/2 second:

Dim value As Integer
value = Val(CounterLabel.Text)
value = value + 1
CounterLabel.Text = Str(value)

You can also use Timer and Xojo.Core.Timer in a web app but these will run on the server and will not be session-specific so they are far less useful.

Using a Timer in an iOS Project

iOS projects must use Xojo.Core.Timer to create a timer. You can drag the Timer from the Library onto your layout to add a timer. Set its Mode and Period properties and add the Action event for your code.

With a Period of 500 (milliseconds) and a Mode of Multiple, this code will increment a counter in a Label:

Dim value As Integer
value = Integer.FromText(CounterLabel.Text)
value = value + 1
CounterLabel.Text = value.ToText

Using AddHandler with a Timer

You can also use a Timer without adding it to the layout, at least in desktop and iOS projects. In this case you would create a Timer instance in a property, create a method to serve as its Action event and then use the AddHandler command to tell the timer that the method will be called in place of the Action event.

Below is how you would do it for an iOS project.

Start by adding a property to the layout:

MyTimer As Xojo.Core.Timer

Next, add a ProgressBar to the layout (this example code uses iOSProgressBar). The Timer will simply update the ProgressBar. In the Open event handler of the layout, instantiate the Timer and indicate that its Action event handler should be handled by a method, TimerAction, that you will add to the layout:

MyTimer = New Xojo.Core.Timer
MyTimer.Period = 1000
MyTimer.Mode = Xojo.Core.Timer.Modes.Multiple
AddHandler MyTimer.Action, AddressOf TimerAction

Now add the TimerAction method to the layout:

Sub TimerAction(sender As Xojo.Core.Timer)
// This code works on iOS and uses iOSProgressBar.
// Change the properties as appropriate for desktop apps.
If ProgressBar1.CurrentValue < ProgressBar1.MaxValue Then
ProgressBar1.CurrentValue = ProgressBar1.CurrentValue + 1
Else
// Stop Timer and Remove the handler
sender.Mode = Xojo.Core.Timer.Mode.Off
RemoveHandler MyTimer.Action, AddressOf TimerAction
End If
End Sub

It is important that the first parameter to TimerAction must be of the type of the original object, in this case Xojo.Core.Timer. When you run the project, the ProgressBar is updated once per second.

Using Timer in a Console Project

To use Timer or Xojo.Core.Timer in a Console project you have to either subclass the timer or use AddHandler to map the Action event to a method as shown above. In addition you have to add an event loop to your Console project using DoEvents.

As an example, the following code uses a Xojo.Core.Timer with AddHandler to display output to the terminal about once a second.

Create a new Console project and add a property to the App object:

MyTimer As Xojo.Core.Timer

Add the Run event to the App object and put this code to initialize the timer and map its Action event to the TimerAction method:

MyTimer = New Xojo.Core.Timer
MyTimer.Period = 1000
MyTimer.Mode = Xojo.Core.Timer.Modes.Multiple
AddHandler MyTimer.Action, AddressOf TimerAction

While True
App.DoEvents
Wend

Now add the TimerAction method:

Public Sub TimerAction(sender As Xojo.Core.Timer)
Print("Timer called.")
End Sub

Run the project and you'll see "Timer called." output to the Terminal (or Command shell) about once a second. Press Control-C to quit the console app.

Example Projects

Examples/Desktop/Controls/ProgressBar
Examples/Desktop/UpdatingUIFromThread/UIThreadingWithTimer
Examples/iOS/Controls/ProgresExample
Examples/Web/Controls/ProgressBar
Examples/Web/Controls/TimerExample

UserGuide

Timers

From Xojo Documentation

Contents