UserGuide

Mobile Controllers

From Xojo Documentation

Timer

iOS Timer Library Icon

A Timer is not actually a user interface control, but it is often used with user interface controls. A Timer runs code at periodic intervals, which is useful for updating progress, animation and anything else that requires the user interface to be updated periodically.

Below are the common events, properties and methods. Refer to the Timer control in the Language Reference for for all its details.

Events

Run

This event is called when the Timer interval is reached, as specified by its RunMode and Period.

Properties

RunMode

The RunMode of a Timer indicates how its Run event gets called. It can have one of three values from the Timer.RunModes enumeration:
  • Off: The Run event is not called.
  • Single: The Run event is called once when the Period is reached.
  • Multiple: The Run event is called each time the Period is reached.

Period

Indicates (in milliseconds) how frequently the Run event is called.

Methods

CallLater

Used to set up a Timer that will call a method at when the Period is reached.

CancelCall

Used to cancel a Timer set up with CallLater.

Usage

When you add a Timer to a Layout, the Inspector shows the RunMode and Period properties. As noted above, the RunMode can be Off, Single or Multiple (the default). Period defaults to 1000 milliseconds (1 second).

A Timer is used to update the user interface. Your app code runs in what is called the "main thread". Timer code also runs in the main thread. If you have a long-running process, it is possible that the Timer's Run event handler call could be delayed until the process finishes. Essentially, a Timer's Run event is only called when the app is idle. This is fine for nearly all cases because and app is most often in the idle state.

Another way to think of a Timer is that it is a "waiter". It waits at least until the Period has elapsed and the app is idle. When those conditions are met, it runs its Run event handler.

You can change the RunMode and Period values within the Timer's Run event handler in order to change how often the Timer runs or to stop it from running entirely.

This code updates a Progress Bar every 1/2 second (RunMode = Multiple and Period = 500) and then turns the Timer off when the Maximum of the Progress Bar is reached:

ProgressBar1.Value = ProgressBar1.Value + 1

// Stop Timer when ProgressBar reaches maximum
If ProgressBar1.Value > ProgressBar1.MaxValue Then
Me.RunMode = Timer.RunModes.Off
End If

Timers are also used for animation, typically to tell a Canvas to redraw itself. If you have code in a Canvas Paint event handler that updates the position of some graphics, you can tell it to redraw itself from a Timer:

AnimationCanvas.Invalidate

You can also add Timers directly in code, but when you do so you have to provide a method that will be called in place of the Run event handler. For a Timer you only want to call once, you can do this using the CallLater method. You create a method that you want the Timer to call, such as this method which will clear a Label's text:

Sub ClearLabel
MyLabel.Text = ""
End Sub

Then you use the CallLater method to tell the Timer to call this method after a period of time. This code sets the Label text and then tells it to call the ClearLabel method after two seconds so that it gets cleared:

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

If you need a repeating Timer, you can create one and then assign a method to run in place of the Run event by using the AddHandler command. This code calls the TimerRun method once a second:

MyTimer = New Timer
MyTimer.Period = 1000
MyTimer.Mode = Timer.RunModes.Multiple

AddHandler MyTimer.Run, AddressOf TimerRun

If you use AddHandler with a Timer, you also need to call RemoveHandler at some point. You'll usually want to do this when the Timer is stopped or when the Layout containing the Timer is closed.

Generic Object

Generic Object Library Icon

A Generic Object is used to add classes that are not user interface controls to a Layout. These classes appear on the Shelf of the Layout. Adding classes in this manner makes it easier to implement their events. Because the class is now on the Layout, you can just click on it and select "Add Event Handler" to implement its event handlers. The alternative to this is creating a subclass, implementing the events on the subclass and then manually creating an instance via code.

After dragging a Generic Object onto your layout, you need to go to the Super field in the Inspector and change it to the name of the class you want to use.

See Also

Timer class; UserGuide:iOS User Interface Controls topic