DSE

Description

The DSE object contains constants and functions related to the plugin environment. It can be used to get or set properties of any existing script instance.

Public Types
enum	EngineInstanceType : uint
enum	ScriptInputType : uint
enum	PersistenceType : uint
enum	SavedDefaultType : uint
enum	ActivationBehavior : uint
enum	ActivationBehaviors : ActivationBehavior
enum	RepeatProperty : uint

Properties
uint	PLUGIN_VERSION_NUM
String	PLUGIN_VERSION_STR
String	SCRIPTS_BASE_DIR
String	VALUE_STATE_PREFIX
String	VALUE_STATE_PARENT_CATEOGRY
String	PLATFORM_OS
String	TP_USER_DATA_PATH
uint	TP_VERSION_CODE
String	TP_VERSION_STR
int	defaultActionRepeatRate
int	defaultActionRepeatDelay
DSE::EngineInstanceType	engineInstanceType
String	engineInstanceName
String	currentInstanceName
DSE::EngineInstanceType	currentInstanceType
String	INSTANCE_TYPE
String	INSTANCE_NAME
String	INSTANCE_DEFAULT_VALUE

Public Member Functions
Array< DynamicScript >	instanceList ()
DynamicScript	instance (String name)
DynamicScript	currentInstance ()
String	instanceStateId ()
void	setActionRepeat (DSE.RepeatProperty property, int ms, String forInstance="")
void	adjustActionRepeat (DSE.RepeatProperty property, int byMs, String forInstance="")

Member Enumeration Documentation

EngineInstanceType

enum EngineInstanceType : uint

Type of script engine instances.

See also

DynamicScript.engineType

Enumerator
UnknownInstanceType	Unknown engine instance type.
SharedInstance	Shared engine instance type.
PrivateInstance	Private engine instance type.

ScriptInputType

enum ScriptInputType : uint

Input types for script actions.

See also

DynamicScript.inputType

Enumerator
UnknownInputType	Unknown script input type.
ExpressionInput	Expression input type.
ScriptInput	Script file input type.
ModuleInput	Module file script input type.

PersistenceType

enum PersistenceType : uint

Script instance persistence types.

See also

DynamicScript.persistence

Enumerator
PersistSession	Instance exists for the duration of current runtime sessions only.
PersistTemporary	Instance is deleted soon after evaluation.
PersistSave	Instance is saved to persistent settings at exit and restored at startup.

SavedDefaultType

enum SavedDefaultType : uint

Script instance saved default value type. These values determine what happens when a script instance is restored from persistent storage.

See also

DynamicScript.defaultType

Enumerator
NoSavedDefault	The instance is not saved in persistent settings, default value type is not applicatble.
FixedValueDefault	Instance is created with a fixed default or empty value (specified in DynamicScript.defaultValue)
CustomExprDefault	Instance is created with default value coming from evaluating a custom expression (specified in DynamicScript.defaultValue)
LastExprDefault	Instance is created with default value coming from evaluating the last saved primary expression (exactly as last sent from the corresponding Touch Portal action/connector).

ActivationBehavior

enum ActivationBehavior : uint

Defines how an action should behave when it is being "activated" as in the case of a button. A button technically how two transition states – when pressed and when released. The time between those events can also either be ignored, reacting only to the transition(s), or used to do something, like repeat some command over and over. An action may also invoke different functions on initial press vs. on release.

See also

DynamicScript.activation

Enumerator
NoActivation	The action is never activated, evaluation never happens.
OnPress	Evaluation happens on initial activation (eg: button press).
OnRelease	Evaluation happens on de-activation (eg: button release).
RepeatOnHold	Evaluation happens repeatedly while the action is active (eg: button is held down).

ActivationBehaviors

enum ActivationBehaviors : ActivationBehavior

The DynamicScript.ActivationBehaviors type stores an OR combination of DynamicScript.ActivationBehavior values.

RepeatProperty

enum RepeatProperty : uint

Action repeat property type.

See also

DSE.setActionRepeat(), DSE.adjustActionRepeat()

Enumerator
RepeatRateProperty	Rate, or pause interval between repetitions, in milliseconds.
RepeatDelayProperty	Initial delay before the the first repetition is activated, in milliseconds.
AllRepeatProperties	OR combination of Rate and Delay properties.

Property Documentation

PLUGIN_VERSION_NUM

uint PLUGIN_VERSION_NUM

read

Current DSE plugin version number in integer format.

This is a "binary coded decimal" where
((MAJOR << 24) | (MINOR << 16) | (PATCH << 8) | BUILD) (each part is limited to values 0-99).
If formatted in hexadecimal this will match the version "number" that Touch Portal shows in the plugin's settings.
E.g. "1.2.30.4" == 16920580 == 0x01023004 or "01023004" as shown in Touch Portal.
The possible "name" part of a version is ignored (the build number increments for each new pre-release alpha/beta version and again on the final release).

PLUGIN_VERSION_STR

String PLUGIN_VERSION_STR

read

Current DSE plugin version number in "MAJOR.MINOR.PATCH.BUILD[-name]" string format.

Eg. "1.0.0.2" or "1.2.0.1-beta1". At least one of the digits always increments for each new published version. The build number increments for any/each new pre-release (alpha/beta) version and again on the final (it may increment in irregular intervals).

SCRIPTS_BASE_DIR

String SCRIPTS_BASE_DIR

read

The base directory path for script files. This is either the path specified in the plugin's "Script Files Base Directory" setting (in Touch Portal), or the plugin's current working directory (which is the default when nothing is specified in the setting).

VALUE_STATE_PREFIX

String VALUE_STATE_PREFIX

read

The prefix added by the plugin to an script instance's Name to form a unique State ID, before creating or updating it in Touch Portal. Touch Portal uses the unique ID to identify States.

See also

DynamicScript.stateId

VALUE_STATE_PARENT_CATEOGRY

String VALUE_STATE_PARENT_CATEOGRY

read

This property contains the name of the Touch Portal parent cateogry into which newly created States will be placed by default. This is where the States will appear in Touch Portal selector lists (which sort States at all). The category will always appear as a child of the main "Dynamic Script Engine" category.

See also

DynamicScript.stateParentCategory

PLATFORM_OS

String PLATFORM_OS

read

This property contains the name of the operating system running the plugin.

Possible values are:

  "linux" - Linux
  "osx" - macOS
  "unix" - Other Unix-based OS
  "windows" - Windows
  "android" - Android
  "ios" - iOS
  "winrt" - WinRT / UWP
  "wasm" - WebAssembly

TP_USER_DATA_PATH

String TP_USER_DATA_PATH

read

Contains the value of the current system user's Touch Portal settings directory path. This should be the same as shown in Touch Portal Settings -> Info -> Data folder field. The value is determined at plugin startup based on the current user and operating system.
Note that on Windows the path is separated with / (not backslashes). Backslashes are annoying in JavaScript and in just about every usage the forward slashes work just as well.

Since

v1.1

TP_VERSION_CODE

uint TP_VERSION_CODE

read

Numeric version of currently connected Touch Portal desktop application. eg. 301007

Since

v1.1

TP_VERSION_STR

String TP_VERSION_STR

read

String version of currently connected Touch Portal desktop application. eg. "3.1.7.0.0".

Since

v1.1

defaultActionRepeatRate

int defaultActionRepeatRate

readwrite

The global default action repeat rate (interval), in milliseconds. The rate is the amount of time to wait between repeat activations a held action. The repeat rate takes effect after the initial repeat delay. Minimum interval is 50ms.
This property has a change notification event: defaultActionRepeatRateChanged(int ms). A callback can be attached to, or detached from, this method by using the connect() and disconnect() syntax, eg:

function onRateChanged(ms) { console.log("Repeat Rate changed to " + ms); }
DSE.defaultActionRepeatRateChanged.connect(onRateChanged);
// ... later, to disconnect:
DSE.defaultActionRepeatRateChanged.disconnect(onRateChanged);

See also

defaultActionRepeatDelay, DynamicScript.repeatRate

Since

v1.2

defaultActionRepeatDelay

int defaultActionRepeatDelay

readwrite

The global default action repeat delay, in milliseconds. The delay is the amount of time before a held action starts repeating, after the initial activation. After this initial delay, the action will be repeated at the current repeat rate. Minimum delay is 50ms. This property has a change notification event: defaultActionRepeatDelayChanged(int ms). A callback can be attached to, or detached from, this method by using the connect() and disconnect() syntax, eg:

function onDelayChanged(ms) { console.log("Repeat Delay changed to " + ms); }
DSE.defaultActionRepeatDelayChanged.connect(onDelayChanged);
// ... later, to disconnect:
DSE.defaultActionRepeatDelayChanged.disconnect(onDelayChanged);

See also

defaultActionRepeatRate, DynamicScript.repeatDelay

Since

v1.2

engineInstanceType

DSE::EngineInstanceType engineInstanceType

read

Returns the engine instance type associated with the current script instance, one of DSE.EngineInstanceType enum values: DSE.PrivateInstance or DSE.SharedInstance.

See also

DynamicScript.engineType

Since

v1.2

engineInstanceName

String engineInstanceName

read

Returns the name of the engine instance associated with the current script instance. For the global shared engine this is always "Shared". For private engine instances, this may or may not be the same as the script's Instance Name, for example if a script action was set to use a specific private named engine instance instead of just "Private". Unlike currentInstanceName property, this value will always be constant, even inside asyncronous methods.

See also

currentInstanceName, DynamicScript.engineName

Since

v1.2

currentInstanceName

String currentInstanceName

read

The Instance Name of the script currently being evaluated, as specified in the corresponding Touch Portal action which invoked the script/expression. This is essentially the same as calling DSE.currentInstance()?.name.

Note

In some cases this property may return an empty, or even incorrect, result, such as when working inside asyncronous methods like with a Promise. In such cases it is best to save the intance name to a local constant variable before entering the asyncronous method.

See also

engineInstanceName, currentInstance(), DynamicScript.name

Since

v1.2

currentInstanceType

DSE::EngineInstanceType currentInstanceType

read

Alias for engineInstanceType.

See also

DynamicScript.engineType

Since

v1.2

INSTANCE_TYPE

String INSTANCE_TYPE

read

The scope of the current script's engine, either "Shared" or "Private".

Deprecated (since v1.2):

This property is deprecated and may be removed in a future version; Use DSE.engineInstanceType or DSE.currentInstace()?.engineType instead which return enumeration values instead of strings.

INSTANCE_NAME

String INSTANCE_NAME

read

The the current script's Instance Name, as specified in the corresponding Touch Portal action which is running the script/expression.

Deprecated (since v1.2):

This property is deprecated and may be removed in a future version; Use DSE.currentInstanceName or DSE.currentInstace()?.name instead.

INSTANCE_DEFAULT_VALUE

String INSTANCE_DEFAULT_VALUE

read

This is the default value as specified in the action which created this script instance, which may be empty/blank (but not null/undefined). This property is empty in Shared instance types.

Deprecated (since v1.2):

This property is deprecated and may be removed in a future version; Use DSE.currentInstance()?.defaultValue (for example) instead, which is more reliable and works in shared engine instances.

Member Function Documentation

instanceList()

Array< DynamicScript > instanceList

(

)

Returns all currently existing script instances as an iteratable array-like object (iterate with of eg. for (const ds of DSE.instanceList()) ...).

Since

v1.2

instance()

DynamicScript instance

(

String

name

)

Returns the script instance with given name, if any, otherwise returns null.

Since

v1.2

currentInstance()

DynamicScript currentInstance

(

)

Returns the current script Instance. This is equivalent to calling DSE.instance(DSE.currentInstanceName).

Note

In some cases this function may return a null result, such as when working inside asyncronous methods like with a Promise. If you need to access the current instance in such cases, you should save a reference to the instance before invoking any async methods and use the saved instace inside them. Or use the instance(String name) overload with a static string value for the instance name.

Since

v1.2

instanceStateId()

String instanceStateId

(

)

Gets Touch Portal State ID of the current script's instance. This is what Touch Portal actually uses to uniquely identify the state (not just the name by itself). This is a convenience method that returns the same as DSE.VALUE_STATE_PREFIX + DSE.INSTANCE_NAME.

Deprecated (since v1.2):

This function is deprecated and may be removed in a future version; DSE.currentInstace()?.stateId instead, for example.

setActionRepeat()

void setActionRepeat	(	DSE.RepeatProperty	property,
		int	ms,
		String	forInstance = ""
	)

Convenience method to set the action repeat rate and/or delay prooperties on either the global default or a specific named script instance.

Parameters

property	should be one of DSE.RepeatRateProperty, DSE.RepeatDelayProperty or DSE.AllRepeatProperties to set both rate and delay at the same time.
ms	is the new property value, in milliseconds (minimum is 50ms).
forInstance	can be a script Instance Name, or empty (default) to set the global default repeat properties.

See also

adjustActionRepeat()

Since

v1.2

adjustActionRepeat()

void adjustActionRepeat	(	DSE.RepeatProperty	property,
		int	byMs,
		String	forInstance = ""
	)

Convenience method to adjust the action repeat rate and/or delay prooperties on either the global default or a specific named script instance.

Parameters

property	should be one of DSE.RepeatRateProperty, DSE.RepeatDelayProperty or DSE.AllRepeatProperties to set both rate and delay at the same time.
byMs	is the adjustment amount, positive or negative, in milliseconds.
forInstance	can be a script Instance Name, or empty (default) to set the global default repeat properties.

See also

setActionRepeat()

Since

v1.2