v1.2.1.0

Description

The global TP namespace is used as a container for all Touch Portal API methods, which are invoked with TP. qualifier, eg. TP.stateUpdate("Hello!");.

Static Public Member Functions

Sending Data

These functions all send information or commands to Touch Portal.

void stateUpdate (String value)
 
void stateUpdate (String name, String value)
 
void stateUpdateById (String id, String value)
 
void stateCreate (String id, String parentGroup, String description, String defaultValue="", boolean forceUpdate=false, int delayMs=0)
 
void stateCreate (String id, String description, String defaultValue="", int delayMs=0)
 
void stateCreate (String id, String description, object options={})
 
void stateRemove (String id)
 
void choiceUpdate (String id, Array< String > values)
 
void choiceUpdateInstance (String id, String instanceId, Array< String > values)
 
void connectorUpdate (String shortId, int value)
 
void connectorUpdateByLongId (String connectorId, int value)
 
void showNotification (String notificationId, String title, String message, Array< Object > options=[],< Function|String|Array > callback=null)
 
void settingUpdate (String name, String value)
 
Events

These are events which are raised whenever some kind of data update is received from Touch Portal.

Events may pass one or more parameters to callback handlers (check documentation for specific events). To connect a handler to an event, use the connect() event prototype method:

function handler(parameters) { .... }
TP.eventName.connect(handler);
The global TP namespace is used as a container for all Touch Portal API methods, which are invoked wi...
Definition: touchportal.dox:6

There is also a 2-parameter version which allows a context object to be given, which then becomes the "this" object when the event handler callback is executed.

MyObject.prototype.myHandler = function(parameters) { ... }
const myObject = new MyObject();
TP.eventName.connect(myObject, myObject.myHandler);

To disconnect a handler, use the disconnect() method:

TP.eventName.disconnect(handler);
// or
TP.eventName.disconnect(myObject, myObject.myHandler);
void messageEvent (Object message)
 
void broadcastEvent (String event, Object data)
 
void connectorIdsChanged (String instanceName, String shortId)
 
Connector Data

Touch Portal reports connector instances to the plugin via shortConnectorIdNotification messages.

These messages are parsed and logged into a database. The functions in this group can be used to query the data based on various criteria about logged connectors. The connector short IDs can then be used to send updates back to Touch Portal, which will move the corresponding slider(s) into a particular position.

See also
connectorIdsChanged(), ConnectorRecord, Updating Sliders from Scripts, Color Mixer Example, Touch Portal Connectors API
Array< StringgetConnectorShortIds (Object criteria={})
 
Array< ConnectorRecordgetConnectorRecords (Object criteria={})
 
ConnectorRecord getConnectorByShortId (String shortId)
 
Other Data

Miscellaneous other data/information access functions.

String currentPageName ()
 

Member Function Documentation

◆ stateUpdate() [1/2]

void stateUpdate ( String  value)
static

Send a State update to Touch Portal with given value for the current script instance.

This only works with instances in a Private script engine.

See also
stateUpdate(String, String)

◆ stateUpdate() [2/2]

void stateUpdate ( String  name,
String  value 
)
static

Send a State update to Touch Portal for a DSE instance named name with given value.

This works with any type of engine instance, Shared or Private. The name will be turned into a fully qualified state ID as necessary (adding the required prefix to match default DSE state IDs).

See also
stateUpdate(String)

◆ stateUpdateById()

void stateUpdateById ( String  id,
String  value 
)
static

Send a State update to Touch Portal for any arbitrary state/value matching the id, with given value.

Note
This can be used to update other plugins' states and even TP global Values (at least as of TP 3.1.x).
See also
stateUpdate()

◆ stateCreate() [1/3]

void stateCreate ( String  id,
String  parentGroup,
String  description,
String  defaultValue = "",
boolean  forceUpdate = false,
int  delayMs = 0 
)
static

Create a new Touch Portal dynamic State (if it doesn't already exist).

Parameters
idMust be a fully qualified state ID (meaning it is not changed in any way and must be unique in TP).
parentGroupSets or creates the sorting category into which the state is placed in the user interface (it will show up as a child of this plugin's states list).
descriptionThis text will be used in the Touch Portal interface to represent the new state (optional if you don't need it selectable in TP UI).
defaultValueAn optional default value for the state, meaning it's initial value.
forceUpdateIf set to true will force TP to evaluate state change events based on the given default value, as if this was a stateUpdate message. When false (default), state change events based on default value may be skipped.
delayMsIf set to greater then zero this will introduce a delay of the specified number of milliseconds after creating the state. This can be useful to work around a TP issue where it may not register the new state before it processes a stateUpdate() message which immediately follows (this can result in TP log messages about the state being updated not belonging to this plugin). A short delay of 2ms or so can resolve this issue and avoid other workarounds (such as delaying the stateUpdate() with a timer).

Note that if you do not want/need a state to be available in the UI, then any stateUpdateById() call will also work (the state will be created if needed but not accessible via the UI).

Since
v1.2.1 added forceUpdate and delayMs arguments, defaultValue is optional.

◆ stateCreate() [2/3]

void stateCreate ( String  id,
String  description,
String  defaultValue = "",
int  delayMs = 0 
)
static

Overload of stateCreate() - Create a new Touch Portal dynamic State (if it doesn't already exist).

This form omits the parentGroup argument of the first version. The parent group of the new state will be determined automatically. This is effectively equivalent to calling:

stateUpdate(id, DSE.currentInstance().stateParentCategory, description, defaultValue, delayMs)
The DSE object contains constants and functions related to the plugin environment....
DynamicScript currentInstance()
Returns the current script Instance. This is equivalent to calling DSE.instance(DSE....
Definition: DSE.h:294
String stateParentCategory
This property holds the name of the Touch Portal parent cateogry into which the created State (if any...
Definition: DynamicScript.h:168
void stateUpdate(String value)
Send a State update to Touch Portal with given value for the current script instance.
Since
v1.2.1

◆ stateCreate() [3/3]

void stateCreate ( String  id,
String  description,
object  options = {} 
)
static

Overload of stateCreate() - Create a new Touch Portal dynamic State (if it doesn't already exist).

This form takes an optional options argument which can be an object with the following members (all are optional, default values are shown):

{
// The initial value of the state.
defaultValue?: {string} "",
// Sets or creates the sorting category into which the state is placed in the user interface (as a child of this plugin's states list).
parentGroup?: {string} DSE.currentInstance().stateParentCategory,
// If set to > 0 this will introduce a delay of the specified number of milliseconds after creating the state.
delayMs?: {int} 0,
// If set to `true` will force TP to evaluate state change events based on the given default value, as if this was a `stateUpdate` message.
forceUpdate?: {boolean} false
}
Since
v1.2.1

◆ stateRemove()

void stateRemove ( String  id)
static

Remove a Touch Portal dynamic State (if it exists).

The id must be fully qualified to match the ID of the existing state.

◆ choiceUpdate()

void choiceUpdate ( String  id,
Array< String values 
)
static

Update a list of choices for a selector with given id, which must be a fully qualified ID of some existing action data member (from some plugin).

values should be an array of strings.

◆ choiceUpdateInstance()

void choiceUpdateInstance ( String  id,
String  instanceId,
Array< String values 
)
static

Update a list of choices for a selector with given id and specific instanceId.

id must be a fully qualified ID of some existing action data member.
instanceId is the internal Touch Portal ID of a specific action instance. This is typically obtained from a 'listChange' Touch Portal message, but could also be obtained from the button ID or page source code.
values should be an array of strings.

Since
v1.2

◆ connectorUpdate()

void connectorUpdate ( String  shortId,
int  value 
)
static

Sends a connector (slider) update with given value which should be an integer in the range of 0 - 100.

The shortId should be a Touch Portal "short connector ID" as reported by Touch Portal in shortConnectorIdNotification messages.

These IDs can be looked up using TP.getShortConnectorIds() method. Another option is to subscribe to the TP.connectorIdsChanged() event and track any reported connectors that way. Another, somewhat slower, option is to retrieve a list of reported short IDs with TP.getConnectorRecords() and further process the result(s) to find the connector(s) you're looking for.

Note that is also possible to find these short IDs in the source JSON of a Touch Portal page (.tml file). Not recommended, but it can do in a pinch.

See also
Touch Portal Connectors API, Color Mixer Example

◆ connectorUpdateByLongId()

void connectorUpdateByLongId ( String  connectorId,
int  value 
)
static

Sends a connector (slider) update with given value which should be an integer in the range of 0 - 100.

The connectorId must be fully qualified "long ID" as described in Touch Portal API docs.

This method could in theory be used to update sliders with connectors provided by other plugins. In practice it is fairly limited since the full connectorId must be 200 characters or less, and coming up with those IDs in the first place can be challenging. However you may find some use for it after all.

See also
Touch Portal Connectors API
Since
v1.1

◆ showNotification()

void showNotification ( String  notificationId,
String  title,
String  message,
Array< Object >  options = [],
< Function|String|Array >  callback = null 
)
static

Creates or raises a user notification in the Touch Portal window.

See TP API docs for details on notifications.

Parameters
notificationIdshould be a unique string, if the user has already responded to a notification with the same notificationId then nothing will be shown.
titleThis will be shown at the top of the notification window.
messageThis is the body of the notification, the main text.
optionsThis is an optional array of "choice" objects which are presented in the notification for user to click on. For example:
[
{
"id":"option1",
"title":"Option 1 title"
},
{
"id":"option2",
"title":"Option 2 title"
}
]
callbackA callback to invoke when one of the options is clicked. The callback value can be a string, function, or an array.
  • A string type callback is simply evaluated (eval(callback)). There is no way to pass any arguments to this.
  • A function is called with the clicked option's id as the first argument and the notificationId as the second argument.
  • If an array is given, the first member of the array should be a function and the 2nd argument should be the this context with which to invoke the callback function. The function is invoked with the same arguments as described above.
See also
Fetch and Notify Example - GitHub Release Version Check, Touch Portal Notifications API

◆ settingUpdate()

void settingUpdate ( String  name,
String  value 
)
static

Update a plugin Setting in Touch Portal named name to value.

This only works for settings of the current plugin (defined in corresponding entry.tp).

Since
v1.2

◆ messageEvent()

void messageEvent ( Object  message)
static

This event is emitted upon every Touch Portal message received by this plugin.

The message parameter is an object representing the "raw" message data received from Touch Portal (originally as a JSON object). Each message will have a type property indicating the message type. Refer to Touch Portal API for further details on each message type and data it contains.

Since
v1.2

◆ broadcastEvent()

void broadcastEvent ( String  event,
Object  data 
)
static

This event is emitted when Touch Portal sends a broadcast message to all plugins.

The event parameter is the name of the event type.

  • As of TP v4.4 (API v10) this can only be "pageChange" to signify that a user has navigated to a new page on their Touch Portal device (not in the desktop page editor).

The data contains any further information about the event. For the pageChange event there is a member named pageName which holds the name of the newly selected page. The name may contain a "path" if the page is inside a subfolder. For example "(main)" or "games/MSFS".

TP v4 added previousPageName, deviceIp, deviceName, & deviceId properties. See https://www.touch-portal.com/api/index.php?section=communication_listen_broadcast for details.

Since
v1.1.0

◆ connectorIdsChanged()

void connectorIdsChanged ( String  instanceName,
String  shortId 
)
static

This event is emitted whenever a shortConnectorIdNotification message from Touch Portal has been received, parsed, and added to the tracking database.

The first parameter passed to event handlers is the State Name used in the connector which has been added/modified. Note that for all "Anonymous (One-Time)" type connectors the instanceName will always be "ANONYMOUS".

The second parameter is the shortId of this slider instance as created by Touch Portal. This short ID can be used later to send updates back to this slider.

You can connect to this event as described in the overall event documentation above, with either onconnectorIdsChanged() or connectorIdsChanged.connect() syntax.

See also
Color Mixer Example
Since
v1.1.0

◆ getConnectorShortIds()

Array< String > getConnectorShortIds ( Object  criteria = {})
static

Returns zero or more connector "short IDs" based on the given criteria from the currently logged connector notification data.

criteria is an object that can contain any of the properties of ConnectorRecord (unless explicitly documented otherwise). For most properties wildcard patterns can be used in the values (again, check ConnectorRecord documentation for details on each property).

For example, to find a Slider instance short ID for a connector with which loads a "example.mjs" module script and invokes a "run()" function with any parameters:

const shortIds = TP.getConnectorShortIds({ file: "*example.mjs", expression: "run(*)" });
Array< String > getConnectorShortIds(Object criteria={})
Returns zero or more connector "short IDs" based on the given criteria from the currently logged conn...

Wildcards are typical "GLOB" style: * for "match anything", ? for "any one character", or [xyz] to match any of a set of characters.

As noted in the ConnectorRecord documentation, some enumeration type properties can only be matched by their full value, like ConnectorRecord.actionType.

If criteria is empty/null/undefined, then all connector records currently in the database will be returned.

By default the results are sorted by newest first, that is by the timestamp property in descending (largest first) order. To specify a custom sort order, add the special property orderBy to the search criteria. The value of orderBy can be the name of any of the ConnectorRecord properties, optionally followed by ASC or DESC to specify the ordering for ascending (smaller first) or descending (largest first), respectively. Default is ascending order ("ASC"). Multiple properties can also be specified by separating them with a comma.

For example to find a all sliders for the current engine instance by State Name, sorted by oldest first and then by expression value in reverse alphabetical order:

const shortIds = TP.getConnectorShortIds({ instanceName: DSE.INSTANCE_NAME, orderBy: "timestamp ASC, expression DESC" });
String INSTANCE_NAME
The the current script's Instance Name, as specified in the corresponding Touch Portal action which i...
Definition: DSE.h:161
See also
connectorUpdate(), Updating Sliders from Scripts, Color Mixer Example
Since
v1.1.0

◆ getConnectorRecords()

Array< ConnectorRecord > getConnectorRecords ( Object  criteria = {})
static

Returns zero or more ConnectorRecord objects based on the given criteria from the currently logged connector notification data.

criteria is exactly the same as described for getConnectorShortIds() function, above.

The only difference here is that the results include the whole ConnectorRecord object, instead of just the shortId property. The objects can then be further examined as needed. Keep in mind these are all read-only results.

Since
v1.1.0

◆ getConnectorByShortId()

ConnectorRecord getConnectorByShortId ( String  shortId)
static

Returns a ConnectorRecord based on the given shortId from the currently logged connector notification data, if any.

If no matching record is found, the returned ConnectorRecord will be empty/null, which can be checked with ConnectorRecord.isNull property.

Short IDs are unique, so each one identifies a unique slider instance. This function could be particularly useful with the TP.connectorIdsChanged() event to get more information about the new slider short ID which is passed by that event to handlers as the 2nd parameter.

You can use a wildcard pattern in the shortId parameter, as described in previous documentation about search criteria. However this query will always return only one record. If the wildcard pattern matches multiple records, only the newest one (by timestamp) will be returned.

Note
There is currently no method in Touch Portal's API for determining that a slider/connector with a given short ID still actually exists on a user's page.
Since
v1.1.0

◆ currentPageName()

String currentPageName ( )
static

Returns the name of the page the user last opened on their Touch Portal device (not in the desktop page editor).

This is always the result of the last broadcastEvent()'s pageName property. See broadcastEvent() documentation for details.

Note
Touch Portal does not send this event to a plugin when it starts up, only once an actual page change happens the first time. As a result, the result of this function call may be empty until the user has switched pages on their device.
Since
v1.1.0