Difference between revisions of "SHIP:Node:timer"

From Serious Documentation
Jump to: navigation, search
(→‎One Shot, Auto Reload)
(→‎One Shot, No Auto Reload)
Line 77: Line 77:
  
 
[[File:SHIPTide-timerExample2.png|800px|border|center|Example {{Node|timer}} {{Prop|timer|alarm}} {{Node|listener}}]]
 
[[File:SHIPTide-timerExample2.png|800px|border|center|Example {{Node|timer}} {{Prop|timer|alarm}} {{Node|listener}}]]
−
 
−
==== One Shot, No Auto Reload ====
 
−
This mode is set when {{Prop|timer|oneshot}} is {{Reserved|true}} and {{Prop|timer|autoreload}} is {{Reserved|false}}.
 
−
 
−
When the {{Prop|timer|alarm}} goes {{Reserved|true}} (on a <code>1</code> to <code>0</code> transition on {{Prop|timer|value}}), the {{Node|timer}}:
 
−
*  sets {{Prop|timer|enabled}} {{Reserved|false}}
 
−
* sets {{Prop|timer|alarm}} {{Reserved|true}}
 
−
 
−
The timer then stops (i.e. a "one shot"), and must be restarted in a [[SHIP:Sail|Sail script]], generally from a {{Node|listener}} {{Prop|listener|listeningto}} the {{Prop|timer|alarm}} to go {{Reserved|true}}.
 
−
 
−
If the {{Prop|timer|enabled}} is subsequently set in a [[SHIP:Sail|Sail script]] {{Reserved|true}}, the act of re-enabling the {{Node|timer}} with value <code>0</code> causes an auto reload of the {{Prop|timer|value}} from {{Prop|timer|period}} and the {{Node|timer}} commences the count-down cycle again.
 
−
 
−
 
−
 
−
 
−
 
−
* reloads {{Prop|timer|value}} from {{Prop|
 
−
 
−
f {{Reserved|true}}, leaves {{Prop|timer|enabled}} {{Reserved|true}}, reloads {{Prop|timer|value}} from {{Prop|timer|period}} and restarts counting down
 
−
 
−
property and:
 
−
* if {{Reserved|true}}, leaves {{Prop|timer|enabled}} {{Reserved|true}}, reloads {{Prop|timer|value}} from {{Prop|timer|period}} and restarts counting down
 
−
* if {{Reserved|false}}, sets {{Prop|timer|enabled}} {{Reserved|false}}, reloads {{Prop|timer|value}} from {{Prop|timer|period}} and restarts counting down
 
−
In the vast majority of use cases, a {{Node|listener}} is attached to the {{Prop|timer|alarm}}, and in the associated {{Node|script}} the alarm is reset.
 
−
 
−
 
−
 
−
 
−
 
−
When {{Prop|timer|enabled}} is set to {{Reserved|true}} and the {{Prop|timer|value}} is non-zero, the {{Node|timer}} begins to count down, with the {{Prop|timer|value}} property decrementing ever 0.1Hz.  When the {{Prop|timer|
 
−
*
 
−
 
−
in that it counts down from the programmed {{Prop|timer|value}} until it hits <code>0</code> which then sets the {{Prop|timer|alarm}}.  If auto
 
−
A GUI is generally composed of numerous graphically designed layout screens.  Touch buttons navigate within an interactive GUI page and also cause screens to change from one to another.  Since the word "screen" can easily be confused with the physical glass screen (vs. the GUI pixel content on the screen), [[SHIP]] uses the term "page" instead.  The {{Node|page}} in the GUI contains the visual layout for a specific GUI page.  You can, and probably will, have many {{Node|page|pages}} in a given GUI.
 
  
 
== Examples ==
 
== Examples ==

Revision as of 08:36, 29 November 2012

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:

Child Nodes

The following nodes are permitted to exist within this node:

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.

Operation

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.

The oneshot and autoreload Properties

A "one shot" timer is a timer that 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:

then

  • the enabled property is kept unchanged (true)
  • the value will be automatically reloaded from period
  • 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.

listeners and timers

Normally, a listener will be set to listen to a timer's alarm property. For example, the following shows a typical listener-script pair acting on an alarm when the timer expires:


Example timer alarm listener

Examples

Retrieved from "https://techref.myserious.com/index.php?title=SHIP:Node:timer&oldid=1067"