JUCE is an open-source cross-platform framework for developing applications and plug-ins, especially for DAW applications. While it has built-in support for multi-touch on operating systems that have native touch support, such as Windows or iOS, it doesn't currently support multi-touch on macOS. Consequently, we've made an addition to JUCE that implements multi-touch on macOS for systems that have installed the UPDD and submitted it as a pull request to the JUCE GitHub repository. We hope that the JUCE development team will eventually incorporate these changes into the library officially.
In the mean time, it's fairly simple for a JUCE developer to include these changes in their application or plug-in. All that's necessary is changing a few files in JUCE's source code. This can be done by applying a patchfile to your local JUCE installation, or by checking out the pull request from the JUCE GitHub repository.
Afterwards, if you're running UPDD Commander, you'll need to configure it to skip gesture processing for touches that fall within your application and instead pass the touches along directly.
Obtaining the code changes
Option 1: Applying the patchfile
- Download and unzip the patchfile from here
- Move it into the root of your JUCE directory. This is the directory that contains the "modules" subdirectory.
- In a terminal window, change the current directory to your JUCE directory and then apply the patch:
cd /path/to/your/JUCE
patch -p1 < updd-multitouch.patch
- Clean and do a full rebuild of your project
Option 2: Checking out the pull request
If you've installed JUCE from its official git repository, you can check out Touch-Base's pull request into a separate branch by executing the following terminal commands:
cd /path/to/your/JUCE
git fetch origin pull/1382/head:updd-multitouch
git checkout updd-multitouch
Afterwards, perform a clean and full rebuild of your project.
Option 3: Applying the changes manually
The latest changes to JUCE can be obtained from Touch-Base's fork of the repo, in the updd-multitouch branch, available here: https://github.com/Touch-Base-Ltd/JUCE/tree/updd-multitouch
These changes include modifications to two existing JUCE source files, and the addition of two new source files. The two modified files are:
modules/juce_gui_basics/juce_gui_basics.cpp
modules/juce_gui_basics/native/juce_NSViewComponentPeer_mac.mm
The two new files are:
modules/juce_gui_basics/native/juce_UPDDMultitouch_mac.mm
modules/juce_gui_basics/native/juce_UPDDMultitouch_upddapi.h
At the time of this writing (8th May 2024), these files are based off of the latest commit to JUCE's develop branch, commit eac95d59. If your JUCE source tree is based off of that commit or the above two modified source files are compatible with it, then you can copy these four files into your JUCE source tree, or copy in the two new files and manually edit in the changes to the two modified files manually. We recommend applying the patch file, though, since it should only apply in cases where the affected code has not been changed in a later commit.
Hardened Runtime and App Sandbox
Because connecting to the UPDD requires both loading a third party library and establishing an inter-process connection, in order for multi-touch to work in a JUCE application, it needs to grant itself certain permissions if Hardened Runtime or App Sandbox are enabled.
With App Sandbox enabled, be sure to grant your application permission for "Outgoing Connections (Client)" so that the app can connect to the UPDD.
With Hardened Runtime enabled, grant your application the runtime exception "Disable Library Validation" so that it can load functions from the UPDD API dynamic library.
Configuring UPDD Commander
When using UPDD Commander, it's necessary to configure it to send
touches to your JUCE application or plug-in, so that it can process them directly. Currently this must be done manually, but we hope in the future to make this sort of configuration unnecessary by
having UPDD Commander automatically detect UPDD clients, including
plug-ins running in a host DAW application.
JUCE standalone applications
For a standalone application, configuring UPDD Commander to send touches to it is fairly simple. Click the + button underneath of UPDD Commander's list of applications
and pick the menu "Add New Application..." Select your application 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 your JUCE 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 JUCE touch events, so when the user touches them, UPDD
Commander will need to process gestures and produce mouse clicks that
can interact with them.
JUCE plug-ins, such as VST3 or AU plug-ins:
When a JUCE plug-in is running inside another application, such as Logic Pro or Pro Tools, it can be trickier to set it up so that it will receive direct touches without interrupting touch functionality in the host application. Generally a host application will still need UPDD Commander to process its touches and convert them into mouse clicks, keyboard presses, and scrolling.
Each host application will have different requirements, but the general method is to add the host application to UPDD Commander, and then add a new UI element to it that will match the window that contains the UI for your JUCE plug-in.
To do so, add the host application to UPDD Commander using the + button below the list of applications, select your application after it's added, and then use the + button again to add a new UI element to the host application. Set it to "Specific UI element":
Then click the "Select UI Element" button, and move the mouse cursor over the window that contains your plug-in's UI. It should hopefully highlight just the area for your plug-in. (This may not work in certain applications, though it has been tested in Logic Pro and Pro Tools.)
Press the return key to select that UI element, and then click OK in the dialog box for adding a UI element. Now that the UI element has been added, give it a descriptive name (such as "MyPlugin window") and then give it a single gesture: click the + button beneath the list of gestures and select "All touches" > "Pass all touches to UPDD client app".
