How to handle all the core AppleEvents

Glancing through the APIs, SwiftUI can handle the open app, reopen app, open doc, and quit core events (with the “aevt” suite ID). What about the print doc and open content events? If there are no hooks (yet), how can I implement them the traditional way without clashing with SwiftUI?

Answered by DTS Engineer in 888115022

You're right that SwiftUI covers oapp/rapp/odoc/quit natively, plus GURL via the .onOpenURL modifier. For the events you're asking about:

Open content — could you clarify which event you mean? If you're thinking of GURL (Open URL / "open this URL or content"), that's the onOpenURL path. If you mean something else (a custom ocon or app-specific event), let me know and I can answer specifically.

Print document (pdoc) — SwiftUI does not route this to NSApplicationDelegate.application(_:printFiles:withSettings:showPrintPanels:). I verified by sending osascript -e 'tell application "Test" to print POSIX file "..."' to test apps using both WindowGroup and DocumentGroup in macOS 26.4 — the delegate method never fired. So the standard delegate path is silent under SwiftUI.

The path that does work is registering directly with NSAppleEventManager. Install your handler in applicationWillFinishLaunching: (before any events arrive) and SwiftUI doesn't fight you for ownership:

@main
struct MyApp: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    var body: some Scene {
        WindowGroup {  // or DocumentGroup
            ContentView()
        }
    }
}

class AppDelegate: NSObject, NSApplicationDelegate {
    func applicationWillFinishLaunching(_ notification: Notification) {
        NSAppleEventManager.shared().setEventHandler(
            self,
            andSelector: #selector(handlePrintEvent(_:replyEvent:)),
            forEventClass: AEEventClass(kCoreEventClass),
            andEventID: AEEventID(kAEPrintDocuments)
        )
    }

    @objc func handlePrintEvent(_ event: NSAppleEventDescriptor,
                                 replyEvent: NSAppleEventDescriptor) {
        // The direct object parameter holds the file(s) or document specifier:
        // event.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))
        // …
    }
}

In the test, this handler received the event with the file URL properly extracted in the '----' (direct object) parameter — exactly what a traditional AppleEvent handler expects.

On the "without clashing with SwiftUI" concern: AppleEvent handlers register for specific (event class, event ID) pairs. Registering for aevt/pdoc doesn't conflict with the handlers SwiftUI installs for aevt/oapp, aevt/rapp, aevt/odoc, or aevt/quit — they're keyed on the 4-char codes and live separately. The same pattern works for any other event you want to handle traditionally: open content, application-specific events, custom suites, or anything not in the small set SwiftUI claims for itself.

If your "open content" event turns out to be one of those non-SwiftUI events, the same setEventHandler(..., forEventClass:andEventID:) approach will work — just substitute the right class and ID codes.

You're right that SwiftUI covers oapp/rapp/odoc/quit natively, plus GURL via the .onOpenURL modifier. For the events you're asking about:

Open content — could you clarify which event you mean? If you're thinking of GURL (Open URL / "open this URL or content"), that's the onOpenURL path. If you mean something else (a custom ocon or app-specific event), let me know and I can answer specifically.

Print document (pdoc) — SwiftUI does not route this to NSApplicationDelegate.application(_:printFiles:withSettings:showPrintPanels:). I verified by sending osascript -e 'tell application "Test" to print POSIX file "..."' to test apps using both WindowGroup and DocumentGroup in macOS 26.4 — the delegate method never fired. So the standard delegate path is silent under SwiftUI.

The path that does work is registering directly with NSAppleEventManager. Install your handler in applicationWillFinishLaunching: (before any events arrive) and SwiftUI doesn't fight you for ownership:

@main
struct MyApp: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    var body: some Scene {
        WindowGroup {  // or DocumentGroup
            ContentView()
        }
    }
}

class AppDelegate: NSObject, NSApplicationDelegate {
    func applicationWillFinishLaunching(_ notification: Notification) {
        NSAppleEventManager.shared().setEventHandler(
            self,
            andSelector: #selector(handlePrintEvent(_:replyEvent:)),
            forEventClass: AEEventClass(kCoreEventClass),
            andEventID: AEEventID(kAEPrintDocuments)
        )
    }

    @objc func handlePrintEvent(_ event: NSAppleEventDescriptor,
                                 replyEvent: NSAppleEventDescriptor) {
        // The direct object parameter holds the file(s) or document specifier:
        // event.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))
        // …
    }
}

In the test, this handler received the event with the file URL properly extracted in the '----' (direct object) parameter — exactly what a traditional AppleEvent handler expects.

On the "without clashing with SwiftUI" concern: AppleEvent handlers register for specific (event class, event ID) pairs. Registering for aevt/pdoc doesn't conflict with the handlers SwiftUI installs for aevt/oapp, aevt/rapp, aevt/odoc, or aevt/quit — they're keyed on the 4-char codes and live separately. The same pattern works for any other event you want to handle traditionally: open content, application-specific events, custom suites, or anything not in the small set SwiftUI claims for itself.

If your "open content" event turns out to be one of those non-SwiftUI events, the same setEventHandler(..., forEventClass:andEventID:) approach will work — just substitute the right class and ID codes.

An update to my earlier reply: in macOS 27.0.1, SwiftUI apps call application(_:printFiles:withSettings:showPrintPanels:). I retested with an AppKit app as a control, which my earlier test didn't have. SwiftUI apps that use WindowGroup and DocumentGroup both called it for the print documents event, as the AppKit app did. So you can handle print in the delegate you provide through NSApplicationDelegateAdaptor, without installing a handler. I haven't retested in macOS 26, so if your app supports it, check the delegate method there. If you installed a print handler following my earlier reply, you can remove it and implement the delegate method instead. The other delegate methods I tested are in How/where do SwiftUI "App" objects handle AppleEvents.

On your follow-up questions:

  • Open contents: SwiftUI apps have an aevt/ocon handler without your adding one. All three test apps, including the AppKit one, had handlers installed for oapp, rapp, odoc, pdoc, ocon, quit, and GURL. Sending each app ocon with text returned -1708, errAEEventNotHandled. To use dropped content, install your own handler with NSAppleEventManager in applicationWillFinishLaunching(_:). In the SwiftUI test app, a handler installed there received the text. Your handler replaces the installed one: the setEventHandler(_:andSelector:forEventClass:andEventID:) documentation says it removes any handler already registered for that event.
  • URL schemes: The onOpenURL(perform:) documentation describes its action as called "when your app receives a Universal Link or a custom URL." In my test, onOpenURL also received an ftp URL, the same way it received a custom-scheme URL. Declare each scheme in CFBundleURLTypes, which the documentation describes as "A list of URL schemes (http, ftp, and so on) supported by the app." Declaring ftp didn't make my test app the default handler. Finder remained the default, so I delivered the URL by opening it with the test app. To change the default, use setDefaultApplication(at:toOpenURLsWithScheme:completion:). Its documentation says the system asks for consent if the change requires it.