Timer

From REALbasicWiki

Overall article skill

✭

Timer class
Available on
General
Superclass	Object
Interfaces	ActionSource
Constants
Values for property Mode ModeOff = 0 ModeSingle = 1 ModeMultiple = 2
Methods
Reset
Properties
Enabled as boolean Index as integer Left as integer Mode as integer Period as integer Top as integer
Events
Action
NOTE: You can get descriptions of the items above from the REALbasic documentation.

A Timer is an object that executes a method periodically.

Contents 1 Methods 1.1 Sub AddActionNotificationReceiver(receiver as ActionNotificationReceiver) 1.2 Sub RemoveActionNotificationReceiver(receiver as ActionNotificationReceiver) 1.3 Sub Reset() 2 Properties 2.1 Enabled as Boolean 2.2 Index as Integer 2.3 Left as Integer 2.4 Period as Integer 2.5 Mode as Integer 2.6 Width as Integer 3 Events 3.1 Sub Action() 4 Discussion 4.1 How Often Does a Timer Actually Fire? 4.1.1 Timers in Console Applications 5 Usage 5.1 Periodic polling 5.2 Delaying actions 6 Sample Code

[edit] Methods

[edit] Sub AddActionNotificationReceiver(receiver as ActionNotificationReceiver)

Adds an ActionNotificationReceiver to receive notifications when Action is called.  

[edit] Sub RemoveActionNotificationReceiver(receiver as ActionNotificationReceiver)

Removes the ActionNotificationReceiver.  

[edit] Sub Reset()

Reset resets a Timer to the start of its period. It does not affect the value of the Enabled property.

[edit] Properties

[edit] Enabled as Boolean

This property allows you to enable or disable a Timer. It is set to true by default. Changing the value of this property does not affect the value of the Mode property.

[edit] Index as Integer

This is the index of a Timer object when part of a control array. Timer used to inherit from Control, and this property is an artifact of that.

[edit] Left as Integer

This read-only property is an artifact of a time when Timer inherited from Control.

[edit] Period as Integer

This is the interval in milliseconds between invocations of a Timer's Action event handler. The default value of Period is 1000. Setting Period to a value less than 1 will result in Period being set to 1. See the discussion section for more on how often a Timer actually calls Action.

[edit] Mode as Integer

Mode accepts or returns one of the three values Timer.ModeOff, Timer.ModeSingle, Timer.ModeMultiple.

[edit] Width as Integer

This read-only property is an artifact of a time when Timer inherited from Control.

[edit] Events

[edit] Sub Action()

The periodic action of a Timer is implemented in the Action event handler.

[edit] Discussion

[edit] How Often Does a Timer Actually Fire?

It is useful to remember that Timers are not precision instruments.

Timer.Action is called in the course of the main event loop if Period milliseconds have elapsed following one of the following events:

• the last invocation of Action
• Reset was called
• Timer.Mode was changed to ModeSingle or ModeMultiple
• Enabled was changed to true.

But one cannot know how long the main event loop will take; nor can one say in general how long another Thread will run before it yields. Thus it is not really possible to predict when Timer.Action will be called; it is only possible to say when Timer.Action will not be called.

[edit] Timers in Console Applications

In console applications, Timers are checked and Action handlers called only when App.DoEvents is called.

[edit] Usage

[edit] Periodic polling

Primarily, a Timer is used to perform periodic actions, such as checking every second for a change of state of things that cannot be detected by Event handlers. Often, this procedure is called polling (i.e. looking actively for a change).

An example:

As there is no REALbasic-provided Event for the appearance and disappearance of disk volumes (e.g. USB hard drives), the code in a Timer.Action event could get the list of currently available volumes, compare it to the previously recorded list, and detect changes to the availability of volumes that way.

[edit] Delaying actions

One-shot timers (Single Shot) are useful to perform a delayed action.

Some examples:

• To detect if the mouse hovers over a certain control for longer than a second, one would restart a one-shot Timer with a Period of 1000 from inside the control's MouseMove event. The control's MouseExit event would stop the timer (set Enabled to false).
• Since Timers execute their Action event only when no other code of the main thread runs, they can be used to perform "cleanup" work that needs to be done while no other event is being handled. See Postponing an action using a Timer for an example.

[edit] Sample Code

(none yet)