SHIP:Node:timer

Node Home

Animations and delayed events or pauses require periodic or one-shot timers. The timer node fills this need in Template:SHIP.

The timer node is a 0.1s resolution event timer which can be set up to be free running or one-shot, with an auto-reload capability.

Parent Nodes

The following nodes are permitted to hold this node:

• box
• display
• group
• text
• page
• variable

Child Nodes

The following nodes are permitted to exist within this node:

• constant
• listener
• variable

Properties

Property	Data Type	Description
SHIP:Property:timer:name
enabled	Boolean	If true (default if unset) this timer is enabled.
alarm*	Boolean	Set to true at run-time when a timer's count value transitions from 1 to 0.
autoreload	Boolean	Determines whether or not period will be loaded into value automatically after it expires.
oneshot	Boolean	If set, the timer will stop when the count value is zero and self-set the enabled property to false
period	Integer	Value used by a timer to reload the countdown value after the timer has expired.
value	Integer	Remaining count-down value, in 10ths of a second, of the timer

*available at SHIPEngine run time only and cannot be set in SHIPTide. Use a Sail script at shiplaunch time if this property needs to be set when the GUI starts to run.

**available only in SHIPTide; cannot be accessed from Sail scripts at run-time.

Overview

The timer is a 0.1s resolution event timer which can be set up to be free-running or one-shot, with an auto-reload capability. The timer's value property represents the current remaining time on the given timer, in tenths of a seconds. For example, if the timer.value is 34, there are 3.4 seconds left on the timer before it hits 0.

When enabled is set to true and the timer.value property is non-zero, the timer begins to count down, with the value property decrementing ever 0.1Hz. On a count value transition from 1 to 0 (the timer expires), the alarm property is set to true. The alarm must be manually reset (set to false) by a Sail script.

In the majority of designs, a listener is attached to the alarm. When the alarm goes Template:Reference the associated script action is taken, often including restarting the timer.

Timer Modes of Operation

The two timer properties oneshot and autoreload determine the operational mode of a timer. These modes are:

Mode	oneshot	autoreload	Operation
0	false	false	Manual free-running operation When enabled, the timer will count down to zero then pause until a new non-zero count value is loaded by a Sail script. Setting the period has no effect.
1	false	true	Automatic free-running operation When enabled, the timer will count down to zero then re-load the value from the period and restart the count down process. A period value of zero will cause the timer to pause (still enabled) until a non-zero value is loaded into the value or period.
2	true	false	Manual one-shot operation When enabled with value non-zero, the timer will count down to zero then self-set enabled to false. The timer will restart when a non-zero value is loaded and the timer is re-enabled by a Sail script. Setting the period has no effect.
3	true	true	Automatic one-shot operation When enabled with value non-zero, the timer will count down to zero then self-set enabled to false. When enabled with value zero, the value will be reloaded from the period and the timer will restart.

Mode 0

Manual free-running operation

To start a timer in this mode, ensure:

• oneshot is false, indicating a free running timer mode
• autoreload false, meaning the timer will not automatically reload the value from the period
• enabled is true
• value is loaded with a value greater than zero

In this mode, the timer will count down until the timer expires (the value hits 0), at which point:

• alarm will go true (if it is not already true)
• enabled will stay true
• The timer will pause counting at value zero

Since the timer is still enabled, the timer will immediately restart counting down when a new non-zero count value is loaded by a Sail script.

Hence, a listener on the alarm could simply:

timer.alarm = false; // clear alarm
timer.value = 50; // restart immediately at 5 seconds

to restart the timer at 5 seconds. The period property is not used by the timer in this mode, and is available to the GUI designer to store any Integer value, such as the desired reload value. The setup of the timer could therefore be:

timer.period = 50;
timer.oneshot = false; // free running mode
timer.autoreload = false; // no automatic reload from period
timer.value = timer.period; // start at 5 seconds
timer.enabled = true;       // start now 

Of course, all these values could be configured on the timer node in SHIPTide without any code all. Then the listener could simply be:

timer.alarm = false; // clear alarm
timer.value = timer.period; // restart immediately at whatever the period is set to

The oneshot and autoreload Properties

A "one shot" timer stops when it has completed its count. The opposite of a one shot timer is a "free running" timer which, when it competes its count, automatically restarts counting in a "free running" mode. The timer node supports both types of operation based on the oneshot value.

When a timer expires and the oneshot property is true, the timer.enabled property is set to false, stopping the timer. Hence the term "one shot", since the timer is now halted and must be re-configured and re-started manually from a Sail script.

However when a timer expires and all the following conditions are true:

• oneshot is set to false (expressing a desire to be a free-running timer)
• autoreload is set to true
• the reload period is set to a value greater than zero

then

• enabled is kept unchanged (true)
• value will be automatically reloaded from period
• and the timer will restart counting down.

This is the free-running mode of the timer.

In both one-shot and free-running modes, care must be taken to clear the alarm property in a Sail script before the next alarm or the next alarm event may be missed.

Examples

Animation Timers

Here is a complete example of a timer, including an associated listener and script which increment a variable every 0.3 seconds:

In this example, the timer is set up as a oneshot with a 0.3 second period. Each time the alarm goes true, the listener awakes and runs the script. The script increments a Short variable named animationCounter.

animationCounter can now be the foundation for numerous listeners throughout the GUI. They will wake up every time animationCounter increments (once every 0.3 seconds) and can use the value to determine which animation image needs to be displayed. For example, if a given animation is composed of 3 cycling images, (animationCounter % 3) could be used in a switch statement to select and display the correct image in the cycle.