macOS: Document the various open-file-or-url callbacks in our app delegate

Pick-to: 6.10
Change-Id: I30a8a4b04f8b2bb40090ab810a5f84de0bd78ba4
Reviewed-by: Volker Hilsheimer <[email protected]>

1 files changed, 61 insertions, 0 deletions

diff --git a/src/plugins/platforms/cocoa/qcocoaapplicationdelegate.mm b/src/plugins/platforms/cocoa/qcocoaapplicationdelegate.mm
index 95ee26a343e..7ca3e61dfa5 100644
--- a/src/plugins/platforms/cocoa/qcocoaapplicationdelegate.mm
+++ b/src/plugins/platforms/cocoa/qcocoaapplicationdelegate.mm
@@ -196,6 +196,23 @@ QT_USE_NAMESPACE
     QCocoaMenuBar::insertWindowMenu();
 }
 
+/*!
+    Tells the delegate to open the specified files
+
+    Sent by the system when the user drags a file to the app's icon
+    in places like Finder or the Dock, or opens a file via the "Open
+    With" menu in Finder.
+
+    These actions can happen when the application is not running,
+    in which case the call comes in between willFinishLaunching
+    and didFinishLaunching. In this case we don't pass on the
+    incoming file paths as file open events, as the paths are
+    also part of the command line arguments, and Qt applications
+    normally expect to handle file opening via those.
+
+    \note The app must register itself as a handler for each file
+    type via the CFBundleDocumentTypes key in the Info.plist.
+ */
 - (void)application:(NSApplication *)sender openFiles:(NSArray *)filenames
 {
     Q_UNUSED(filenames);
@@ -213,6 +230,8 @@ QT_USE_NAMESPACE
         }
         QUrl url = qt_apple_urlFromPossiblySecurityScopedURL([NSURL fileURLWithPath:fileName]);
         QWindowSystemInterface::handleFileOpenEvent(url);
+        // FIXME: We're supposed to call [NSApp replyToOpenOrPrint:] here, but we
+        //  don't know if the open operation succeeded, failed, or was cancelled.
     }
 
     if ([reflectionDelegate respondsToSelector:_cmd])
@@ -265,6 +284,17 @@ QT_USE_NAMESPACE
     }
 }
 
+/*!
+    Returns a Boolean value that indicates if the app responds
+    to reopen AppleEvents.
+
+    These events are sent whenever the Finder reactivates an already
+    running application because someone double-clicked it again or used
+    the dock to activate it.
+
+    We pass the activation on to Qt, and return YES, to let AppKit
+    follow its normal flow.
+ */
 - (BOOL)applicationShouldHandleReopen:(NSApplication *)theApplication hasVisibleWindows:(BOOL)flag
 {
     if ([reflectionDelegate respondsToSelector:_cmd])
@@ -312,6 +342,25 @@ QT_USE_NAMESPACE
         [self doesNotRecognizeSelector:invocationSelector];
 }
 
+/*!
+    Callback for when the application is asked to pick up a user activity
+    from another app (also known as Handoff, which is part of the bigger
+    Continuity story for Apple operating systems).
+
+    This is normally managed by two apps by the same vendor explicitly
+    initiating a custom NSUserActivity and picking it up in another app
+    on the same or another device, which we don't have APIs for.
+
+    This is also how the system supports Universal Links, where a web page
+    can deep-link into an app. In this case the app needs to claim and
+    validate an associated domain. The resulting link will be delivered
+    as a special NSUserActivityTypeBrowsingWeb activity type, which we
+    treat as QDesktopServices::handleUrl().
+
+    Finally, for NS/UIDocument based apps (which Qt is not), the system
+    automatically handles document hand-off if the application includes
+    the NSUbiquitousDocumentUserActivityType key in its Info.plist.
+ */
 - (BOOL)application:(NSApplication *)application continueUserActivity:(NSUserActivity *)userActivity
           restorationHandler:(void(^)(NSArray<id<NSUserActivityRestoring>> *restorableObjects))restorationHandler
 {
@@ -334,6 +383,18 @@ QT_USE_NAMESPACE
     return NO;
 }
 
+/*!
+    Callback for when the app is asked to open custom URL schemes.
+
+    We register a handler for events of type kInternetEventClass with the
+    NSAppleEventManager during application start.
+
+    The application must include the schemes in the CFBundleURLTypes
+    key of the Info.plist.
+
+    \note This callback is not used for http/https URLs, see
+    continueUserActivity above for how we handle that.
+ */
 - (void)getUrl:(NSAppleEventDescriptor *)event withReplyEvent:(NSAppleEventDescriptor *)replyEvent
 {
     Q_UNUSED(replyEvent);