DynamicScript

Description

DynamicScript represents an instance of an expression, script file, or module being evaluated using a scripting engine.

In other words, this is the type of object created by the plugin when a user invokes one of the scripting type actions this plugin provides.

It has properties representing some of the action parameters which can be set in an action/connector, such as the State/instance Name, expression, file, and so on. Most properties are read-only, but a few can be set at runtime such as the default type/value and held action repeating delay/rate.

A DynamicScript object instance can be retrieved with the DSE object functions such as DSE.currentInstance(), DSE.instance(), or DSE.instanceList(). They cannot be created directly (eg. new DynamicScript() will not work).

Since

v1.2

Properties
string	name
Type, Input and Engine properties.
DSE::ScriptInputType	inputType
string	expression
string	scriptFile
string	scriptFileResolved
string	moduleAlias
DSE::EngineInstanceType	engineType
string	engineName
Persistence properties.
DSE::PersistenceType	persistence
DSE::SavedDefaultType	defaultType
String	defaultValue
int	autoDeleteDelay
Object	dataStore
Touch Portal State properties.
bool	createState
string	stateId
string	stateName
string	stateParentCategory
bool	stateCreated
Action behaviour properties – how the instance reacts to various input types like button press/release/hold.
Note This whole section is actually somewhat of a workaround for how Touch Portal allows "On Hold" button behaviors to be specified. All this configuration should really be on the control/button side, not in the action(s) the control is triggering. Eg. separate action for press vs. release, whether to repeat while held or not, repeat delay/rate, etc.
DSE::ActivationBehaviors	activation
int	repeatRate
int	repeatDelay
int	activeRepeatRate
int	activeRepeatDelay
int	effectiveRepeatRate
int	effectiveRepeatDelay
int	maxRepeatCount
int	repeatCount
bool	isRepeating
bool	isPressed

Public Member Functions
void	stateUpdate (String &value)
void	evaluate ()
void	setPressedState (bool isPressed)
Events
All these events correspond to changes in property values, provided as a way for a script to take some immediate action based on a new value for that property, vs, say, having to check the values periodically with a timer. See Event Handling for details about connecting handlers to events.
void	pressedStateChanged (bool isPressed)
void	repeatingStateChanged (bool isRepeating)
void	repeatCountChanged (int repeatCount)
void	repeatRateChanged (int ms)
void	repeatDelayChanged (int ms)
void	activeRepeatRateChanged (int ms)
void	activeRepeatDelayChanged (int ms)

Property Documentation

name

string name

readwrite

The Instance Name of this script instance as specified in the corresponding Action which created it.
This property is read-only.

inputType

DSE::ScriptInputType inputType

read

The type of scripting action. DSE.ScriptInputType enumeration value, one of: DSE.ExpressionInput, DSE.ScriptInput, DSE.ModuleInput, DSE.UnknownInputType
This property is read-only.

expression

string expression

read

The full expression string. This is as received from Touch Portal, possibly with any TP macros already evaluated.
This property is read-only.

scriptFile

string scriptFile

read

The script/module file, if any. Only DSE.ScriptInput and DSE.ModuleInput inputType instances will have a file, the value will be empty otherwise. This is the actual string value specified in the Action "Script File" property which created this Script instance. The scriptFileResolved property contains the absolute system path to the file being loaded, potentially after resolving and normalizing the given name against the default script path.
This property is read-only.

scriptFileResolved

string scriptFileResolved

read

This property contains the absolute system path to the scriptFile being loaded, potentially after resolving and normalizing the given name against the default script path.
This property is read-only.

moduleAlias

string moduleAlias

read

The module import alias. Only Module type instances will have an alias.
This property is read-only.

engineType

DSE::EngineInstanceType engineType

read

This is the Engine Instance type which this script is using for its execution environment. DSE.EngineInstanceType enumeration value, one of: DSE.SharedInstance or DSE.PrivateInstance
This property is read-only.

engineName

string engineName

read

The name of the engine instance this script instance is using for its execution environment. The engine instance is specified in the Action which created this script instance. For Private type script instances this may nor may not be the same as the name property. For Shared instance types this is always "Shared".
This property is read-only.

persistence

DSE::PersistenceType persistence

readwrite

Persistence essentially determines the lifespan of this script instance. "Session" persistence means it will exist until DSE exits. "Saved" means the instance data will be saved to a settings file when DSE exits, and restored from settings the next time DSE starts. "Temporary" instances will be automatically deleted after a time span specified in autoDeleteDelay.

defaultType

DSE::SavedDefaultType defaultType

readwrite

This property determines how to treat the defaultValue property value. See enumeration documentation links for details on each type.
DSE.SavedDefaultType enumeration value, one of: DSE.FixedValueDefault, DSE.CustomExprDefault, DSE.LastExprDefault

Note

In versions prior to 1.2.1, the default only applied to saved instances and used when they got restored from saved settings. Since v1.2.1, a default type and value can be applied to any instance. The DSE.LastExprDefault type is still only relevant to saved instances, since a brand new instance wouldn't have a "last expression."

See also

defaultValue, persistence

defaultValue

String defaultValue

readwrite

A default value to use when creating a Touch Portal state (when createState is true). Depending on the value of defaultType, this could be an empty string, a fixed default string value, or an expression to be evaluated.

See also

defaultType, persistence

autoDeleteDelay

int autoDeleteDelay

readwrite

For temporary instances, where persistence property is DSE.PersistTemporary, this property determines the delay time before the instance is automatically deleted. The value is in milliseconds. The default delay time is 10 seconds (10,000 ms). If the instance created a Touch Portal State, the State is also removed after this delay time.

See also

persistence

dataStore

Object dataStore

read

Persistent arbitrary data storage object which is attached to this script instance.

This is a generic Object type on which properties can be created or deleted as necessary. The property value(s) can be any serializable (to/from JSON) data type, incuding a objects or arrays. This data is stored with the script instance itself, not in the Engine the script is running in, so for example resetting the Engine instance will not affect this stored data, unlike with local variables. This data is also saved and restored at startup with the rest of the instance properties if its persistence property is DSE.PersistSave.

Note

To persist between Engine resets or Dynamic Script Engine runs (in saved settings), this data is saved and restored by converting it to/from JSON. This means you cannot restore a function-like Object (or class instance). Only plain data types, numbers and strings basically, will survive the JSON round-trip conversion.

For example, this will not work properly:

let color = new Color('blue');
DSE.currentInstance().dataStore.color = color;
// typeof dataStore.color == Color,  BUT only until the data storage needs to be saved/restored...
// ... after JSON round-trip
color = DSE.currentInstance().dataStore.color;
// typeof color == Object;  color == { _a: 1, _b: 0, _format: 'name', _g: 128, .... }

Instead, save some way to restore a new instance of the object type to the same state as the saved one:

DSE.currentInstance().dataStore.color = color.rgba()
// dataStore.color == { r: 0, g: 128, b: 0, a: 1 }
// ... after JSON round-trip, the Color type can accept the serialized 'rgba' object as input.
color = new Color(DSE.currentInstance().dataStore.color);
// color.isValid() == true; color.rgba() == { r: 0, g: 128, b: 0, a: 1 }

\warn Only use this object for data which actually needs to be saved and restored to/from persistent storage. For temporary/run-time variables it is far more efficient to just create and use them "on the stack" in your script (like you normally would) vs. accessing the dataStore object repeatedly.

This property is read-only (meaning the actual storage object cannot be changed; properties of the object itself can be fully manipulated).

createState

bool createState

readwrite

This property value is true when when this script instance was created with "Create State" set to "Yes" by the corresponding action, and false otherwise. Changing this property from false to true will create a new Touch Portal State, and toggling from true to false will remove the State from Touch Portal. State creation happens "laziliy," meaning one will be created before a State update is to be sent (if ever). State removal, on the other hand, is immediate.

See also

stateCreated

stateId

string stateId

read

The State ID of this instance as used with Touch Portal to uniquely identify this State, if any. This value will be empty when createState property is false. If not empty, this is typically in the form of DSE.VALUE_STATE_PREFIX + name.
This property is read-only.

stateName

string stateName

readwrite

The "friendly name" of the created State (if any), as it will appear in Touch Portal selector lists. By default this is the same as the name property.
If this property is set by a script or expression in the initial evaluation (when the Action creating it is first used), then the State will be created with the new name.
Changing this property after the State has already been created will have no effect. Either set it before changing the createState property, or toggle createState to false and then true again to re-create the State under the new parent category.

See also

createState, stateCreated

stateParentCategory

string stateParentCategory

readwrite

This property holds the name of the Touch Portal parent cateogry into which the created State (if any) will be placed. By default the property is not explicitly set, and reading it will return the global default value (DSE.VALUE_STATE_PARENT_CATEOGRY).
If this property is set by a script or expression in the initial evaluation (when the Action creating it is first used), then the State will be created with the new name.
Changing this property after the State has already been created will have no effect. Either set it before changing the createState property, or toggle createState to false and then to true again to re-create the State under the new parent category.

See also

createState, stateCreated

stateCreated

bool stateCreated

read

This read-only property value is true if a Touch Portal State has been created for this script instance, false otherwise. This should always be false if createState is false.
This property is read-only.

See also

createState

activation

DSE::ActivationBehaviors activation

readwrite

The activation property determines how the instance will behave when a control (eg. button) using this instance is activated (eg. pressed, held, or released).
This property is primarily relevant when an action is used in a Touch Portal "On Hold" button setup, and is usually set by the "On Hold" action options.
The value can be any OR combination of DSE.ActivationBehavior enumeration flags.
For example:

• DSE.OnPress - Evaluates expression on initial button press only.
• DSE.OnPress | DSE.RepeatOnHold - Evaluates expression on initial button press and repeatedly while it is held.
• DSE.OnPress | DSE.OnRelease - Evaluates expression on initial button press and again when it is released.
• DSE.RepeatOnHold - Ignores the initial button press and then starts repeating the evaluation after effectiveRepeatDelay ms, until it is released.
• DSE.OnRelease - Evaluates expression only when button is released. This is the default behavior when using an action in Touch Portal's "On Pressed" button setup (which actually triggers actions upon button release).

repeatRate

int repeatRate

readwrite

The default action repeat rate for this particular instance, in milliseconds. If -1 (default) then the global default rate is used.

See also

, activeRepeatRate, DSE.defaultActionRepeatRate, repeatRateChanged()

repeatDelay

int repeatDelay

readwrite

The default action repeat delay for this particular instance, in milliseconds. If -1 (default) then the global default rate is used.

See also

activeRepeatDelay, DSE.defaultActionRepeatDelay, repeatDelayChanged()

activeRepeatRate

int activeRepeatRate

readwrite

Temporary repeat rate for the next time script action gets repeated, in milliseconds. Automatically resets to -1 once script finishes repeating. If -1 (default) then repeatRate or the global default rate is used.

See also

activeRepeatRateChanged()

activeRepeatDelay

int activeRepeatDelay

readwrite

Temporary repeat delay time for the next time script action gets repeated, in milliseconds. Automatically resets to -1 once script finishes repeating. If -1 (default) then repeatDelay or the global default delay is used.

See also

activeRepeatDelayChanged()

effectiveRepeatRate

int effectiveRepeatRate

read

The currently effective action repeat rate which is either the global default rate, or this instance's repeatRate if set, or activeRepeatRate if it was set.
This property is read-only.

effectiveRepeatDelay

int effectiveRepeatDelay

read

The currently effective action repeat delay which is either the global default delay, or this instance's repeatDelay if set, or activeRepeatDelay if it was set.
This property is read-only.

maxRepeatCount

int maxRepeatCount

readwrite

Get or set the maximum number of times this action will repeat when held. A value of -1 (default) means to repeat an unlimited number of times. Setting the value to 0 effectively disables repeating.

repeatCount

int repeatCount

read

The number of times the current, or last, repeating action of this instance has repeated. The property is reset to zero when the isRepeating property changes from false to true – that is, every time the repetition is about to start, but before the initial effectiveRepeatDelay time has passed.

See also

repeatCountChanged(), isRepeating, isPressed
This property is read-only.

isRepeating

bool isRepeating

read

true if this script evaluation is currently repeating, false otherwise. The value changes to true every time the repetition is about to start, but before the initial effectiveRepeatDelay time has passed. For example it is possible to cancel a repetition before it even starts by setting isPressed to false whenever whenever this property changes.

See also

repeatingStateChanged()
This property is read-only.

isPressed

bool isPressed

readwrite

This property value is true if a button using an Action which invokes this script is currently being held down, false otherwise. The value can be changed by setting the property or calling the setPressedState() method, which has further documentation on what this means.

See also

pressedStateChanged()

Member Function Documentation

stateUpdate()

void stateUpdate

(

String &

value

)

Send a Touch Portal State value update using this instance's stateId as the State ID. If createState property is false then calling this method has no effect.
This method will create the Touch Portal State if it has not already been created.

evaluate()

void evaluate

(

)

Callling this method causes the instance to evaluate its current expression, basically as if it was invoked from a Touch Portal Action or Connector.

This includes loading any script file or importing a module as per the current inputType, scriptFile, and moduleAlias property settings.

Note that we cannot retrieve data/values from Touch Portal directly, it has to send them to us via an Action. So if the expression originally gets some data value(s) provided by TP itself (from a Value or State), the last data it sent gets evaluated. There is no way to retrieve a more current value, and in fact the script instance itself isn't even aware that some Value or State was involved in the first place (it only gets the data from the Value/State, not the name or ID).

setPressedState()

void setPressedState

(

bool

isPressed

)

This method provides direct control over the current "pressed state" of this script instance, which can be true or false.

Normally an instance can be "pressed" and "released" when its corresponding Action is used in a Touch Portal button's "On Hold" setup tab. An action used there sends two events to the plugin, one for the "down" event, when the button is first pressed, and another for the "up" event.

Setting the pressed state to false while an action's button is being held and is repeating, for example, will cancel any further repeats, just as if the button had been released by the user. Setting the pressed state to true will not have any immediate effect until the next time the the action's expression is evaluated, either by using its corresponding action in Touch Portal, or by calling the evaluate() method. Once evaluation is performed, the behavior will depend on the current value of the activation property (eg. the action could start repeating, wait for a delay, or be "armed" for a release/up event).

See also

isPressed, pressedStateChanged()

pressedStateChanged()

void pressedStateChanged

(

bool

isPressed

)

This event is only emitted when an action is used in an "On Hold" button setup.

When the button using this action is first pressed down, this event is emitted with the isPressed parameter set to true. When the button is later released, the event is emitted again with the parameter set to false.

The event is emitted regardless of the activation property value, as long as the button is being used in the "On Hold" tab (when an action is used in the "On Pressed" tab setup, it is actually only activated when the button is released, so this event would have no relevance).
This allows custom behavior for a button from within a script handler – for example different actions could be performed on button press vs. release.

This event has a corresponding opressedStateChanged property to which a single event handler may be assigned.

See also

isPressed, setPressedState()

repeatingStateChanged()

void repeatingStateChanged

(

bool

isRepeating

)

This event is emitted when an evaluation starts or stops repeating (as per the activation property). The isRepeating parameter reflects the current (new) value of the isRepeating property.

This event has a corresponding onrepeatingStateChanged property to which a single event handler may be assigned.

repeatCountChanged()

void repeatCountChanged

(

int

repeatCount

)

This event is emitted when the value of the repeatCount property changes, meaning whenever the evaluation is repeated, or when a new "repetition" starts. See repeatCount for more details. The repeatCount parameter value reflects the current (new) repeatCount property value.

This event has a corresponding onrepeatCountChanged property to which a single event handler may be assigned.

repeatRateChanged()

void repeatRateChanged

(

int

ms

)

This event is emitted when the value of the repeatRate property changes. The ms parameter value reflects the current (new) repeatRate property value.

This event has a corresponding onrepeatRateChanged property to which a single event handler may be assigned.

repeatDelayChanged()

void repeatDelayChanged

(

int

ms

)

This event is emitted when the value of the repeatDelay property changes. The ms parameter value reflects the current (new) repeatDelay property value.

This event has a corresponding onrepeatDelayChanged property to which a single event handler may be assigned.

activeRepeatRateChanged()

void activeRepeatRateChanged

(

int

ms

)

This event is emitted when the value of the activeRepeatRate property changes. The ms parameter value reflects the current (new) activeRepeatRate property value.

This event has a corresponding onactiveRepeatRateChanged property to which a single event handler may be assigned.

activeRepeatDelayChanged()

void activeRepeatDelayChanged

(

int

ms

)

This event is emitted when the value of the activeRepeatDelay property changes. The ms parameter value reflects the current (new) activeRepeatDelay property value.

This event has a corresponding onactiveRepeatDelayChanged property to which a single event handler may be assigned.