Description

The TPClientQt class is a simple TCP/IP network client for usage in Touch Portal plugins which wish to utilize the Qt C++ library/framework.

Note: Familiarity with the Touch Portal API is assumed throughout this documentation. The client performs no error checking in terms of what the user tries to send to TP, and in most cases delivers only the JSON data as it came from TP (parsed into QJson* types).

Messages from TP are delivered via the message(MessageType, const QJsonObject &) signal, which identifies the message type with an enumerator and passes the message data on as a QJsonObject. Beyond determining the message type, no other processing is done on the incoming data.

Sending messages to TP can be done at 3 different levels:

The (very overloaded) methods provided by this class which have names eponymous with the corresponding TP API message types. Eg: stateUpdate(), showNotification(), etc.
Arbitrary JSON object via the send() method or from a serialized QVariantMap via sendMap();
Raw bytes with the write() method.

The client emits connected(), disconnected(), and error() signals to notify the plugin of connection status and network state changes. Disconnections may happen spontaneously for a number of reasons (socket error, TP quitting, etc). Notably, error() is emitted if the initial connection to Touch Portal fails.

Note: It is the responsibility of the plugin itself to take appropriate termination actions when the connection to TP is lost/closed, either on purpose or due to error, and especially if/when TP sends the closePlugin message (which expects the plugin process to exit).

Some static convenience functions are provided for dealing with action/connector data coming from TP (for retrieving individual data values or coercing the incoming arrays into more user-friendly structures). See the actionData*() function references.

The client depends on the QtCore and QtNetwork libraries/modules. Tested with Qt versions 5.12.12, 5.15.7, 6.4.1.

Some minimal logging is performed via QLoggingCategory named "TPClientQt". By default, in Debug builds (QT_DEBUG defined) Debug-level messages (and above) are emitted, while on other builds the minimum level is set to Warning. This can be controlled as usual per Qt logging categories, eg. with QT_LOGGING_RULES env. var, config file, or eg. QLoggingCategory::setFilterRules("TPClientQt.info = true");.

NOTE:
All methods and functions in this class are reentrant. Not thread-safe: do not attempt to send messages from multiple threads w/out serializing the access (mutex, etc).

The TPClientQt itself can be moved into a new thread if desired, as long as the above conditions remain true.

Definition at line 84 of file TPClientQt.h.

#include "TPClientQt.h"

Member Classes
struct	ActionDataItem

struct	TPInfo

Public Types
enum class	MessageType : short { Unknown , info , settings , action , down , up , connectorChange , shortConnectorIdNotification , listChange , broadcast , notificationOptionClicked , closePlugin }

Public Member Functions
	TPClientQt (const char pluginId, QObject parent=nullptr)


bool	isConnected () const

QAbstractSocket::SocketState	socketState () const

QAbstractSocket::SocketError	socketError () const

QString	errorString () const

const TPClientQt::TPInfo &	tpInfo () const

QString	pluginId () const

bool	setPluginId (const char *pluginId)

QString	hostName () const

uint16_t	hostPort () const

void	setHostProperties (const QString &nameOrAddress=QStringLiteral("127.0.0.1"), uint16_t port=12136)

int	connectionTimeout () const

void	setConnectionTimeout (int timeoutMs=10000)


void	stateUpdate (const char id, const char value) const

void	createState (const char id, const char parentGroup, const char desc, const char defaultValue) const

void	createState (const std::string &id, const std::string &parentGroup, const std::string &desc, const std::string &defaultValue="") const

void	createState (const char id, const char desc, const char *defaultValue) const

void	createState (const std::string &id, const std::string &desc, const std::string &defaultValue="") const

void	removeState (const char *id) const

void	removeState (const std::string &id) const

void	choiceUpdate (const char *id, const QJsonArray &values) const

void	choiceUpdate (const char id, const QVector< const char > &values) const

void	choiceUpdate (const char *id, const QStringList &values) const

void	choiceUpdate (const std::string &id, const std::vector< std::string > &values) const

void	choiceUpdate (const char id, const char instanceId, const QJsonArray &values) const

void	choiceUpdate (const char id, const char instanceId, const QVector< const char * > &values) const

void	choiceUpdate (const char id, const char instanceId, const QStringList &values) const

void	choiceUpdate (const std::string &id, const std::string &instanceId, const std::vector< std::string > &values) const

void	connectorUpdate (const char *shortId, uint8_t value) const

void	connectorUpdate (const std::string &shortId, uint8_t value) const

void	connectorUpdate (const char *connectortId, uint8_t value, bool addPrefix) const

void	connectorUpdate (const std::string &connectortId, uint8_t value, bool addPrefix) const

void	connectorUpdate (const char connectortId, const QMap< const char , const char * > &nvPairs, uint8_t value, bool addPrefix=true) const

void	settingUpdate (const char name, const char value) const

void	settingUpdate (const std::string &name, const std::string &value) const

void	showNotification (const char notificationId, const char title, const char *msg, const QJsonArray &options) const

void	showNotification (const char notificationId, const char title, const char *msg, const QVariantList &options) const

void	showNotification (const char notificationId, const char title, const char msg, const QVector< QPair< const char , const char * > > &options) const

void	showNotification (const char notificationId, const char title, const char msg, const std::vector< std::pair< const char , const char * > > &options) const

void	showNotification (const std::string &notificationId, const std::string &title, const std::string &msg, const std::vector< std::pair< std::string, std::string > > &options) const


QByteArray	encode (const QJsonObject &object) const

Static Public Member Functions

static ActionDataItem	actionDataItem (int index, const QJsonArray &data, const ActionDataItem &defaultItem=ActionDataItem())

static QString	actionDataValue (int index, const QJsonArray &data, const QString &defaultValue=QLatin1String(""))

static QString	actionDataValue (const char *id, const QJsonArray &data, const QString &defaultValue=QLatin1String(""))

static QVector< ActionDataItem >	actionDataToItemArray (const QJsonArray &data, char separator=0)

static QMap< QString, QString >	actionDataToMap (const QJsonArray &data, char separator=0)

Public Slots

void	connect ()

void	connect (int timeout, const QString &host=QString(), uint16_t port=0)

void	disconnect () const


void	send (const QJsonObject &object) const

void	sendMap (const QVariantMap &map) const

void	write (const QByteArray &data) const


void	stateUpdate (const QByteArray &id, const QByteArray &value) const

void	stateUpdate (QStringView id, QStringView value) const

void	createState (const QByteArray &id, const QByteArray &parentGroup, const QByteArray &desc, const QByteArray &defaultValue) const

void	createState (QStringView id, QStringView parentGroup, QStringView desc, QStringView defaultValue) const

void	createState (const QByteArray &id, const QByteArray &desc, const QByteArray &defaultValue) const

void	createState (QStringView id, QStringView desc, QStringView defaultValue) const

void	removeState (const QByteArray &id) const

void	removeState (QStringView id) const

void	choiceUpdate (const QByteArray &id, const QJsonArray &values) const

void	choiceUpdate (const QByteArray &id, const QVector< QByteArray > &values) const

void	choiceUpdate (const QByteArray &id, const QStringList &values) const

void	choiceUpdate (const QByteArray &id, const QByteArrayList &values) const

void	choiceUpdate (QStringView id, const QJsonArray &values) const

void	choiceUpdate (QStringView id, const QVector< QStringView > &values) const

void	choiceUpdate (QStringView id, const QStringList &values) const

void	choiceUpdate (QStringView id, const QByteArrayList &values) const

void	choiceUpdate (const QByteArray &id, const QByteArray &instanceId, const QJsonArray &values) const

void	choiceUpdate (const QByteArray &id, const QByteArray &instanceId, const QVector< QByteArray > &values) const

void	choiceUpdate (const QByteArray &id, const QByteArray &instanceId, const QStringList &values) const

void	choiceUpdate (const QByteArray &id, const QByteArray &instanceId, const QByteArrayList &values) const

void	choiceUpdate (QStringView id, QStringView instanceId, const QJsonArray &values) const

void	choiceUpdate (QStringView id, QStringView instanceId, const QVector< QStringView > &values) const

void	choiceUpdate (QStringView id, QStringView instanceId, const QStringList &values) const

void	choiceUpdate (QStringView id, QStringView instanceId, const QByteArrayList &values) const

void	connectorUpdate (const QByteArray &shortId, uint8_t value) const

void	connectorUpdate (QStringView shortId, uint8_t value) const

void	connectorUpdate (const QByteArray &connectortId, uint8_t value, bool addPrefix) const

void	connectorUpdate (QStringView connectortId, uint8_t value, bool addPrefix) const

void	connectorUpdate (const QByteArray &connectortId, const QMap< const QByteArray, const QByteArray > &nvPairs, uint8_t value, bool addPrefix=true) const

void	connectorUpdate (QStringView connectortId, const QMap< QStringView, QStringView > &nvPairs, uint8_t value, bool addPrefix=true) const

void	settingUpdate (const QByteArray &name, const QByteArray &value) const

void	settingUpdate (QStringView name, QStringView value) const

void	showNotification (const QByteArray &notificationId, const QByteArray &title, const QByteArray &msg, const QJsonArray &options) const

void	showNotification (const QByteArray &notificationId, const QByteArray &title, const QByteArray &msg, const QVariantList &options) const

void	showNotification (QStringView notificationId, QStringView title, QStringView msg, const QVariantList &options) const

void	showNotification (const QByteArray &notificationId, const QByteArray &title, const QByteArray &msg, const QVector< QPair< QLatin1String, QStringView > > &options) const

void	showNotification (QStringView notificationId, QStringView title, QStringView msg, const QVector< QPair< QStringView, QStringView > > &options) const

Signals
void	connected (const TPClientQt::TPInfo &tpInfo, const QJsonObject &settings)

void	disconnected ()

void	error (QAbstractSocket::SocketError error)

void	message (TPClientQt::MessageType type, const QJsonObject &message)

Class Documentation

◆ TPClientQt::ActionDataItem

struct TPClientQt::ActionDataItem

Class Members
QString	id	ID of the action data member.
QString	value	Current value of the data member.

◆ TPClientQt::TPInfo

struct TPClientQt::TPInfo

Class Members
bool	paired	true if actively connected to TP; expects that 'status' == 'paired' in initial 'info' message. Reset to `false` when disconnected from TP.
uint32_t	pluginVersion	Numeric plugin version read from entry.tp file.
uint16_t	sdkVersion	Supported SDK version.
QString	status	The 'status' property from initial 'info' message (typically "paired"); This does not get changed after disconnection (see `paired`).
uint32_t	tpVersionCode	Numeric Touch Portal version.
QString	tpVersionString	Touch Portal version number as text.

Member Enumeration Documentation

◆ MessageType

enum class MessageType : short

strong

This enumeration is used in the message() signal to indicate message type. The names match the Touch Portal API message names, with the exception of Unknown. This is a strongly typed enum class because some of the names are common words. It is registered with Qt meta system and is suitable for queued signals/slots.

Enumerator
Unknown	An unknown event, perhaps from a newer version of TP which isn't supported yet.
info	The initial connection event, sent after pairing with TP.
settings	Emitted for 'info' and 'settings' message type; value/settings array is flattened to QJsonObject of {'setting name': 'value', ...} pairs.
action	An action click/touch event.
down	Action button press event.
up	Action button release event.
connectorChange	Connector value change.
shortConnectorIdNotification	Connector ID mapping event.
listChange	Action data choice change event.
broadcast	Page change event.
notificationOptionClicked	User clicked an option in a notification.
closePlugin	Plugin STOP event. It is the responsibility of the plugin to initiate disconnection after this message is received.

Definition at line 90 of file TPClientQt.h.

Constructor & Destructor Documentation

◆ TPClientQt()

TPClientQt	(	const char *	pluginId,
		QObject *	parent = `nullptr`
	)

explicit

The constructor creates the instance but does not attempt any connections. The pluginId will be used in the initial pairing message sent to Touch Portal, and must match ID in the plugin's entry.tp config file. You could pass a null ID here and set it later with setPluginId(), but an ID is required before trying to connect to TP.

See also: connect()

Definition at line 173 of file TPClientQt.cpp.

Member Function Documentation

◆ actionDataItem()

TPClientQt::ActionDataItem actionDataItem	(	int	index,
		const QJsonArray &	data,
		const ActionDataItem &	defaultItem = `ActionDataItem()`
	)

inlinestatic

Returns the action data object (id and value as ActionDataItem struct) at given index in the given array of action/connector data values (as sent from TP), or the optional defaultItem item if the index is out of bounds (or a default-constructed ActionDataItem if defaultItem is not provided).

Definition at line 658 of file TPClientQt.h.

◆ actionDataToItemArray()

QVector< TPClientQt::ActionDataItem > actionDataToItemArray	(	const QJsonArray &	data,
		char	separator = `0`
	)

inlinestatic

Convert JSON array of action data objects: [ { 'id': id, 'value': value }, ... ] to a vector of ActionDataItem types. If separator is not zero, the data IDs will be split on this character and only the last part will be saved in the returned ActionDataItems' id.

Definition at line 695 of file TPClientQt.h.

◆ actionDataToMap()

QMap< QString, QString > actionDataToMap	(	const QJsonArray &	data,
		char	separator = `0`
	)

inlinestatic

Flattens array of objects: [ { 'id': id, 'value': value }, ... ] to a single mapping of { {id, value}, ... } (assuming each data id key is unique). This allows simplified lookup by data ID string (vs. index), and is also iterable. The returned map does not preserve the original data order. If separator is not zero, the data IDs will be split on this character and only the last part will be saved in the returned map's key names.

Definition at line 713 of file TPClientQt.h.

◆ actionDataValue() [1/2]

QString actionDataValue	(	const char *	id,
		const QJsonArray &	data,
		const QString &	defaultValue = `QLatin1String("")`
	)

inlinestatic

Returns the 'value' member of the action data object with given id in the given array of action/connector data values (as sent from TP), or the given defaultValue if the data member doesn't exist in the array (or for some reason doesn't have a 'value' member).

Note: This has to loop over the data array until the member with given id is found (or not). If needing named data values more than once per action processing, it would likely be more efficient to use actionDataToMap() and store the result.

Definition at line 677 of file TPClientQt.h.

◆ actionDataValue() [2/2]

QString actionDataValue	(	int	index,
		const QJsonArray &	data,
		const QString &	defaultValue = `QLatin1String("")`
	)

inlinestatic

Returns the 'value' member of the action data object at given index in the given array of action/connector data values (as sent from TP), or the given defaultValue if the data member doesn't exist in the array (or for some reason doesn't have a 'value' member).

Definition at line 670 of file TPClientQt.h.

◆ choiceUpdate() [1/24]

void choiceUpdate	(	const char *	id,
		const char *	instanceId,
		const QJsonArray &	values
	)		const

inline

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a QJsonArray of strings. QJsonArray is most efficient as it requires no further conversion before sending.

Definition at line 547 of file TPClientQt.h.

◆ choiceUpdate() [2/24]

void choiceUpdate	(	const char *	id,
		const char *	instanceId,
		const QStringList &	values
	)		const

inline

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a vector of const char strings.

Definition at line 222 of file TPClientQt.h.

◆ choiceUpdate() [3/24]

void choiceUpdate	(	const char *	id,
		const char *	instanceId,
		const QVector< const char * > &	values
	)		const

inline

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a vector of const char strings.

Definition at line 220 of file TPClientQt.h.

◆ choiceUpdate() [4/24]

void choiceUpdate	(	const char *	id,
		const QJsonArray &	values
	)		const

inline

Update a list of action data choices for action data with given id using a QJsonArray of strings. QJsonArray is most efficient as it requires no further conversion before sending.

Definition at line 537 of file TPClientQt.h.

◆ choiceUpdate() [5/24]

void choiceUpdate	(	const char *	id,
		const QStringList &	values
	)		const

inline

Update a list of action data choices for action data with given id using a list of QStrings.

Definition at line 214 of file TPClientQt.h.

◆ choiceUpdate() [6/24]

void choiceUpdate	(	const char *	id,
		const QVector< const char * > &	values
	)		const

inline

Update a list of action data choices for action data with given id using a vector of const char strings.

Definition at line 212 of file TPClientQt.h.

◆ choiceUpdate [7/24]

void choiceUpdate	(	const QByteArray &	id,
		const QByteArray &	instanceId,
		const QByteArrayList &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a QByteArray list.

Note: This method only exists on Qt < v6. With v6+ QByteArrayList is the same as QVector<QByteArray>.

Definition at line 358 of file TPClientQt.h.

◆ choiceUpdate [8/24]

void choiceUpdate	(	const QByteArray &	id,
		const QByteArray &	instanceId,
		const QJsonArray &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a QJsonArray of strings. QJsonArray is most efficient as it requires no further conversion before sending.

Definition at line 350 of file TPClientQt.h.

◆ choiceUpdate [9/24]

void choiceUpdate	(	const QByteArray &	id,
		const QByteArray &	instanceId,
		const QStringList &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a list of QStrings.

Definition at line 354 of file TPClientQt.h.

◆ choiceUpdate [10/24]

void choiceUpdate	(	const QByteArray &	id,
		const QByteArray &	instanceId,
		const QVector< QByteArray > &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a vector of QByteArray types.

Definition at line 352 of file TPClientQt.h.

◆ choiceUpdate [11/24]

void choiceUpdate	(	const QByteArray &	id,
		const QByteArrayList &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id using a QByteArray list.

Note: This method only exists on Qt < v6. With v6+ QByteArrayList is the same as QVector<QByteArray>.

Definition at line 338 of file TPClientQt.h.

◆ choiceUpdate [12/24]

void choiceUpdate	(	const QByteArray &	id,
		const QJsonArray &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id using a QJsonArray of strings. QJsonArray is most efficient as it requires no further conversion before sending.

Definition at line 330 of file TPClientQt.h.

◆ choiceUpdate [13/24]

void choiceUpdate	(	const QByteArray &	id,
		const QStringList &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id using a list of QStrings.

Definition at line 334 of file TPClientQt.h.

◆ choiceUpdate [14/24]

void choiceUpdate	(	const QByteArray &	id,
		const QVector< QByteArray > &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id using a vector of QByteArray types.

Definition at line 332 of file TPClientQt.h.

◆ choiceUpdate() [15/24]

void choiceUpdate	(	const std::string &	id,
		const std::string &	instanceId,
		const std::vector< std::string > &	values
	)		const

inline

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a std::vector of std::string types.

Definition at line 224 of file TPClientQt.h.

◆ choiceUpdate() [16/24]

void choiceUpdate	(	const std::string &	id,
		const std::vector< std::string > &	values
	)		const

inline

Update a list of action data choices for action data with given id using a std::vector of std::string types.

Definition at line 216 of file TPClientQt.h.

◆ choiceUpdate [17/24]

void choiceUpdate	(	QStringView	id,
		const QByteArrayList &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id using a QByteArray list.

Definition at line 347 of file TPClientQt.h.

◆ choiceUpdate [18/24]

void choiceUpdate	(	QStringView	id,
		const QJsonArray &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id using a vector of QJsonArray of strings. QJsonArray is most efficient as it requires no further conversion before sending.

Definition at line 341 of file TPClientQt.h.

◆ choiceUpdate [19/24]

void choiceUpdate	(	QStringView	id,
		const QStringList &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id using a list of QStrings.

Definition at line 345 of file TPClientQt.h.

◆ choiceUpdate [20/24]

void choiceUpdate	(	QStringView	id,
		const QVector< QStringView > &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id using a vector of QStringView-compatible types.

Definition at line 343 of file TPClientQt.h.

◆ choiceUpdate [21/24]

void choiceUpdate	(	QStringView	id,
		QStringView	instanceId,
		const QByteArrayList &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a QByteArray list.

Definition at line 367 of file TPClientQt.h.

◆ choiceUpdate [22/24]

void choiceUpdate	(	QStringView	id,
		QStringView	instanceId,
		const QJsonArray &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a QJsonArray of strings. QJsonArray is most efficient as it requires no further conversion before sending.

Definition at line 361 of file TPClientQt.h.

◆ choiceUpdate [23/24]

void choiceUpdate	(	QStringView	id,
		QStringView	instanceId,
		const QStringList &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a list of QStrings.

Definition at line 365 of file TPClientQt.h.

◆ choiceUpdate [24/24]

void choiceUpdate	(	QStringView	id,
		QStringView	instanceId,
		const QVector< QStringView > &	values
	)		const

inlineslot

Update a list of action data choices for action data with given id and specific instanceId reported by TP, using a vector of QStringView-compatible types.

Definition at line 363 of file TPClientQt.h.

◆ connect [1/2]

void connect ( )

slot

Initiate a connection to Touch Portal. The plugin ID (set in constructor or with setPluginId() must be valid. This first tries to open a network socket connection, and if that succeeds then the initial 'pair' message is sent to Touch Portal. Upon actual successful pairing, meaning an 'info' message response was received from TP with 'status' == "paired", the connected() signal is emitted. If either the initial socket connection or pairing with TP fails within the connectionTimeout() period, then the error(QAbstractSocket::SocketError) signal is emitted. If connectionTimeout() is <= 0 then the client will not wait for a successful pair response from TP and will assume it is connected as long as the network socket is open.

See also: error() signal, connectionTimeout(), setConnectionTimeout()

Definition at line 237 of file TPClientQt.cpp.

◆ connect [2/2]

void connect	(	int	timeout,
		const QString &	host = `QString()`,
		uint16_t	port = `0`
	)

inlineslot

Initiate a connection to Touch Portal. The plugin ID (set in constructor or with setPluginId() must be valid. This is a "shortcut" method which first calls setConnectionTimeout(timeout) and setHostProperties(host, port) before calling connect(). To ignore any of the arguments (not change the corresponding TPClientQt properties), pass timeout < 0, host = QString() (default), and/or port = 0 (default).

See also: connect()

Definition at line 497 of file TPClientQt.h.

◆ connected

void connected	(	const TPClientQt::TPInfo &	tpInfo,
		const QJsonObject &	settings
	)

signal

Emitted upon successful connection and pairing with Touch Portal. Data from the initial pairing 'info' message is passed in tpInfo struct along with the initial settings object. settings object is the original settings array sent from Touch Portal but flattened to QJsonObject of ‘{'setting name’: 'value', ...}` pairs.

See also: TPInfo, MessageType::settings

◆ connectionTimeout()

int connectionTimeout ( ) const

Returns the currently set connection timeout value, in milliseconds. This is either the default or one explicitly set with setConnectionTimeout().

Definition at line 207 of file TPClientQt.cpp.

◆ connectorUpdate() [1/11]

void connectorUpdate	(	const char *	connectortId,
		const QMap< const char , const char > &	nvPairs,
		uint8_t	value,
		bool	addPrefix = `true`
	)		const

inline

Update a Connector value with given connectortId. This overload takes a mapping of action data id/value pairs and builds up the long connectorId string for you (see TP API docs for details on long connectorId format). Valid value range is 0-100. If addPrefix is set to true then the string "pc_" + the plugin ID + "_" is prepended to the given connectorId value.

Definition at line 578 of file TPClientQt.h.

◆ connectorUpdate() [2/11]

void connectorUpdate	(	const char *	connectortId,
		uint8_t	value,
		bool	addPrefix
	)		const

inline

Update a Connector value with given full connectortId (see TP API docs for details). Valid value range is 0-100. If addPrefix is set to true then the string "pc_" + the plugin ID + "_" is prepended to the given connectorId value.

Definition at line 568 of file TPClientQt.h.

◆ connectorUpdate() [3/11]

void connectorUpdate	(	const char *	shortId,
		uint8_t	value
	)		const

inline

Update a Connector value with given shortId as reported by TP. Valid value range is 0-100.

Definition at line 558 of file TPClientQt.h.

◆ connectorUpdate [4/11]

void connectorUpdate	(	const QByteArray &	connectortId,
		const QMap< const QByteArray, const QByteArray > &	nvPairs,
		uint8_t	value,
		bool	addPrefix = `true`
	)		const

inlineslot

Update a Connector value with given connectortId. This overload takes a mapping of action data id/value pairs and builds up the long connectorId string for you (see TP API docs for details on long connectorId format). Valid value range is 0-100. If addPrefix is set to true then the string "pc_" + the plugin ID + "_" is prepended to the given connectorId value.

Definition at line 587 of file TPClientQt.h.

◆ connectorUpdate [5/11]

void connectorUpdate	(	const QByteArray &	connectortId,
		uint8_t	value,
		bool	addPrefix
	)		const

inlineslot

Update a Connector value with given full connectortId (see TP API docs for details). Valid value range is 0-100. If addPrefix is set to true then the string "pc_" + the plugin ID + "_" is prepended to the given connectorId value.

Definition at line 376 of file TPClientQt.h.

◆ connectorUpdate [6/11]

void connectorUpdate	(	const QByteArray &	shortId,
		uint8_t	value
	)		const

inlineslot

Update a Connector value with given shortId as reported by TP. Valid value range is 0-100.

Definition at line 370 of file TPClientQt.h.

◆ connectorUpdate() [7/11]

void connectorUpdate	(	const std::string &	connectortId,
		uint8_t	value,
		bool	addPrefix
	)		const

inline

Update a Connector value with given full connectortId (see TP API docs for details). Valid value range is 0-100. If addPrefix is set to true then the string "pc_" + the plugin ID + "_" is prepended to the given connectorId value.

Definition at line 236 of file TPClientQt.h.

◆ connectorUpdate() [8/11]

void connectorUpdate	(	const std::string &	shortId,
		uint8_t	value
	)		const

inline

Update a Connector value with given shortId as reported by TP. Valid value range is 0-100.

Definition at line 229 of file TPClientQt.h.

◆ connectorUpdate [9/11]

void connectorUpdate	(	QStringView	connectortId,
		const QMap< QStringView, QStringView > &	nvPairs,
		uint8_t	value,
		bool	addPrefix = `true`
	)		const

inlineslot

Update a Connector value with given connectortId. This overload takes a mapping of action data id/value pairs and builds up the long connectorId string for you (see TP API docs for details on long connectorId format). Valid value range is 0-100. If addPrefix is set to true then the string "pc_" + the plugin ID + "_" is prepended to the given connectorId value.

Definition at line 596 of file TPClientQt.h.

◆ connectorUpdate [10/11]

void connectorUpdate	(	QStringView	connectortId,
		uint8_t	value,
		bool	addPrefix
	)		const

inlineslot

Update a Connector value with given full connectortId (see TP API docs for details). Valid value range is 0-100. If addPrefix is set to true then the string "pc_" + the plugin ID + "_" is prepended to the given connectorId value.

Definition at line 379 of file TPClientQt.h.

◆ connectorUpdate [11/11]

void connectorUpdate	(	QStringView	shortId,
		uint8_t	value
	)		const

inlineslot

Update a Connector value with given shortId as reported by TP. Valid value range is 0-100.

Definition at line 372 of file TPClientQt.h.

◆ createState() [1/8]

void createState	(	const char *	id,
		const char *	desc,
		const char *	defaultValue
	)		const

inline

Create a new dynamic state with given id, description and default value strings. Passing nullptr to defaultValue is same as using an empty string.

Definition at line 201 of file TPClientQt.h.

◆ createState() [2/8]

void createState	(	const char *	id,
		const char *	parentGroup,
		const char *	desc,
		const char *	defaultValue
	)		const

inline

Create a new dynamic state with given id, parentGroup, description and default value strings. Passing nullptr to defaultValue is same as using an empty string.

Definition at line 516 of file TPClientQt.h.

◆ createState [3/8]

void createState	(	const QByteArray &	id,
		const QByteArray &	desc,
		const QByteArray &	defaultValue
	)		const

inlineslot

Create a new dynamic state with given id, description and defaultValue strings.

Definition at line 320 of file TPClientQt.h.

◆ createState [4/8]

void createState	(	const QByteArray &	id,
		const QByteArray &	parentGroup,
		const QByteArray &	desc,
		const QByteArray &	defaultValue
	)		const

inlineslot

Create a new dynamic state with given id, parentGroup, description and defaultValue strings.

Definition at line 316 of file TPClientQt.h.

◆ createState() [5/8]

void createState	(	const std::string &	id,
		const std::string &	desc,
		const std::string &	defaultValue = `""`
	)		const

inline

Create a new dynamic state with given id, description and default value strings.

Definition at line 203 of file TPClientQt.h.

◆ createState() [6/8]

void createState	(	const std::string &	id,
		const std::string &	parentGroup,
		const std::string &	desc,
		const std::string &	defaultValue = `""`
	)		const

inline

Create a new dynamic state with given id, parentGroup, description and default value strings.

Definition at line 199 of file TPClientQt.h.

◆ createState [7/8]

void createState	(	QStringView	id,
		QStringView	desc,
		QStringView	defaultValue
	)		const

inlineslot

Create a new dynamic state with given id, description and defaultValue strings.

Definition at line 322 of file TPClientQt.h.

◆ createState [8/8]

void createState	(	QStringView	id,
		QStringView	parentGroup,
		QStringView	desc,
		QStringView	defaultValue
	)		const

inlineslot

Create a new dynamic state with given id, parentGroup, description and defaultValue strings.

Definition at line 318 of file TPClientQt.h.

◆ disconnect

void disconnect ( ) const

slot

Initiates disconnection from Touch Portal. This flushes and gracefully closes any open network sockets. The disconnected() signal will be emitted upon actual disconnection (which may not be immediate). Returns immediately if the connection isn't already open.

Definition at line 260 of file TPClientQt.cpp.

◆ disconnected

void disconnected ( )

signal

Emitted upon disconnection from Touch Portal, either from an explicit call to close() or if the connection is closed unexpectedly, by the remote host (eg. Touch Portal exits) or some other unrecoverable socket error. It is the responsibility of the plugin to take any appropriate action after a disconnection or error event. The last error, if any, can be retrieved via socketError() method.

◆ encode()

QByteArray encode ( const QJsonObject & object ) const

inline

Low-level API: Serializes a JSON object to UTF8 bytes. object should contain one TP message. This can be then be sent to TP via write() method.

Definition at line 265 of file TPClientQt.h.

◆ error

void error ( QAbstractSocket::SocketError error )

signal

Emitted in case of error upon initial connection or unexpected termination. This would typically be what is reported by the QTcpSocket being used, but during initial connection attempt it may also return one of:

QAbstractSocket::ConnectionRefusedError - Touch Portal refused connection with an invalid status in 'info' message.
QAbstractSocket::SocketTimeoutError - Network connection was established but Touch Portal didn't respond to our 'pair' message within the connectionTimeout() period.
QAbstractSocket::OperationError - Parameter validation error, eg. pluginId is null.

◆ errorString()

QString errorString ( ) const

Returns the current TCP/IP network error, if any, as a human-readable string.

See also: QIODevice::errorString()

Definition at line 201 of file TPClientQt.cpp.

◆ hostName()

QString hostName ( ) const

Returns the currently set Touch Portal host name/address string. This is either the default or one explicitly set with setHostProperties();.

Definition at line 205 of file TPClientQt.cpp.

◆ hostPort()

uint16_t hostPort ( ) const

Returns the currently set Touch Portal host port. This is either the default or one explicitly set with setHostProperties();.

Definition at line 206 of file TPClientQt.cpp.

◆ isConnected()

bool isConnected ( ) const

Returns true if connected to Touch Portal, false otherwise.

Definition at line 198 of file TPClientQt.cpp.

◆ message

void message	(	TPClientQt::MessageType	type,
		const QJsonObject &	message
	)

signal

Emitted when any message is received from Touch Portal. Refer to the TP API for specifics of each message type and what data to expect in the JSON message object. The type is simply derived from the 'type' value found in each TP message, or TPClientQt::MessageType::Unknown if the message type wasn't recognized (eg. TP is using a newer API than this client supports).

◆ pluginId()

QString pluginId ( ) const

Returns the plugin ID set in constructor or with setPluginId().

Definition at line 204 of file TPClientQt.cpp.

◆ removeState() [1/4]

void removeState ( const char * id ) const

inline

Delete (remove) a dynamic state with given id string.

Definition at line 528 of file TPClientQt.h.

◆ removeState [2/4]

void removeState ( const QByteArray & id ) const

inlineslot

Delete (remove) a dynamic state with given id string.

Definition at line 325 of file TPClientQt.h.

◆ removeState() [3/4]

void removeState ( const std::string & id ) const

inline

Delete (remove) a dynamic state with given id string.

Definition at line 207 of file TPClientQt.h.

◆ removeState [4/4]

void removeState ( QStringView id ) const

inlineslot

Delete (remove) a dynamic state with given id string.

Definition at line 327 of file TPClientQt.h.

◆ send

void send ( const QJsonObject & object ) const

inlineslot

Low-level API: Send JSON message data to Touch Portal. object should contain one TP message. All other methods for sending structured data are conveniences for this method.

Definition at line 298 of file TPClientQt.h.

◆ sendMap

void sendMap ( const QVariantMap & map ) const

inlineslot

Low-level API: Send a JSON representation of a variant map to Touch Portal. map should contain one TP message. The map is serialized as QJsonObject type.

Definition at line 300 of file TPClientQt.h.

◆ setConnectionTimeout()

void setConnectionTimeout ( int timeoutMs = 10000 )

Sets the timeout value for the initial pairing 'info' message to be received from Touch Portal, in milliseconds. An error() signal will be sent if connection fails after this period. A timeout of <= 0 will make the client not wait for a successful pair response from TP and will assume it is connected as long as the network socket is open. The default value is 10000 (10s). Call this method with no argument to reset the timeout value to default.

See also: connectionTimeout()

Definition at line 232 of file TPClientQt.cpp.

◆ setHostProperties()

void setHostProperties	(	const QString &	nameOrAddress = `QStringLiteral("127.0.0.1")`,
		uint16_t	port = `12136`
	)

Set the Touch Portal host name/address and port number for connection. nameOrAddress can be a IPv4 dotted address or a host name which will be resolved. Default host is "127.0.0.1" (local computer) and port # 12136 (TP's default for plugin API). Call this method with no arguments to reset both properties to their defaults. Changing these settings when already connected to TP has no effect until the next connection attempt.

See also: hostName(), hostPort()

Definition at line 224 of file TPClientQt.cpp.

◆ setPluginId()

bool setPluginId ( const char * pluginId )

Alternate way to set or change the plugin ID. This cannot be changed when connected to TP. Returns false if that is attempted or if pluginId is null or empty.

Definition at line 210 of file TPClientQt.cpp.

◆ settingUpdate() [1/4]

void settingUpdate	(	const char *	name,
		const char *	value
	)		const

inline

Update a plugin setting value with given name to value.

Definition at line 605 of file TPClientQt.h.

◆ settingUpdate [2/4]

void settingUpdate	(	const QByteArray &	name,
		const QByteArray &	value
	)		const

inlineslot

Update a plugin setting value with given name to value.

Definition at line 390 of file TPClientQt.h.

◆ settingUpdate() [3/4]

void settingUpdate	(	const std::string &	name,
		const std::string &	value
	)		const

inline

Update a plugin setting value with given name to value.

Definition at line 245 of file TPClientQt.h.

◆ settingUpdate [4/4]

void settingUpdate	(	QStringView	name,
		QStringView	value
	)		const

inlineslot

Update a plugin setting value with given name to value.

Definition at line 392 of file TPClientQt.h.

◆ showNotification() [1/10]

void showNotification	(	const char *	notificationId,
		const char *	title,
		const char *	msg,
		const QJsonArray &	options
	)		const

inline

Send a notification message to TP. See TP SDK documentation for details on each field. The options variant list should be some kind of array containing the notification option id and title pairs/objects, for example a ‘QJsonArray<QJsonObject>({'id’, 'title'})`.

Definition at line 615 of file TPClientQt.h.

◆ showNotification() [2/10]

void showNotification	(	const char *	notificationId,
		const char *	title,
		const char *	msg,
		const QVariantList &	options
	)		const

inline

Send a notification message to TP. See TP SDK documentation for details on each field. The options variant list should be some kind of array containing the notification option id and title pairs/objects, for example a ‘QVariantList<QVariantMap>({'id’, 'title'})`.

Definition at line 252 of file TPClientQt.h.

◆ showNotification() [3/10]

void showNotification	(	const char *	notificationId,
		const char *	title,
		const char *	msg,
		const QVector< QPair< const char , const char > > &	options
	)		const

inline

Send a notification message to TP. See TP SDK documentation for details on each field. The options are passed as an array of id/title pairs which are converted to appropriate JSON objects, eg: ‘{'id’: pair.first, 'title': pair.second}`.

Definition at line 627 of file TPClientQt.h.

◆ showNotification() [4/10]

void showNotification	(	const char *	notificationId,
		const char *	title,
		const char *	msg,
		const std::vector< std::pair< const char , const char > > &	options
	)		const

inline

Send a notification message to TP. See TP SDK documentation for details on each field. The options are passed as an array of id/title pairs which are converted to appropriate JSON objects, eg: ‘{'id’: pair.first, 'title': pair.second}`.

Definition at line 633 of file TPClientQt.h.

◆ showNotification [5/10]

void showNotification	(	const QByteArray &	notificationId,
		const QByteArray &	title,
		const QByteArray &	msg,
		const QJsonArray &	options
	)		const

inlineslot

Send a notification message to TP. See TP SDK documentation for details on each field. The options variant list should be some kind of array containing the notification option id and title pairs/objects, for example a ‘QVariantList<QVariantMap({'id’, 'title'})>`.

Definition at line 396 of file TPClientQt.h.

◆ showNotification [6/10]

void showNotification	(	const QByteArray &	notificationId,
		const QByteArray &	title,
		const QByteArray &	msg,
		const QVariantList &	options
	)		const

inlineslot

Send a notification message to TP. See TP SDK documentation for details on each field. The options variant list should be some kind of array containing the notification option id and title pairs/objects, for example a ‘QVariantList<QVariantMap({'id’, 'title'})>`.

Definition at line 399 of file TPClientQt.h.

◆ showNotification [7/10]

void showNotification	(	const QByteArray &	notificationId,
		const QByteArray &	title,
		const QByteArray &	msg,
		const QVector< QPair< QLatin1String, QStringView > > &	options
	)		const

inlineslot

Send a notification message to TP. See TP SDK documentation for details on each field. The options are passed as an array of id/title pairs which are converted to appropriate JSON objects, eg: ‘{'id’: pair.first, 'title': pair.second}`.

Definition at line 644 of file TPClientQt.h.

◆ showNotification() [8/10]

void showNotification	(	const std::string &	notificationId,
		const std::string &	title,
		const std::string &	msg,
		const std::vector< std::pair< std::string, std::string > > &	options
	)		const

inline

Send a notification message to TP. See TP SDK documentation for details on each field. The options are passed as an array of id/title pairs which are converted to appropriate JSON objects, eg: ‘{'id’: pair.first, 'title': pair.second}`.

Definition at line 638 of file TPClientQt.h.

◆ showNotification [9/10]

void showNotification	(	QStringView	notificationId,
		QStringView	title,
		QStringView	msg,
		const QVariantList &	options
	)		const

inlineslot

Send a notification message to TP. See TP SDK documentation for details on each field. The options variant list should be some kind of array containing the notification option id and title pairs/objects, for example a ‘QVariantList<QVariantMap({'id’, 'title'})>`.

Definition at line 402 of file TPClientQt.h.

◆ showNotification [10/10]

void showNotification	(	QStringView	notificationId,
		QStringView	title,
		QStringView	msg,
		const QVector< QPair< QStringView, QStringView > > &	options
	)		const

inlineslot

Send a notification message to TP. See TP SDK documentation for details on each field. The options are passed as an array of id/title pairs which are converted to appropriate JSON objects, eg: ‘{'id’: pair.first, 'title': pair.second}`.

Definition at line 650 of file TPClientQt.h.

◆ socketError()

QAbstractSocket::SocketError socketError ( ) const

Returns the current TCP/IP network socket error, if any.

See also: QAbstractSocket::error()

Definition at line 200 of file TPClientQt.cpp.

◆ socketState()

QAbstractSocket::SocketState socketState ( ) const

Returns the current state of the TCP/IP network socket used to communicate with Touch Portal.

Definition at line 199 of file TPClientQt.cpp.

◆ stateUpdate() [1/3]

void stateUpdate	(	const char *	id,
		const char *	value
	)		const

inline

Send a state update with given id and value strings.

Definition at line 506 of file TPClientQt.h.

◆ stateUpdate [2/3]

void stateUpdate	(	const QByteArray &	id,
		const QByteArray &	value
	)		const

inlineslot

Send a state update with given id and value strings.

Definition at line 311 of file TPClientQt.h.

◆ stateUpdate [3/3]

void stateUpdate	(	QStringView	id,
		QStringView	value
	)		const

inlineslot

Send a state update with given id and value strings.

Definition at line 313 of file TPClientQt.h.

◆ tpInfo()

const TPClientQt::TPInfo & tpInfo ( ) const

Returns information about the currently connected Touch Portal instance. This data is saved from the initial connection's 'info' message.

See also: TPInfo struct.

Note: This reference becomes invalid when connect() is called.

Definition at line 203 of file TPClientQt.cpp.

◆ write

void write ( const QByteArray & data ) const

slot

Low-level API: Write UTF-8 bytes directly to Touch Portal. data should contain one TP message in the form of a serialized (UTF8 text) JSON object. A newline is automatically added after data is sent (as per TP API specs). All messages are ultimately sent via this method.

Definition at line 266 of file TPClientQt.cpp.

The documentation for this class was generated from the following files:

Description

Member Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Slots

Signals

Class Documentation

◆ TPClientQt::ActionDataItem

◆ TPClientQt::TPInfo

Member Enumeration Documentation

◆ MessageType

Constructor & Destructor Documentation

◆ TPClientQt()

Member Function Documentation

◆ actionDataItem()

◆ actionDataToItemArray()

◆ actionDataToMap()

◆ actionDataValue() [1/2]

◆ actionDataValue() [2/2]

◆ choiceUpdate() [1/24]

◆ choiceUpdate() [2/24]

◆ choiceUpdate() [3/24]

◆ choiceUpdate() [4/24]

◆ choiceUpdate() [5/24]

◆ choiceUpdate() [6/24]

◆ choiceUpdate [7/24]

◆ choiceUpdate [8/24]

◆ choiceUpdate [9/24]

◆ choiceUpdate [10/24]

◆ choiceUpdate [11/24]

◆ choiceUpdate [12/24]

◆ choiceUpdate [13/24]

◆ choiceUpdate [14/24]

◆ choiceUpdate() [15/24]

◆ choiceUpdate() [16/24]

◆ choiceUpdate [17/24]

◆ choiceUpdate [18/24]

◆ choiceUpdate [19/24]

◆ choiceUpdate [20/24]

◆ choiceUpdate [21/24]

◆ choiceUpdate [22/24]

◆ choiceUpdate [23/24]

◆ choiceUpdate [24/24]

◆ connect [1/2]

◆ connect [2/2]

◆ connected

◆ connectionTimeout()

◆ connectorUpdate() [1/11]

◆ connectorUpdate() [2/11]

◆ connectorUpdate() [3/11]

◆ connectorUpdate [4/11]

◆ connectorUpdate [5/11]

◆ connectorUpdate [6/11]

◆ connectorUpdate() [7/11]

◆ connectorUpdate() [8/11]

◆ connectorUpdate [9/11]

◆ connectorUpdate [10/11]

◆ connectorUpdate [11/11]

◆ createState() [1/8]

◆ createState() [2/8]

◆ createState [3/8]

◆ createState [4/8]

◆ createState() [5/8]

◆ createState() [6/8]

◆ createState [7/8]

◆ createState [8/8]

◆ disconnect

◆ disconnected

◆ encode()

◆ error

◆ errorString()

◆ hostName()

◆ hostPort()

◆ isConnected()

◆ message

◆ pluginId()

◆ removeState() [1/4]

◆ removeState [2/4]

◆ removeState() [3/4]