Touch Portal API (TP)

Description

Functions, data, and events for interacting with Touch Portal directly, such as updating state values or sending notifications.

These functions are part of the global TP namespace, used with TP. qualifier, eg. TP.stateUpdate("Hello!");.

Note that the "Touch Portal API" documented here, while closely related to Touch Portal's Plugin API, is not always an exact match, nor can always provide all the features a full plugin could have (such as custom Actions). Nevertheless it can be helpful to understand how Touch Portal interacts with data sent from plugins in the first place, since all those limits would apply here as well (in other words, this plugin can only work with the API features which are available to us in the first place).

See also

Touch Portal Plugin API

Members
class	TP
class	ConnectorRecord

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 desc="", String defaultValue="")
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). There are two syntactical ways to connect a callback function to an event. First is by using the usual 'on*' style syntax: TP.oneventName( (parameters) => { .... } ); The other way is with the connect() event prototype method: TP.eventName.connect( (parameters) => { .... } ); Both forms have 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.oneventName(myObject.myHandler, myObject); // OR (note the switched parameter order) TP.eventName.connect(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< String >	getConnectorShortIds (Object criteria={})
Array< ConnectorRecord >	getConnectorRecords (Object criteria={})
ConnectorRecord	getConnectorByShortId (String shortId)

Other Data
Miscellaneous other data/information access functions.
String	currentPageName ()

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()

void stateCreate ( String  id, String  parentGroup, String  desc = "", String  defaultValue = ""  )

static

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

Parameters

id	Must be a fully qualified state ID (meaning it is not changed in any way and must be unique in TP).
parentGroup	Sets 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).
desc	This 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).
defaultValue	An optional default value for the state, meaning it's initial value.

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).
Also note that there's currently a bug in TP (<= v3.1) that prevents state change events from being detected based on a default value.

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

notificationId	should be a unique string, if the user has already responded to a notification with the same notificationId then nothing will be shown.
title	This will be shown at the top of the notification window.
message	This is the body of the notification, the main text.
options	This 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" } ]
callback	A 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 v3.1 (API v6) 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 one member named pageName which holds the name of the newly selected page. The name may contain a "path" if the page is in side a subfolder. For example "(main)" or "games/MSFS".

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

Note

Touch Portal v3.2 is going to have a multi-device upgrade available, so multiple devices could be connected to one desktop application and have different pages open. It's not clear yet how this will affect the "pageChange" broadcast event.

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(*)" });

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" });

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