iOS Embedding Refactor (flutter#6447)

* Create FlutterEngine to manage a Shell to support maintaining execution state across instances of FlutterViewControllers
* Refactor PlatformViewIOS to support adding or removing a FlutterViewController dynamically
* Refactor FlutterDartHeadlessCodeRunner to implement FlutterEngine
* Refactor FlutterViewController to accept a FlutterEngine at initialization or to create one for backwards compatibility; any Shell related responsibilities are now passed through to the Engine instance
* Remove FlutterNavigationController (unused)
* Update all public Objective C doc comments to be consistent and formatable
* Add public documentation to all public headers

ci/licenses_golden/licenses_flutter

@@ -118,13 +118,11 @@ FILE: ../../../flutter/shell/platform/darwin/ios/framework/Headers/FlutterBinary
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Headers/FlutterChannels.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Headers/FlutterCodecs.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Headers/FlutterHeadlessDartRunner.h
-FILE: ../../../flutter/shell/platform/darwin/ios/framework/Headers/FlutterNavigationController.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Headers/FlutterPlugin.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Headers/FlutterTexture.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterChannels.mm
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterCodecs.mm
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterHeadlessDartRunner.mm
-FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterNavigationController.mm
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterStandardCodec.mm
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterStandardCodec_Internal.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterUmbrellaImport.m
@@ -203,7 +201,6 @@ FILE: ../../../flutter/shell/platform/android/io/flutter/plugin/common/JSONUtil.
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Flutter.podspec
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Info.plist
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/module.modulemap
-FILE: ../../../flutter/shell/platform/darwin/ios/headless_platform_view_ios.mm
 FILE: ../../../flutter/shell/platform/embedder/assets/EmbedderInfo.plist
 FILE: ../../../flutter/shell/platform/embedder/assets/embedder.modulemap
 FILE: ../../../flutter/shell/platform/embedder/fixtures/simple_main.dart
@@ -518,7 +515,10 @@ FILE: ../../../flutter/shell/platform/android/android_shell_holder.cc
 FILE: ../../../flutter/shell/platform/android/android_shell_holder.h
 FILE: ../../../flutter/shell/platform/android/platform_message_response_android.cc
 FILE: ../../../flutter/shell/platform/android/platform_message_response_android.h
+FILE: ../../../flutter/shell/platform/darwin/ios/framework/Headers/FlutterEngine.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterAppDelegate_Internal.h
+FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine.mm
+FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine_Internal.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterObservatoryPublisher.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterObservatoryPublisher.mm
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterPlatformViews.mm
@@ -599,7 +599,6 @@ FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterCallbac
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterPluginAppLifeCycleDelegate.mm
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/accessibility_text_entry.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/accessibility_text_entry.mm
-FILE: ../../../flutter/shell/platform/darwin/ios/headless_platform_view_ios.h
 ----------------------------------------------------------------------------------------------------
 Copyright 2018 The Chromium Authors. All rights reserved.
 

shell/platform/darwin/ios/BUILD.gn

@@ -26,9 +26,9 @@ _flutter_framework_headers = [
   "framework/Headers/FlutterChannels.h",
   "framework/Headers/FlutterCodecs.h",
   "framework/Headers/FlutterDartProject.h",
+  "framework/Headers/FlutterEngine.h",
   "framework/Headers/FlutterHeadlessDartRunner.h",
   "framework/Headers/FlutterMacros.h",
-  "framework/Headers/FlutterNavigationController.h",
   "framework/Headers/FlutterPlatformViews.h",
   "framework/Headers/FlutterPlugin.h",
   "framework/Headers/FlutterPluginAppLifeCycleDelegate.h",
@@ -52,8 +52,9 @@ shared_library("create_flutter_framework_dylib") {
     "framework/Source/FlutterCodecs.mm",
     "framework/Source/FlutterDartProject.mm",
     "framework/Source/FlutterDartProject_Internal.h",
+    "framework/Source/FlutterEngine.mm",
+    "framework/Source/FlutterEngine_Internal.h",
     "framework/Source/FlutterHeadlessDartRunner.mm",
-    "framework/Source/FlutterNavigationController.mm",
     "framework/Source/FlutterObservatoryPublisher.h",
     "framework/Source/FlutterObservatoryPublisher.mm",
     "framework/Source/FlutterPlatformPlugin.h",
@@ -80,8 +81,6 @@ shared_library("create_flutter_framework_dylib") {
     "framework/Source/platform_message_router.mm",
     "framework/Source/vsync_waiter_ios.h",
     "framework/Source/vsync_waiter_ios.mm",
-    "headless_platform_view_ios.h",
-    "headless_platform_view_ios.mm",
     "ios_external_texture_gl.h",
     "ios_external_texture_gl.mm",
     "ios_gl_context.h",

shell/platform/darwin/ios/framework/Headers/Flutter.h

@@ -8,6 +8,13 @@
 /**
  BREAKING CHANGES:
 
+ October 5, 2018:
+  - Removed FlutterNavigationController.h/.mm
+  - Changed return signature of `FlutterDartHeadlessCodeRunner.run*` from void
+ to bool
+  - Removed HeadlessPlatformViewIOS
+  - Marked FlutterDartHeadlessCodeRunner deprecated
+
  August 31, 2018: Marked -[FlutterDartProject
  initFromDefaultSourceForConfiguration] and FlutterStandardBigInteger as
  unavailable.
@@ -47,9 +54,9 @@
 #include "FlutterChannels.h"
 #include "FlutterCodecs.h"
 #include "FlutterDartProject.h"
+#include "FlutterEngine.h"
 #include "FlutterHeadlessDartRunner.h"
 #include "FlutterMacros.h"
-#include "FlutterNavigationController.h"
 #include "FlutterPlatformViews.h"
 #include "FlutterPlugin.h"
 #include "FlutterPluginAppLifeCycleDelegate.h"

shell/platform/darwin/ios/framework/Headers/FlutterAppDelegate.h

@@ -11,11 +11,11 @@
 #include "FlutterPlugin.h"
 
 /**
- * UIApplicationDelegate subclass for simple apps that want default behavior.
+ * `UIApplicationDelegate` subclass for simple apps that want default behavior.
  *
- * This class provides the following behaviors:
+ * This class implements the following behaviors:
  *   * Status bar touches are forwarded to the key window's root view
- *     FlutterViewController, in order to trigger scroll to top.
+ *     `FlutterViewController`, in order to trigger scroll to top.
  *   * Keeps the Flutter connection open in debug mode when the phone screen
  *     locks.
  *
@@ -24,7 +24,8 @@
  * code as necessary from FlutterAppDelegate.mm.
  */
 FLUTTER_EXPORT
-@interface FlutterAppDelegate : UIResponder<UIApplicationDelegate, FlutterPluginRegistry, FlutterAppLifeCycleProvider>
+@interface FlutterAppDelegate
+    : UIResponder <UIApplicationDelegate, FlutterPluginRegistry, FlutterAppLifeCycleProvider>
 
 @property(strong, nonatomic) UIWindow* window;
 

shell/platform/darwin/ios/framework/Headers/FlutterBinaryMessenger.h

@@ -11,72 +11,67 @@
 
 NS_ASSUME_NONNULL_BEGIN
 /**
- A message reply callback.
-
- Used for submitting a binary reply back to a Flutter message sender. Also used
- in the dual capacity for handling a binary message reply received from Flutter.
-
- - Parameters:
-   - reply: The reply.
+ * A message reply callback.
+ *
+ * Used for submitting a binary reply back to a Flutter message sender. Also used
+ * in for handling a binary message reply received from Flutter.
+ *
+ * @param reply The reply.
  */
 typedef void (^FlutterBinaryReply)(NSData* _Nullable reply);
 
 /**
- A strategy for handling incoming binary messages from Flutter and to send
- asynchronous replies back to Flutter.
-
- - Parameters:
-   - message: The message.
-   - reply: A callback for submitting a reply to the sender.
+ * A strategy for handling incoming binary messages from Flutter and to send
+ * asynchronous replies back to Flutter.
+ *
+ * @param message The message.
+ * @param reply A callback for submitting an asynchronous reply to the sender.
  */
 typedef void (^FlutterBinaryMessageHandler)(NSData* _Nullable message, FlutterBinaryReply reply);
 
 /**
- A facility for communicating with the Flutter side using asynchronous message
- passing with binary messages.
-
- - SeeAlso:
-   - `FlutterBasicMessageChannel`, which supports communication using structured
- messages.
-   - `FlutterMethodChannel`, which supports communication using asynchronous
- method calls.
-   - `FlutterEventChannel`, which supports commuication using event streams.
+ * A facility for communicating with the Flutter side using asynchronous message
+ * passing with binary messages.
+ *
+ * Implementated by:
+ * - `FlutterBasicMessageChannel`, which supports communication using structured
+ * messages.
+ * - `FlutterMethodChannel`, which supports communication using asynchronous
+ * method calls.
+ * - `FlutterEventChannel`, which supports commuication using event streams.
  */
 FLUTTER_EXPORT
-@protocol FlutterBinaryMessenger<NSObject>
+@protocol FlutterBinaryMessenger <NSObject>
 /**
- Sends a binary message to the Flutter side on the specified channel, expecting
- no reply.
-
- - Parameters:
-   - channel: The channel name.
-   - message: The message.
+ * Sends a binary message to the Flutter side on the specified channel, expecting
+ * no reply.
+ *
+ * @param channel The channel name.
+ * @param message The message.
  */
 - (void)sendOnChannel:(NSString*)channel message:(NSData* _Nullable)message;
 
 /**
- Sends a binary message to the Flutter side on the specified channel, expecting
- an asynchronous reply.
-
- - Parameters:
-   - channel: The channel name.
-   - message: The message.
-   - callback: A callback for receiving a reply.
+ * Sends a binary message to the Flutter side on the specified channel, expecting
+ * an asynchronous reply.
+ *
+ * @param channel The channel name.
+ * @param message The message.
+ * @param callback A callback for receiving a reply.
  */
 - (void)sendOnChannel:(NSString*)channel
               message:(NSData* _Nullable)message
           binaryReply:(FlutterBinaryReply _Nullable)callback;
 
 /**
- Registers a message handler for incoming binary messages from the Flutter side
- on the specified channel.
-
- Replaces any existing handler. Use a `nil` handler for unregistering the
- existing handler.
-
- - Parameters:
-   - channel: The channel name.
-   - handler: The message handler.
+ * Registers a message handler for incoming binary messages from the Flutter side
+ * on the specified channel.
+ *
+ * Replaces any existing handler. Use a `nil` handler for unregistering the
+ * existing handler.
+ *
+ * @param channel The channel name.
+ * @param handler The message handler.
  */
 - (void)setMessageHandlerOnChannel:(NSString*)channel
               binaryMessageHandler:(FlutterBinaryMessageHandler _Nullable)handler;

shell/platform/darwin/ios/framework/Headers/FlutterCallbackCache.h

@@ -9,26 +9,43 @@
 
 #include "FlutterMacros.h"
 
+/**
+ * An object containing the result of `FlutterCallbackCache`'s `lookupCallbackInformation`
+ * method.
+ */
 FLUTTER_EXPORT
 @interface FlutterCallbackInformation : NSObject
+/**
+ * The name of the callback.
+ */
 @property(retain) NSString* callbackName;
+/**
+ * The class name of the callback.
+ */
 @property(retain) NSString* callbackClassName;
+/**
+ * The library path of the callback.
+ */
 @property(retain) NSString* callbackLibraryPath;
 @end
 
+/**
+ * The cache containing callback information for spawning a
+ * `FlutterHeadlessDartRunner`.
+ */
 FLUTTER_EXPORT
 @interface FlutterCallbackCache : NSObject
 /**
- Returns the callback information for the given callback handle.
- This callback information can be used when spawning a
- FlutterHeadlessDartRunner.
-
- - Parameter handle: The handle for a callback, provided by the
-   Dart method `PluginUtilities.getCallbackHandle`.
- - Returns: A FlutterCallbackInformation object which contains the name of the
-   callback, the name of the class in which the callback is defined, and the
-   path of the library which contains the callback. If the provided handle is
-   invalid, nil is returned.
+ * Returns the callback information for the given callback handle.
+ * This callback information can be used when spawning a
+ * `FlutterHeadlessDartRunner`.
+ *
+ * @param handle The handle for a callback, provided by the
+ *   Dart method `PluginUtilities.getCallbackHandle`.
+ * @return A `FlutterCallbackInformation` object which contains the name of the
+ *   callback, the name of the class in which the callback is defined, and the
+ *   path of the library which contains the callback. If the provided handle is
+ *   invalid, nil is returned.
  */
 + (FlutterCallbackInformation*)lookupCallbackInformation:(int64_t)handle;