Difference between revisions of "SHIP:Node:timer"

From Serious Documentation
Jump to: navigation, search
(→‎Mode 1)
 
(30 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
[[SHIP:Node|Node Home]]
 
[[SHIP:Node|Node Home]]
 
__TOC__
 
__TOC__
−
Animations and delayed events or pauses require periodic or one-shot timers. The {{Node|timer}} node fills this need in {{SHIP}}.
+
{| class="wikitable" style="margin: 1em auto 1em auto;"
 +
! scope="col" | Node Type
 +
! scope="col" | Description
 +
|-
 +
|<onlyinclude>{{Node|timer}}{{#if: {{{1|}}}|{{{1}}} }}||Generates delays and timed alarm events.</onlyinclude>
 +
|}
 +
Animations and delayed events or pauses require periodic or one-shot timers. The {{Node|timer}} node fills this need in [[SHIP]].
  
 
The {{Node|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.  
 
The {{Node|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 ==
+
== Ancestors ==
−
The following nodes are permitted to hold this node:
+
 
−
* {{Node|box}}
+
{{Node|timer}} nodes are only permitted in the {{Node|layout}} area. The following {{Node|layout}} area nodes are permitted to have {{Node|timer}}s as descendants:
−
* {{Node|display}}
+
{| class="wikitable" style="margin: 1em auto 1em auto;"
−
* {{Node|group}}
+
! scope="col" | Node Type
−
* {{Node|text}}
+
! scope="col" | Description
−
* {{Node|page}}
+
|-
−
* {{Node|variable}}
+
|{{:SHIP:Node:box|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:display|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:group|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:layout}}
 +
|-
 +
|{{:SHIP:Node:page|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:text|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:timer|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:variable|{{†}}}}
 +
|}
 +
{{†}}{{Node|timer}} nodes are permitted ''directly'' underneath these nodes.
  
−
== Child Nodes ==
+
== Descendants ==
−
The following nodes are permitted to exist within this node:
+
The following nodes are permitted within {{Node|timer}}s:
−
* {{Node|constant}}
 
−
* {{Node|listener}}
 
−
* {{Node|variable}}
 
  
−
== Properties ==
 
 
{| class="wikitable" style="margin: 1em auto 1em auto;"  
 
{| class="wikitable" style="margin: 1em auto 1em auto;"  
−
! scope="col" | Property
+
! scope="col" | Node Type
−
! scope="col" | Data Type
 
 
! scope="col" | Description
 
! scope="col" | Description
 
|-
 
|-
−
|{{:SHIP:Property:timer:name}}
+
|{{:SHIP:Node:constant|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:group|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:listener|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:script}}
 +
|-
 +
|{{:SHIP:Node:timer|{{†}}}}
 +
|-
 +
|{{:SHIP:Node:variable|{{†}}}}
 +
|}
 +
{{†}}only these nodes are permitted ''directly'' underneath the {{Node|timer}} node.
 +
 
 +
== Properties ==
 +
{{PropTableStart|}}
 +
|-
 +
|{{:SHIP:Property:all:name}}
 
|-
 
|-
 
|{{:SHIP:Property:timer:enabled}}
 
|{{:SHIP:Property:timer:enabled}}
Line 48: Line 82:
 
The {{Node|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 {{Node|timer}}'s {{Prop|timer|value}} property represents the current remaining time on the given {{Node|timer}}, in tenths of a seconds.  For example, if the {{Node|timer}}.{{Prop|timer|value}} is 34, there are 3.4 seconds left on the timer before it hits <code>0</code>.
 
The {{Node|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 {{Node|timer}}'s {{Prop|timer|value}} property represents the current remaining time on the given {{Node|timer}}, in tenths of a seconds.  For example, if the {{Node|timer}}.{{Prop|timer|value}} is 34, there are 3.4 seconds left on the timer before it hits <code>0</code>.
  
−
When {{Prop|timer|enabled}} is set to {{Reserved|true}} and the {{Node|timer}}.{{Prop|timer|value}} property is non-zero, the {{Node|timer}} begins to count down, with the {{Prop|timer|value}} property decrementing ever 0.1Hz. On a count {{Prop|timer|value}} transition from <code>1</code> to <code>0</code> (the {{Node|timer}} '''expires'''), the {{Prop|timer|alarm}} property is set to {{Reserved|true}}. The {{Prop|timer|alarm}} must be manually reset (set to {{Reserved|false}}) by a [[SHIP:Sail|Sail script]].
+
When {{Prop|timer|enabled}} is set to {{Reserved|true}} and the {{Node|timer}}.{{Prop|timer|value}} property is non-zero, the {{Node|timer}} begins to count down, with the {{Prop|timer|value}} property decrementing every 0.1 seconds. On a count {{Prop|timer|value}} transition from <code>1</code> to <code>0</code> (the {{Node|timer}} '''expires'''), the {{Prop|timer|alarm}} property is set to {{Reserved|true}}. The {{Prop|timer|alarm}} must be manually reset (set to {{Reserved|false}}) by a [[SHIP:Sail|Sail script]].
  
−
In the majority of designs, a {{Node|listener}} is attached to the {{Prop|timer|alarm}}.  When the {{Prop|timer|alarm}} goes {{Reference|true}} the associated {{Node|script}} action is taken, often including restarting the {{Node|timer}}.
+
In the majority of designs, a {{Node|listener}} is attached to the {{Prop|timer|alarm}}.  When the {{Prop|timer|alarm}} goes {{Reserved|true}} the associated {{Node|script}} action is taken, often including restarting the {{Node|timer}}.
  
 
== Timer Modes of Operation ==
 
== Timer Modes of Operation ==
  
−
The three {{Node|timer}} properties {{Prop|timer|oneshot}}, {{Prop|timer|autoreload}} and {{Prop|timer|period}}, all determine the operational mode of a timer.  These modes are:
+
The two {{Node|timer}} properties {{Prop|timer|oneshot}} and {{Prop|timer|autoreload}} determine the operational mode of a timer.  These modes are:
  
 
{| class="wikitable" style="margin: 1em auto 1em auto;"  
 
{| class="wikitable" style="margin: 1em auto 1em auto;"  
Line 60: Line 94:
 
! scope="col" | {{Prop|timer|oneshot}}
 
! scope="col" | {{Prop|timer|oneshot}}
 
! scope="col" | {{Prop|timer|autoreload}}
 
! scope="col" | {{Prop|timer|autoreload}}
−
! scope="col" | {{Prop|timer|period}}
 
 
! scope="col" | Operation
 
! scope="col" | Operation
 
|-
 
|-
−
|1||{{Reserved|false}}||{{Reserved|false}}||any||Manual free-running operation.  When {{Prop|timer|enabled}}, the {{Node|timer}} will count down to zero then pause until a new non-zero count {{Prop|timer|value}} is loaded by a [[SHIP:Sail|Sail script]]. Setting the {{Prop|timer|period}} has no effect.
+
|[[SHIP:Node:timer#Mode 0|Mode 0]]||{{Reserved|false}}||{{Reserved|false}}||'''Manual free-running operation'''
 +
 
 +
When {{Prop|timer|enabled}}, the {{Node|timer}} will count down to zero then pause until a new non-zero count {{Prop|timer|value}} is loaded by a [[SHIP:Sail|Sail script]].
 +
 
 +
Setting the {{Prop|timer|period}} has no effect.
 
|-
 
|-
−
|1||{{Reserved|false}}||{{Reserved|true}}||<code>0</code>||Not used.  A zero value will not be loaded into the {{Prop|timer|value}}. The {{Node|timer}} will "stick" at zero until the {{Prop|timer|value}} or the {{Prop|timer|period}} is set to a non-zero value.
+
|[[SHIP:Node:timer#Mode 1|Mode 1]]||{{Reserved|false}}||{{Reserved|true}}||'''Automatic free-running operation'''
 +
 
 +
When {{Prop|timer|enabled}}, the {{Node|timer}} will count down to zero then re-load the {{Prop|timer|value}} from the {{Prop|timer|period}} and restart the count down process.
 +
 
 +
A {{Prop|timer|period}} value of zero will cause the {{Node|timer}} to pause (still {{Prop|timer|enabled}}) until a non-zero value is loaded into the {{Prop|timer|value}} or {{Prop|timer|period}}.
 
|-
 
|-
−
|1||{{Reserved|false}}||{{Reserved|true}}||<code>&gt;0</code>||The {{Prop|timer|period}} will be reloaded into the {{Prop|timer|value}} and the countdown process will start.
+
|[[SHIP:Node:timer#Mode 2|Mode 2]]||{{Reserved|true}}||{{Reserved|false}}||'''Manual one-shot operation'''
 +
 
 +
When {{Prop|timer|enabled}} with {{Prop|timer|value}} non-zero, the {{Node|timer}} will count down to zero then self-set {{Prop|timer|enabled}} to {{Reserved|false}}.
 +
 
 +
The {{Node|timer}} will restart when a non-zero {{Prop|timer|value}} is loaded '''and''' the {{Node|timer}} is re-{{Prop|timer|enabled}} by a [[SHIP:Sail|Sail script]].
 +
 
 +
Setting the {{Prop|timer|period}} has no effect.
 
|-
 
|-
−
|1||{{Reserved|true}}||{{Reserved|false}}||<code>0</code>||Not used.
+
|[[SHIP:Node:timer#Mode 3|Mode 3]]||{{Reserved|true}}||{{Reserved|true}}||'''Automatic one-shot operation'''
−
|-
+
 
−
|1||{{Reserved|true}}||{{Reserved|false}}||<code>&gt;0</code>||Not used.
+
When {{Prop|timer|enabled}} with {{Prop|timer|value}} non-zero, the {{Node|timer}} will count down to zero then self-set {{Prop|timer|enabled}} to {{Reserved|false}}.
−
|-
+
 
−
|1||{{Reserved|true}}||{{Reserved|true}}||<code>0</code>||Not used.  A zero value will not be loaded into the {{Prop|timer|value}}. The {{Node|timer}} will "stick" at zero until the {{Prop|timer|value}} or the {{Prop|timer|period}} is set to a non-zero value.
+
When re-{{Prop|timer|enabled}} with {{Prop|timer|value}} zero, the {{Prop|timer|value}} will be reloaded from the {{Prop|timer|period}} and the {{Node|timer}} will restart.
−
|-
 
−
|1||{{Reserved|true}}||{{Reserved|true}}||<code>&gt;0</code>||The {{Prop|timer|period}} will be reloaded into the {{Prop|timer|value}} when the {{Node|timer}} is re-{{Prop|timer|enabled}} by a [[SHIP:Sail|Sail script]] and the countdown process will start.
 
 
|}
 
|}
  
−
=== Mode 1 ===
+
=== Mode 0 ===
 +
'''Manual free-running operation'''
  
−
To set this mode, ensure:
+
To start a {{Node|timer}} in this mode, ensure:
 
* {{Prop|timer|oneshot}} is {{Reserved|false}}, indicating a free running {{Node|timer}} mode
 
* {{Prop|timer|oneshot}} is {{Reserved|false}}, indicating a free running {{Node|timer}} mode
 
* {{Prop|timer|autoreload}} {{Reserved|false}}, meaning the {{Node|timer}} will not automatically reload the {{Prop|timer|value}} from the {{Prop|timer|period}}
 
* {{Prop|timer|autoreload}} {{Reserved|false}}, meaning the {{Node|timer}} will not automatically reload the {{Prop|timer|value}} from the {{Prop|timer|period}}
 +
* {{Prop|timer|enabled}} is {{Reserved|true}}
 +
* {{Prop|timer|value}} is loaded with a value greater than zero
  
−
In this mode, the {{Node|timer}} will count down until the {{Node|timer}} expires, at which point:
+
In this mode, the {{Node|timer}} will count down until the {{Node|timer}} expires (the {{Prop|timer|value}} hits <code>0</code>), at which point:
 
* {{Prop|timer|alarm}} will go {{Reserved|true}} (if it is not already {{Reserved|true}})
 
* {{Prop|timer|alarm}} will go {{Reserved|true}} (if it is not already {{Reserved|true}})
 
* {{Prop|timer|enabled}} will stay {{Reserved|true}}
 
* {{Prop|timer|enabled}} will stay {{Reserved|true}}
Line 91: Line 139:
 
Since the {{Node|timer}} is still {{Prop|timer|enabled}}, the timer will immediately restart counting down when a new non-zero count {{Prop|timer|value}} is loaded by a [[SHIP:Sail|Sail script]].  
 
Since the {{Node|timer}} is still {{Prop|timer|enabled}}, the timer will immediately restart counting down when a new non-zero count {{Prop|timer|value}} is loaded by a [[SHIP:Sail|Sail script]].  
  
−
Hence, a {{Node|listener}} on the {{Prop|timer|alarm}} could simply:
+
Hence, a {{Node|listener}}-{{Node|script}} on the {{Prop|timer|alarm}} could simply:
 
  <code>timer.alarm = false; // clear alarm
 
  <code>timer.alarm = false; // clear alarm
 
  timer.value = 50; // restart immediately at 5 seconds</code>
 
  timer.value = 50; // restart immediately at 5 seconds</code>
  
−
to restart the timer at 5 seconds.
+
to restart the timer at 5 seconds. The {{Prop|timer|period}} property is not used by the {{Node|timer}} in this mode, and is available to the GUI designer to store any {{DataType|Integer}} value, such as the desired reload value.  The setup of the {{Node|timer}} could therefore be:
 +
<code>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 </code>
 +
Of course, all these values could be configured on the {{Node|timer}} node in [[SHIPTide]] without any code all.  Then the {{Node|listener}}-{{Node|script}} could simply be:
 +
<code>timer.alarm = false; // clear alarm
 +
timer.value = timer.period; // restart immediately at whatever the period is set to</code>
 +
 
 +
Care must be taken to clear the {{Prop|timer|alarm}} property in a [[SHIP:Sail|Sail script]] before the next alarm or the next alarm event may be missed.
 +
 
 +
=== Mode 1 ===
 +
'''Automatic free-running operation'''
 +
 
 +
To start a {{Node|timer}} in this mode, ensure:
 +
* {{Prop|timer|oneshot}} is {{Reserved|false}}, indicating a free running {{Node|timer}} mode
 +
* {{Prop|timer|autoreload}} {{Reserved|true}}, meaning the {{Node|timer}} ''will'' automatically reload the {{Prop|timer|value}} from the {{Prop|timer|period}}
 +
* {{Prop|timer|enabled}} is {{Reserved|true}}
  
 +
If the {{Prop|timer|value}} is zero when the {{Node|timer}} is {{Prop|timer|enabled}}, the {{Node|timer}} will load the {{Prop|timer|value}} from the {{Prop|timer|period}}.
  
 +
In this mode, the {{Node|timer}} will count down until the {{Node|timer}} expires (the {{Prop|timer|value}} hits <code>0</code>), at which point:
 +
* {{Prop|timer|alarm}} will go {{Reserved|true}} (if it is not already {{Reserved|true}})
 +
* {{Prop|timer|enabled}} will stay {{Reserved|true}}
 +
* The {{Node|timer}} will reload its {{Prop|timer|value}} from its {{Prop|timer|period}} and restart counting immediately
  
 +
If the {{Prop|timer|period}} is zero when a reload is attempted, the {{Node|timer}} will remain {{Prop|timer|enabled}} but paused until either:
 +
* {{Prop|timer|value}} is loaded with a non-zero value, or,
 +
* {{Prop|timer|period}} is loaded with a non-zero value (which will be auto-loaded into {{Prop|timer|value}} immediately)).
  
−
==== The {{Prop|timer|oneshot}} and {{Prop|timer|autoreload}} Properties ====
+
The setup of the {{Node|timer}} could therefore be:
 +
<code>timer.period = 50;
 +
timer.oneshot = false; // free running mode
 +
timer.autoreload = true; // automatic reload from period
 +
timer.value = 0; // timer will automatically load from period when 0
 +
timer.enabled = true;      // start now </code>
 +
These values can be configured on the {{Node|timer}} node in [[SHIPTide]] without any code all.
  
−
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 {{Node|timer}} node supports both types of operation based on the {{Prop|timer|oneshot}} value.
+
Care must be taken to clear the {{Prop|timer|alarm}} property in a [[SHIP:Sail|Sail script]] before the next alarm or the next alarm event may be missed.  For example, the {{Node|listener}}-{{Node|script}} on the {{Prop|timer|alarm}} could simply be:
 +
<code>timer.alarm = false; // clear alarm
 +
// do some action; timer is still running and was auto reloaded.</code>
  
−
When a {{Node|timer}} expires and the {{Prop|timer|oneshot}} property is {{Reserved|true}}, the {{Node|timer}}.{{Prop|timer|enabled}} property is set to {{Reserved|false}}, stopping the {{Node|timer}}.  Hence the term "one shot", since the timer is now halted and must be re-configured and re-started manually from a [[SHIP:Sail|Sail script]].
+
=== Mode 2 ===
 +
'''Manual one-shot operation'''
  
−
However when a {{Node|timer}} expires and ''all'' the following conditions are true:
+
To start a {{Node|timer}} in this mode, ensure:
−
*{{Prop|timer|oneshot}} is set to {{Reserved|false}} (expressing a desire to be a free-running timer)
+
* {{Prop|timer|oneshot}} is {{Reserved|true}}, indicating one-shot {{Node|timer}} mode
−
*{{Prop|timer|autoreload}} is set to {{Reserved|true}}
+
* {{Prop|timer|autoreload}} {{Reserved|false}}, meaning the {{Node|timer}} ''will not'' automatically reload the {{Prop|timer|value}} from the {{Prop|timer|period}}
−
*the reload {{Prop|timer|period}} is set to a value greater than zero
+
* {{Prop|timer|enabled}} is {{Reserved|true}}
−
then
 
−
*{{Prop|timer|enabled}} is kept unchanged ({{Reserved|true}})
 
−
*{{Prop|timer|value}} will be automatically reloaded from {{Prop|timer|period}}
 
−
*and the {{Node|timer}} will restart counting down.
 
  
−
This is the free-running mode of the {{Node|timer}}.
+
If the {{Prop|timer|value}} is zero when the {{Node|timer}} is {{Prop|timer|enabled}}, the {{Node|timer}} will not start and the {{Prop|timer|enabled}} property will not go {{Reserved|true}}.
  
−
In both one-shot and free-running modes, care must be taken to clear the {{Prop|timer|alarm}} property in a [[SHIP:Sail|Sail script]] before the next alarm or the next alarm event may be missed.
+
In this mode, the {{Node|timer}} will count down until the {{Node|timer}} expires (the {{Prop|timer|value}} hits <code>0</code>), at which point:
 +
* {{Prop|timer|alarm}} will go {{Reserved|true}} (if it is not already {{Reserved|true}})
 +
* {{Prop|timer|enabled}} will self-set to {{Reserved|false}} and the {{Node|timer}} will stop.
 +
 
 +
To re-start the{{Node|timer}}, the {{Prop|timer|value}} must be reloaded with a non-zero value and the {{Prop|timer|enabled}} must be re-set to {{Reserved|true}}.
 +
 
 +
Setting the {{Prop|timer|period}} has no effect in this mode, and this property can be used as a placeholder for the value a script may wish to use as a reload value.
 +
 
 +
The setup of the {{Node|timer}} could therefore be:
 +
<code>timer.period = 50;
 +
timer.oneshot = true; // one shot mode
 +
timer.autoreload = false; // do not automatic reload from period
 +
timer.value = timer.period; // must set up value manually
 +
timer.enabled = true;      // start now </code>
 +
These values can be configured on the {{Node|timer}} node in [[SHIPTide]] and do not need to be initialized in a [[SHIP:Sail|Sail script]].
 +
 
 +
Care must be taken to clear the {{Prop|timer|alarm}} property in a [[SHIP:Sail|Sail script]] before the next alarm or the next alarm event may be missed.  For example, the {{Node|listener}}-{{Node|script}} on the {{Prop|timer|alarm}} could simply be:
 +
<code>timer.alarm = false; // clear alarm
 +
timer.value = timer.period; // manually reload period
 +
// do some action; timer is halted
 +
timer.enabled = true; // restart timer</code>
 +
 
 +
=== Mode 3 ===
 +
'''Automatic one-shot operation'''
 +
 
 +
To start a {{Node|timer}} in this mode, ensure:
 +
* {{Prop|timer|oneshot}} is {{Reserved|true}}, indicating one-shot {{Node|timer}} mode
 +
* {{Prop|timer|autoreload}} {{Reserved|true}}, meaning the {{Node|timer}} ''will'' automatically reload the {{Prop|timer|value}} from the {{Prop|timer|period}}
 +
* {{Prop|timer|enabled}} is {{Reserved|true}}
 +
 
 +
If the {{Prop|timer|value}} is zero when the {{Node|timer}} is {{Prop|timer|enabled}}, the {{Node|timer}} will re-load the {{Prop|timer|value}} from the {{Prop|timer|period}} which, if non-zero, will restart the {{Node|timer}} count down.  If the {{Prop|timer|period}} is zero, {{Prop|timer|enabled}} will not go {{Reserved|true}} as requested.
 +
 
 +
In this mode, the {{Node|timer}} will count down until the {{Node|timer}} expires (the {{Prop|timer|value}} hits <code>0</code>), at which point:
 +
* {{Prop|timer|alarm}} will go {{Reserved|true}} (if it is not already {{Reserved|true}})
 +
* {{Prop|timer|enabled}} will self-set to {{Reserved|false}} and the {{Node|timer}} will stop.
 +
 
 +
To re-start the{{Node|timer}}, simply re-set {{Prop|timer|enabled}} to {{Reserved|true}}.  As described above,  the {{Node|timer}} will re-load the {{Prop|timer|value}} from the {{Prop|timer|period}} which, if non-zero, will restart the {{Node|timer}} count down.
 +
 
 +
The setup of the {{Node|timer}} could therefore be:
 +
<code>timer.period = 50;
 +
timer.oneshot = true; // one shot mode
 +
timer.autoreload = true; //  automatic reload from period
 +
timer.value = 0; // will reload from period
 +
timer.enabled = true;      // start now </code>
 +
These values can be configured on the {{Node|timer}} node in [[SHIPTide]] and do not need to be initialized in a [[SHIP:Sail|Sail script]].
 +
 
 +
Care must be taken to clear the {{Prop|timer|alarm}} property in a [[SHIP:Sail|Sail script]] before the next alarm or the next alarm event may be missed. For example, the {{Node|listener}}-{{Node|script}} on the {{Prop|timer|alarm}} could simply be:
 +
<code>timer.alarm = false; // clear alarm
 +
// do some action; timer is halted
 +
timer.enabled = true; // restart timer, will auto-reload from period</code>
  
 
== Examples ==
 
== Examples ==
Line 129: Line 257:
 
In this example, the timer is set up as a oneshot with a 0.3 second {{Prop|timer|period}}.  Each time the {{Prop|timer|alarm}} goes {{Reserved|true}}, the {{Node|listener}} awakes and runs the {{Node|script}}.  The {{Node|script}} increments a {{DataType|Short}} {{Node|variable}} named '''animationCounter'''.
 
In this example, the timer is set up as a oneshot with a 0.3 second {{Prop|timer|period}}.  Each time the {{Prop|timer|alarm}} goes {{Reserved|true}}, the {{Node|listener}} awakes and runs the {{Node|script}}.  The {{Node|script}} increments a {{DataType|Short}} {{Node|variable}} named '''animationCounter'''.
  
−
'''animationCounter''' can now be the foundation for numerous {{Node|listener}}s throughout the GUI.  They will wake up every time '''animationCounter''' increments (once every 0.3 seconds) and can use the {{Prop|variable|value}} to determine which animation image needs to be displayed.  For example, if a given animation is composed of 3 cycling images, <code>(animationCounter % 3)</code> could be used in a <code>switch</code> statement to select and display the correct image in the cycle.
+
'''animationCounter''' can now be the foundation for numerous {{Node|listener}}s throughout the GUI.  They will wake up every time '''animationCounter''' increments (once every 0.3 seconds) and can use the <!--- Remove link until page exist {{Prop|variable|value}}--->'''value''' to determine which animation image needs to be displayed.  For example, if a given animation is composed of 3 cycling images, <code>(animationCounter % 3)</code> could be used in a <code>switch</code> statement to select and display the correct image in the cycle.

Latest revision as of 10:29, 27 October 2016

Node Home

Node Type Description
timer Generates delays and timed alarm events.

Animations and delayed events or pauses require periodic or one-shot timers. The timer node fills this need in 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.

Ancestors

timer nodes are only permitted in the layout area. The following layout area nodes are permitted to have timers as descendants:

Node Type Description
box† A generic rectangular container, available as a reusable resource or layout element.
display† Contains the visual GUI layout for a specific LCD display/touch set.
group† Lightweight node that encloses other nodes for pure organizational benefit, or to create an array of nodes.
layout Top of the Layout Area within a SHIP GUI, which completely describes how the GUI is visually organized.
page† Visual layout area for a specific GUI "page", or "screen"
text† Defines a text resource or a visual text representation.
timer† Generates delays and timed alarm events.
variable† Run-time value accessible by scripts and able to generate events on change.

†timer nodes are permitted directly underneath these nodes.

Descendants

The following nodes are permitted within timers:

Node Type Description
constant† Defines a constant value for use in SHIPTide properties or SAIL scripts.
group† Lightweight node that encloses other nodes for pure organizational benefit, or to create an array of nodes.
listener† Monitors one or more properties (including variable values!) for changes, and on changes invokes a script.
script Run-time algorithms, written in SHIPSail.
timer† Generates delays and timed alarm events.
variable† Run-time value accessible by scripts and able to generate events on change.

†only these nodes are permitted directly underneath the timer node.

Properties

Property Data Type Description
name** String The name used to identify this node in SHIPTide.
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 every 0.1 seconds. 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 true 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
Mode 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.

Mode 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.

Mode 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.

Mode 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 re-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:

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

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-script 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-script could simply be: 

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

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.

Mode 1

Automatic free-running operation

To start a timer in this mode, ensure:

If the value is zero when the timer is enabled, the timer will load the value from the period.

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

If the period is zero when a reload is attempted, the timer will remain enabled but paused until either:

  • value is loaded with a non-zero value, or,
  • period is loaded with a non-zero value (which will be auto-loaded into value immediately)).

The setup of the timer could therefore be: 

timer.period = 50;
timer.oneshot = false; // free running mode
timer.autoreload = true; // automatic reload from period
timer.value = 0; // timer will automatically load from period when 0
timer.enabled = true;       // start now

These values can be configured on the timer node in SHIPTide without any code all.

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. For example, the listener-script on the alarm could simply be: 

timer.alarm = false; // clear alarm
// do some action; timer is still running and was auto reloaded.

Mode 2

Manual one-shot operation

To start a timer in this mode, ensure:

If the value is zero when the timer is enabled, the timer will not start and the enabled property will not go true.

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

To re-start thetimer, the value must be reloaded with a non-zero value and the enabled must be re-set to true.

Setting the period has no effect in this mode, and this property can be used as a placeholder for the value a script may wish to use as a reload value.

The setup of the timer could therefore be: 

timer.period = 50;
timer.oneshot = true; // one shot mode
timer.autoreload = false; // do not automatic reload from period
timer.value = timer.period; // must set up value manually
timer.enabled = true;       // start now

These values can be configured on the timer node in SHIPTide and do not need to be initialized in a Sail script.

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. For example, the listener-script on the alarm could simply be: 

timer.alarm = false; // clear alarm
timer.value = timer.period; // manually reload period

// do some action; timer is halted 

timer.enabled = true; // restart timer

Mode 3

Automatic one-shot operation

To start a timer in this mode, ensure:

If the value is zero when the timer is enabled, the timer will re-load the value from the period which, if non-zero, will restart the timer count down. If the period is zero, enabled will not go true as requested.

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

To re-start thetimer, simply re-set enabled to true. As described above, the timer will re-load the value from the period which, if non-zero, will restart the timer count down.

The setup of the timer could therefore be: 

timer.period = 50;
timer.oneshot = true; // one shot mode
timer.autoreload = true; //  automatic reload from period
timer.value = 0; // will reload from period
timer.enabled = true;       // start now

These values can be configured on the timer node in SHIPTide and do not need to be initialized in a Sail script.

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. For example, the listener-script on the alarm could simply be: 

timer.alarm = false; // clear alarm
// do some action; timer is halted
timer.enabled = true; // restart timer, will auto-reload from period

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:

Example timer example with variable, listener and script

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.

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