Add support for application exit requests (flutter#121378)

gspencergoog · web-flow · commit bcdab118ba6e · 2023-03-17T15:35:55.000Z
Add support for application exit requests
diff --git a/dev/benchmarks/complex_layout/macos/Runner/Info.plist b/dev/benchmarks/complex_layout/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/dev/benchmarks/macrobenchmarks/macos/Runner/Info.plist b/dev/benchmarks/macrobenchmarks/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/dev/integration_tests/channels/macos/Runner/Info.plist b/dev/integration_tests/channels/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/dev/integration_tests/flavors/macos/Runner/Info.plist b/dev/integration_tests/flavors/macos/Runner/Info.plist
@@ -29,6 +29,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/dev/integration_tests/flutter_gallery/macos/Runner/Info.plist b/dev/integration_tests/flutter_gallery/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/dev/integration_tests/ui/macos/Runner/Info.plist b/dev/integration_tests/ui/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/dev/manual_tests/macos/Runner/Info.plist b/dev/manual_tests/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/examples/api/lib/services/binding/handle_request_app_exit.0.dart b/examples/api/lib/services/binding/handle_request_app_exit.0.dart
@@ -0,0 +1,110 @@
+// Copyright 2014 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 'dart:ui';
+
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+
+/// Flutter code sample for [ServicesBinding.handleRequestAppExit].
+
+void main() {
+  runApp(const ApplicationExitExample());
+}
+
+class ApplicationExitExample extends StatelessWidget {
+  const ApplicationExitExample({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return const MaterialApp(
+      home: Scaffold(body: Body()),
+    );
+  }
+}
+
+class Body extends StatefulWidget {
+  const Body({super.key});
+
+  @override
+  State<Body> createState() => _BodyState();
+}
+
+class _BodyState extends State<Body> with WidgetsBindingObserver {
+  bool _shouldExit = false;
+  String lastResponse = 'No exit requested yet';
+
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addObserver(this);
+  }
+
+  @override
+  void dispose() {
+    WidgetsBinding.instance.removeObserver(this);
+    super.dispose();
+  }
+
+  Future<void> _quit() async {
+    final AppExitType exitType = _shouldExit ? AppExitType.required : AppExitType.cancelable;
+    setState(() {
+      lastResponse = 'App requesting ${exitType.name} exit';
+    });
+    await ServicesBinding.instance.exitApplication(exitType);
+  }
+
+  @override
+  Future<AppExitResponse> didRequestAppExit() async {
+    final AppExitResponse response = _shouldExit ? AppExitResponse.exit : AppExitResponse.cancel;
+    setState(() {
+      lastResponse = 'App responded ${response.name} to exit request';
+    });
+    return response;
+  }
+
+  void _radioChanged(bool? value) {
+    value ??= true;
+    if (_shouldExit == value) {
+      return;
+    }
+    setState(() {
+      _shouldExit = value!;
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Center(
+      child: SizedBox(
+        width: 300,
+        child: IntrinsicHeight(
+          child: Column(
+            children: <Widget>[
+              RadioListTile<bool>(
+                title: const Text('Do Not Allow Exit'),
+                groupValue: _shouldExit,
+                value: false,
+                onChanged: _radioChanged,
+              ),
+              RadioListTile<bool>(
+                title: const Text('Allow Exit'),
+                groupValue: _shouldExit,
+                value: true,
+                onChanged: _radioChanged,
+              ),
+              const SizedBox(height: 30),
+              ElevatedButton(
+                onPressed: _quit,
+                child: const Text('Quit'),
+              ),
+              const SizedBox(height: 30),
+              Text(lastResponse),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}
diff --git a/examples/api/macos/Runner/Info.plist b/examples/api/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/examples/api/test/services/binding/handle_request_app_exit.0_test.dart b/examples/api/test/services/binding/handle_request_app_exit.0_test.dart
@@ -0,0 +1,22 @@
+// Copyright 2014 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 'package:flutter_api_samples/services/binding/handle_request_app_exit.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Application Exit example', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.ApplicationExitExample(),
+    );
+
+    expect(find.text('No exit requested yet'), findsOneWidget);
+    expect(find.text('Do Not Allow Exit'), findsOneWidget);
+    expect(find.text('Allow Exit'), findsOneWidget);
+    expect(find.text('Quit'), findsOneWidget);
+    await tester.tap(find.text('Quit'));
+    await tester.pump();
+    expect(find.text('App requesting cancelable exit'), findsOneWidget);
+  });
+}
diff --git a/examples/flutter_view/macos/Runner/Info.plist b/examples/flutter_view/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/examples/hello_world/macos/Runner/Info.plist b/examples/hello_world/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/examples/image_list/macos/Runner/Info.plist b/examples/image_list/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/examples/layers/macos/Runner/Info.plist b/examples/layers/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/examples/platform_view/macos/Runner/Info.plist b/examples/platform_view/macos/Runner/Info.plist
@@ -27,6 +27,6 @@
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
-	<string>FlutterApplication</string>
+	<string>NSApplication</string>
 </dict>
 </plist>
diff --git a/packages/flutter/lib/src/services/binding.dart b/packages/flutter/lib/src/services/binding.dart
@@ -263,30 +263,119 @@ mixin ServicesBinding on BindingBase, SchedulerBinding {
     return null;
   }
 
-  Future<void> _handlePlatformMessage(MethodCall methodCall) async {
+  Future<dynamic> _handlePlatformMessage(MethodCall methodCall) async {
     final String method = methodCall.method;
-    // There is only one incoming method call currently possible.
-    assert(method == 'SystemChrome.systemUIChange');
-    final List<dynamic> args = methodCall.arguments as List<dynamic>;
-    if (_systemUiChangeCallback != null) {
-      await _systemUiChangeCallback!(args[0] as bool);
+    assert(method == 'SystemChrome.systemUIChange' || method == 'System.requestAppExit');
+    switch (method) {
+      case 'SystemChrome.systemUIChange':
+        final List<dynamic> args = methodCall.arguments as List<dynamic>;
+        if (_systemUiChangeCallback != null) {
+          await _systemUiChangeCallback!(args[0] as bool);
+        }
+        break;
+      case 'System.requestAppExit':
+        return <String, dynamic>{'response': (await handleRequestAppExit()).name};
     }
   }
 
   static AppLifecycleState? _parseAppLifecycleMessage(String message) {
     switch (message) {
-      case 'AppLifecycleState.paused':
-        return AppLifecycleState.paused;
       case 'AppLifecycleState.resumed':
         return AppLifecycleState.resumed;
       case 'AppLifecycleState.inactive':
         return AppLifecycleState.inactive;
+      case 'AppLifecycleState.paused':
+        return AppLifecycleState.paused;
       case 'AppLifecycleState.detached':
         return AppLifecycleState.detached;
     }
     return null;
   }
 
+  /// Handles any requests for application exit that may be received on the
+  /// [SystemChannels.platform] method channel.
+  ///
+  /// By default, returns [ui.AppExitResponse.exit].
+  ///
+  /// {@template flutter.services.binding.ServicesBinding.requestAppExit}
+  /// Not all exits are cancelable, so not all exits will call this function. Do
+  /// not rely on this function as a place to save critical data, because you
+  /// will be disappointed. There are a number of ways that the application can
+  /// exit without letting the application know first: power can be unplugged,
+  /// the battery removed, the application can be killed in a task manager or
+  /// command line, or the device could have a rapid unplanned disassembly (i.e.
+  /// it could explode). In all of those cases (and probably others), no
+  /// notification will be given to the application that it is about to exit.
+  /// {@endtemplate}
+  ///
+  /// {@tool sample}
+  /// This examples shows how an application can cancel (or not) OS requests for
+  /// quitting an application. Currently this is only supported on macOS and
+  /// Linux.
+  ///
+  /// ** See code in examples/api/lib/services/binding/handle_request_app_exit.0.dart **
+  /// {@end-tool}
+  ///
+  /// See also:
+  ///
+  /// * [WidgetsBindingObserver.didRequestAppExit], which can be overridden to
+  ///   respond to this message.
+  /// * [WidgetsBinding.handleRequestAppExit] which overrides this method to
+  ///   notify its observers.
+  Future<ui.AppExitResponse> handleRequestAppExit() async {
+    return ui.AppExitResponse.exit;
+  }
+
+  /// Exits the application by calling the native application API method for
+  /// exiting an application cleanly.
+  ///
+  /// This differs from calling `dart:io`'s [exit] function in that it gives the
+  /// engine a chance to clean up resources so that it doesn't crash on exit, so
+  /// calling this is always preferred over calling [exit]. It also optionally
+  /// gives handlers of [handleRequestAppExit] a chance to cancel the
+  /// application exit.
+  ///
+  /// The [exitType] indicates what kind of exit to perform. For
+  /// [ui.AppExitType.cancelable] exits, the application is queried through a
+  /// call to [handleRequestAppExit], where the application can optionally
+  /// cancel the request for exit. If the [exitType] is
+  /// [ui.AppExitType.required], then the application exits immediately without
+  /// querying the application.
+  ///
+  /// For [ui.AppExitType.cancelable] exits, the returned response value is the
+  /// response obtained from the application as to whether the exit was canceled
+  /// or not. Practically, the response will never be [ui.AppExitResponse.exit],
+  /// since the application will have already exited by the time the result
+  /// would have been received.
+  ///
+  /// The optional [exitCode] argument will be used as the application exit code
+  /// on platforms where an exit code is supported. On other platforms it may be
+  /// ignored. It defaults to zero.
+  ///
+  /// See also:
+  ///
+  /// * [WidgetsBindingObserver.didRequestAppExit] for a handler you can
+  ///   override on a [WidgetsBindingObserver] to receive exit requests.
+  @mustCallSuper
+  Future<ui.AppExitResponse> exitApplication(ui.AppExitType exitType, [int exitCode = 0]) async {
+    final Map<String, Object?>? result = await SystemChannels.platform.invokeMethod<Map<String, Object?>>(
+      'System.exitApplication',
+      <String, Object?>{'type': exitType.name, 'exitCode': exitCode},
+    );
+    if (result == null ) {
+      return ui.AppExitResponse.cancel;
+    }
+    switch (result['response']) {
+      case 'cancel':
+        return ui.AppExitResponse.cancel;
+      case 'exit':
+      default:
+        // In practice, this will never get returned, because the application
+        // will have exited before it returns.
+        return ui.AppExitResponse.exit;
+    }
+  }
+
   /// The [RestorationManager] synchronizes the restoration data between
   /// engine and framework.
   ///
@@ -326,7 +415,6 @@ mixin ServicesBinding on BindingBase, SchedulerBinding {
   void setSystemUiChangeCallback(SystemUiChangeCallback? callback) {
     _systemUiChangeCallback = callback;
   }
-
 }
 
 /// Signature for listening to changes in the [SystemUiMode].
diff --git a/packages/flutter/lib/src/services/system_channels.dart b/packages/flutter/lib/src/services/system_channels.dart
@@ -120,6 +120,11 @@ class SystemChannels {
   ///  * `SystemNavigator.pop`: Tells the operating system to close the
   ///    application, or the closest equivalent. See [SystemNavigator.pop].
   ///
+  ///  * `System.exitApplication`: Tells the engine to send a request back to
+  ///    the application to request an application exit (using
+  ///    `System.requestAppExit` below), and if it is not canceled, to terminate
+  ///    the application using the platform UI toolkit's termination API.
+  ///
   /// The following incoming methods are defined for this channel (registered
   /// using [MethodChannel.setMethodCallHandler]):
   ///
@@ -129,6 +134,9 @@ class SystemChannels {
   ///    [SystemChrome.setSystemUIChangeCallback] to respond to this change in
   ///    application state.
   ///
+  ///  * `System.requestAppExit`: The application has requested that it be
+  ///    terminated. See [ServicesBinding.exitApplication].
+  ///
   /// Calls to methods that are not implemented on the shell side are ignored
   /// (so it is safe to call methods when the relevant plugin might be missing).
   static const MethodChannel platform = OptionalMethodChannel(
diff --git a/packages/flutter/lib/src/widgets/binding.dart b/packages/flutter/lib/src/widgets/binding.dart
diff --git a/packages/flutter/test/services/binding_test.dart b/packages/flutter/test/services/binding_test.dart
diff --git a/packages/flutter_tools/templates/app_shared/macos.tmpl/Runner/Info.plist b/packages/flutter_tools/templates/app_shared/macos.tmpl/Runner/Info.plist
