This document is aimed at developers of Qt client applications that utilise Qt touch events.
Qt is a cross platform Integrated development Environment (IDE) for Windows, macOS and Linux.
The Qt API includes a QTouchEvents API to respond to touch events that work as standard in Windows, but not in macOS.
To overcome this issue, we have created a Qt plugin.
The UPDDTouch Qt plugin allows any touch-enabled Qt application to receive multitouch events on macOS from a UPDD supported touch device.
By simply adding in the plugin, the touch events work the same as they do on Windows. Except for a small code change to load the plugin, no other source code changes to the app should be required.
To use it with your application, make sure the compiled plugin is included in your app's Qt plugin directory, in a subfolder named "generic". Where the Qt plugin directory is varies from one Qt application to another and depends on how it is deployed. See the following Qt documents for more information:
https://doc.qt.io/qt-6/deployment-plugins.html
https://doc.qt.io/qt-6/macos-deployment.html#qt-plugins
The version of the plugin used must not only match the Qt version in both its major and minor version but use the same Qt dynamic libraries as the host application. For example, an application built with Qt 5.12 must use a Qt 5.12 version of the plugin. Most Qt applications for macOS link to Qt's frameworks in a standard way, particularly if they are prepared for release using Qt's macdeployqt tool. In this case, the pre-built plugins provided by Touch-Base ** should work without any alteration. You can install it into your Qt installation's plugin directory for use during development, and then copy the plugin into your application bundle when deploying, into the Contents/PlugIns/generic subdirectory.
If you are building your own version of Qt, statically linking to Qt, or not linking to Qt's frameworks in the same manner as is set up by macdeployqt, then you may need to build your own copy of the UPDDTouch plugin to use it. To this end the source code is provided here. It should compile in any version of Qt 5 or 6.
When utilising a version of the QT Plugin that is compatible with Qt5 and therefore will be using the UPDD driver's V6 API it is important that the file libupddapi.1.0.0.dylib resides in folder
/Library/Application Support/UPDD.
If using UPDD V6, this file will be part of the software. If using UPDD V7, either request that the driver is supplied with 'V6 components' or download the file from the link above.
To load the plugin when your app runs, it can either be done by specifying a command line option to the application when launched, e.g.:
/Applications/MyQtApplication.app/Contents/MacOS/MyQtApplication -plugin UPDDTouch ...or you can make a simple code alteration to your app so that the plugin is always loaded. To do so, simply add this code before you instantiate QApplication in your application's main function (or wherever suitable):
QByteArray prevValue = qgetenv("QT_QPA_GENERIC_PLUGINS");
if (prevValue.isEmpty()) {
qputenv("QT_QPA_GENERIC_PLUGINS", "UPDDTouch");
} else {
qputenv("QT_QPA_GENERIC_PLUGINS", prevValue + QByteArray(",UPDDTouch"));
}
You can also statically link the plugin into your application, which means that it isn't necessary to include the plugin's dynamic library when deploying the app.
See this Qt document for more information: https://doc.qt.io/qt-6/plugins-howto.html#static-plugins
** - If required, please request from support@touch-base.com stating Qt version in use.
This Qt plugin has been build for specific applications as documented below:
Vista Lighting and Media Control Software
Configuring QT apps in UPDD commander
When using UPDD Commander, it's necessary to configure it to send touches to the Qt application that uses the Qt Plugin, so that the plugin can receive them and send them into the application. To do so, click the + button underneath of UPDD Commander's list of applications and pick the menu "Add New Application..." Select your Qt app to add it to the list, and then make the following two changes to it:
1. Click the + button under the list of gestures and select the menu All Touches > Pass all touches to UPDD client app. This special gesture configures UPDD Commander to pass any touches that occur within the application directly to that application, skipping gesture processing.
2. With the Qt application selected in the lefthand list, click the gear icon below the application list, and then check the box "Inherit UI element gestures before [app name] gestures". This will allow touches that fall within any UI elements configured under "Default Gestures" to continue working as before, such as menus, window title bars, and system file dialogs. This is important because these UI elements will not respond to Qt touch events, so when the user touches them, UPDD Commander will need to process gestures and produce mouse clicks that can interact with them.
In this example, this is set for the Qt application Vista 3: