Add platform channel exit support.

Author: gspencergoog

lib/ui/platform_dispatcher.dart

@@ -1733,6 +1733,42 @@ enum AppLifecycleState {
   detached,
 }
 
+/// The possible responses to a request to exit the application.
+///
+/// The request is typically responded to by a [WidgetsBindingObserver].
+// TODO(gspencergoog): Insert references here to AppLifecycleListener and to the
+// actual function called on WidgetsBindingObserver once those have landed in
+// the framework.
+enum AppExitResponse {
+  /// Exiting the application can proceed.
+  exit,
+  /// Cancel the exit: do not exit the application.
+  cancel,
+}
+
+/// The type of application exit to perform when calling
+/// `ServicesBinding.exitApplication`.
+// TODO(gspencergoog): Insert references here to ServicesBinding.exitApplication
+// that has landed in the framework.
+enum AppExitType {
+  /// Requests that the application start an orderly exit, sending a request
+  /// back to the framework through the [WidgetsBinding], and if that responds
+  /// with [AppExitResponse.exit], then proceed with the same steps as a
+  /// [required] exit. if that responds with [AppExitResponse.cancel], then the
+  /// exit request is canceled and the application continues executing normally.
+  cancelable,
+
+  /// A non-cancelable orderly exit request. The engine will shut down the
+  /// engine and call the native UI toolkit's exit API.
+  ///
+  /// If you need an even faster and more dangerous exit, then call `dart:io`'s
+  /// `exit()` directly, and even the native toolkit's exit API won't be called.
+  /// This is quite dangerous, though, since it's possible that the engine will
+  /// crash because it hasn't been properly shut down, causing the app to crash
+  /// on exit.
+  required,
+}
+
 /// A representation of distances for each of the four edges of a rectangle,
 /// used to encode the view insets and padding that applications should place
 /// around their user interface, as exposed by [FlutterView.viewInsets] and

lib/web_ui/lib/platform_dispatcher.dart

@@ -374,6 +374,16 @@ enum AppLifecycleState {
   detached,
 }
 
+enum AppExitResponse {
+  exit,
+  cancel,
+}
+
+enum AppExitType {
+  cancelable,
+  required,
+}
+
 abstract class ViewPadding {
   const factory ViewPadding._(
       {required double left,

shell/platform/darwin/macos/BUILD.gn

@@ -38,6 +38,7 @@ _framework_binary_subpath = "Versions/A/$_flutter_framework_name"
 # the Flutter engine source root.
 _flutter_framework_headers = [
   "framework/Headers/FlutterAppDelegate.h",
+  "framework/Headers/FlutterApplication.h",
   "framework/Headers/FlutterDartProject.h",
   "framework/Headers/FlutterEngine.h",
   "framework/Headers/FlutterMacOS.h",
@@ -57,6 +58,7 @@ source_set("flutter_framework_source") {
     "framework/Source/AccessibilityBridgeMac.h",
     "framework/Source/AccessibilityBridgeMac.mm",
     "framework/Source/FlutterAppDelegate.mm",
+    "framework/Source/FlutterApplication.mm",
     "framework/Source/FlutterBackingStore.h",
     "framework/Source/FlutterBackingStore.mm",
     "framework/Source/FlutterChannelKeyResponder.h",

shell/platform/darwin/macos/framework/Headers/FlutterApplication.h

@@ -0,0 +1,54 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef FLUTTER_FLUTTERAPPLICATION_H_
+#define FLUTTER_FLUTTERAPPLICATION_H_
+
+#import <Cocoa/Cocoa.h>
+
+/**
+ * A Flutter-specific subclass of NSApplication that overrides |terminate| and
+ * provides an addition |terminateApplication| method so that Flutter can handle
+ * requests for termination in an asynchronous fashion.
+ *
+ * When a call to |terminate| comes in, either from the OS through a Quit menu
+ * item, through the Quit item in the dock context menu, or from the application
+ * itself, a request is sent to the Flutter framework. If that request is
+ * granted, this subclass will (in |terminateApplication|) call
+ * |NSApplication|'s version of |terminate| to proceed with terminating the
+ * application normally by calling |applicationShouldTerminate|, etc.
+ *
+ * If the termination request is denied by the framework, then the application
+ * will continue to execute normally, as if no |terminate| call were made.
+ *
+ * The |FlutterAppDelegate| always returns |NSTerminateNow| from
+ * |applicationShouldTerminate|, since it has already decided by that point that
+ * it should terminate.
+ *
+ * In order for this class to be used in place of |NSApplication|, the
+ * "NSPrincipalClass" entry in the Info.plist for the application must be set to
+ * "FlutterApplication". If it is not, then the application will not be given
+ * the chance to deny a termination request, and calls to requestAppExit on the
+ * engine (from the framework, typically) will simply exit the application
+ * without ceremony.
+ *
+ * If the |NSApp| global isn't of type |FlutterApplication|, a log message will
+ * be printed once in debug mode when the application is first accessed through
+ * the singleton's |sharedApplication|, describing how to fix this.
+ */
+@interface FlutterApplication : NSApplication
+
+/**
+ * FlutterApplication's implementation of |terminate| doesn't terminate the
+ * application: that is left up to the engine, which will call this function if
+ * it decides that termination request is granted, which will start the regular
+ * Cocoa flow for terminating the application, calling
+ * |applicationShouldTermnate|, etc.
+ *
+ * @param(sender) The id of the object requesting the termination, or nil.
+ */
+- (void)terminateApplication:(id)sender;
+@end
+
+#endif  // FLUTTER_FLUTTERAPPLICATION_H_

shell/platform/darwin/macos/framework/Headers/FlutterMacOS.h

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 #import "FlutterAppDelegate.h"
+#import "FlutterApplication.h"
 #import "FlutterBinaryMessenger.h"
 #import "FlutterChannels.h"
 #import "FlutterCodecs.h"

shell/platform/darwin/macos/framework/Source/FlutterAppDelegate.mm

@@ -3,6 +3,10 @@
 // found in the LICENSE file.
 
 #import "flutter/shell/platform/darwin/macos/framework/Headers/FlutterAppDelegate.h"
+#include <AppKit/AppKit.h>
+#import "flutter/fml/logging.h"
+#import "flutter/shell/platform/darwin/macos/framework/Source/FlutterAppDelegate_internal.h"
+#import "flutter/shell/platform/embedder/embedder.h"
 
 @interface FlutterAppDelegate ()
 
@@ -13,10 +17,16 @@ - (NSString*)applicationName;
 
 @end
 
-@implementation FlutterAppDelegate
+@implementation FlutterAppDelegate {
+  FlutterEngineTerminationHandler* _terminationHandler;
+}
 
-// TODO(stuartmorgan): Implement application lifecycle forwarding to plugins here, as is done
-// on iOS. Currently macOS plugins don't have access to lifecycle messages.
+- (instancetype)init {
+  if (self = [super init]) {
+    _terminationHandler = nil;
+  }
+  return self;
+}
 
 - (void)applicationWillFinishLaunching:(NSNotification*)notification {
   // Update UI elements to match the application name.
@@ -28,6 +38,13 @@ - (void)applicationWillFinishLaunching:(NSNotification*)notification {
   }
 }
 
+// This always returns NSTerminateNow, since by the time we get here, the
+// application has already been asked if it should terminate or not, and if not,
+// then termination never gets this far.
+- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication*)sender {
+  return NSTerminateNow;
+}
+
 #pragma mark Private Methods
 
 - (NSString*)applicationName {
@@ -39,4 +56,17 @@ - (NSString*)applicationName {
   return applicationName;
 }
 
+- (void)setTerminationRequestHandler:(FlutterEngineTerminationHandler*)handler {
+  _terminationHandler = handler;
+}
+
+- (void)tryToTerminateApplication:(FlutterApplication*)application
+                         exitType:(FlutterAppExitType)type {
+  if (_terminationHandler) {
+    [_terminationHandler tryToTerminateApplication:application exitType:type result:nil];
+  } else {
+    [application terminateApplication:application];
+  }
+}
+
 @end

shell/platform/darwin/macos/framework/Source/FlutterAppDelegate_internal.h

@@ -0,0 +1,25 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef FLUTTER_FLUTTERAPPDELEGATE_INTERNAL_H_
+#define FLUTTER_FLUTTERAPPDELEGATE_INTERNAL_H_
+
+#include "embedder.h"
+#import "flutter/shell/platform/darwin/macos/framework/Headers/FlutterAppDelegate.h"
+#import "flutter/shell/platform/darwin/macos/framework/Source/FlutterEngine_Internal.h"
+
+@interface FlutterAppDelegate ()
+/**
+ * Allows the engine to add a handler for termination requests
+ */
+- (void)setTerminationRequestHandler:(FlutterEngineTerminationHandler*)handler;
+
+/**
+ * Allows the delegate to respond to an attempt to terminate the application.
+ */
+- (void)tryToTerminateApplication:(FlutterApplication*)application
+                         exitType:(FlutterAppExitType)type;
+@end
+
+#endif  // FLUTTER_FLUTTERAPPDELEGATE_INTERNAL_H_

shell/platform/darwin/macos/framework/Source/FlutterApplication.mm

@@ -0,0 +1,86 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#import "flutter/shell/platform/darwin/macos/framework/Headers/FlutterApplication.h"
+#include "embedder.h"
+#include "shell/platform/darwin/macos/framework/Headers/FlutterAppDelegate.h"
+#include "shell/platform/darwin/macos/framework/Source/FlutterAppDelegate_internal.h"
+
+#ifndef FLUTTER_RELEASE
+namespace {
+static bool warned_about_flutter_application = false;
+}  // namespace
+#endif  // !FLUTTER_RELEASE
+
+// An NSApplication subclass that implements overrides necessary for some
+// Flutter features, like application lifecycle handling.
+@interface FlutterApplication () {
+}
+@end
+
+@implementation FlutterApplication
+
+// Initialize NSApplication using the custom subclass.  Check whether NSApp was
+// already initialized using another class, because that would break some
+// things. Warn about the mismatch only once, and only in debug builds.
++ (NSApplication*)sharedApplication {
+  NSApplication* app = [super sharedApplication];
+
+  // +sharedApplication initializes the global NSApp, so if we're delivering
+  // something other than a FlutterApplication, warn the developer once.
+#ifndef FLUTTER_RELEASE
+  if (!warned_about_flutter_application && ![NSApp isKindOfClass:self]) {
+    NSLog(@"NSApp should be of type %s, not %s. "
+           "Some application lifecycle requests (e.g. ServicesBinding.exitApplication) "
+           "and notifications will be unavailable.\n"
+           "Modify the application's NSPrincipleClass to be %s"
+           "in the Info.plist to fix this.",
+          [[self className] UTF8String], [[NSApp className] UTF8String],
+          [[self className] UTF8String]);
+    warned_about_flutter_application = true;
+  }
+#endif  // !FLUTTER_RELEASE
+  return app;
+}
+
+// |terminate| is the entry point for orderly "quit" operations in Cocoa. This
+// includes the application menu's Quit menu item and keyboard equivalent, the
+// application's dock icon menu's Quit menu item, "quit" (not "force quit") in
+// the Activity Monitor, and quits triggered by user logout and system restart
+// and shutdown.
+//
+// We override the normal |terminate| implementation. Our implementation, which
+// is specific to the asyncronous nature of Flutter, works by asking the
+// application delegate to terminate using its |tryToTerminateApplication|
+// method instead of going through |applicationShouldTerminate|.
+//
+// The standard |applicationShouldTerminate| is not used because returning
+// NSTerminateLater from that function moves the run loop into a modal dialog
+// mode (NSModalPanelRunLoopMode), which stops the main run loop from processing
+// messages like, for instance, the response to the method channel call, and
+// code paths leading to it must be redirected to |tryToTerminateApplication|.
+//
+// |tryToTerminateApplication| differs from the standard
+// |applicationShouldTerminate| in that no special event loop is run in the case
+// that immediate termination is not possible (e.g., if dialog boxes allowing
+// the user to cancel have to be shown, or data needs to be saved). Instead,
+// tryToTerminateApplication sends a method channel call to the framework asking
+// it if it is OK to terminate. When that method channel call returns with a
+// result, the application either terminates or continues running.
+- (void)terminate:(id)sender {
+  FlutterAppDelegate* appDelegate = static_cast<FlutterAppDelegate*>([NSApp delegate]);
+
+  [appDelegate tryToTerminateApplication:self exitType:kFlutterAppExitTypeCancelable];
+  // Return, don't exit. The application delegate is responsible for exiting on
+  // its own by calling |-terminateApplication|.
+}
+
+// Starts the regular Cocoa application termination flow, so that plugins will
+// get the appropriate notifications after the application has already decided
+// to quit. This is called after the application has decided that
+// it's OK to terminate.
+- (void)terminateApplication:(id)sender {
+  [super terminate:sender];
+}
+@end