japlscript / japlse

Java API for AppleScript System Events

JaplSE

JaplSE is a Java API for the AppleScript System Events based on JaplScript.

Installation

JaplSE is released via Maven. You can install it via the following dependency:

<dependency>
    <groupId>com.tagtraum</groupId>
    <artifactId>japlse</artifactId>
</dependency>

The Maven artifacts also contain sources and javadocs.

If you are using modules, its name is tagtraum.japlse.

Usage

To use the generated code, do something like this:

import com.tagtraum.macos.systemevents.Application;

public class SendKeyStroke {

    public static void main(final String[] args) {
        final Application application = Application.getInstance();
        // send keystroke with no modifiers
        // to the frontmost app window
        application.keystroke("e", null);
    }
}

Or this:

import com.tagtraum.macos.systemevents.Application;

public class GetDownloadsFolder {

    public static void main(final String[] args) {
        final Application application = Application.getInstance();
        final String downloadsFolder = application.getDownloadsFolder().getPosixPath();
        System.out.println("Downloads folder: " + downloadsFolder);
    }
}

API

You can find the complete API here.

AppleScript Sandbox

Since macOS 10.14 (Mojave), Apple imposed a sandbox on AppleScript. Therefore you may see dialog boxes requesting authorization to perform certain actions. After a while, these boxes simply disappear and there does not seem to be an easy way to authorize your app. In this case, you need to open the system preferences, navigate to Security & Privacy, Privacy, and then Automation, and make sure your app is allowed to remote control whatever app you are trying to remote control (see also this article).

If you are shipping a real app with a UI and not just a command line tool, you need to customize the sandbox permission dialog. You can do so by adding the key NSAppleEventsUsageDescription to your app bundle's /Contents/Info.plist file. For example:

[...]
<key>NSAppleEventsUsageDescription</key>
<string>SuperMusic uses AppleEvents to access your Music.app library,
        e.g., to set BPM values or create playlists.</string>
[...]

Apple's documentation for the keyword is here.