Refactor initial route code take 2 (flutter#20468)

ci/licenses_golden/licenses_flutter

@@ -925,6 +925,7 @@ FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine.
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterEnginePlatformViewTest.mm
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterEngineTest.mm
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine_Internal.h
+FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine_Test.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterHeadlessDartRunner.mm
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterObservatoryPublisher.h
 FILE: ../../../flutter/shell/platform/darwin/ios/framework/Source/FlutterObservatoryPublisher.mm

lib/ui/window.dart

@@ -1056,23 +1056,19 @@ class Window {
   ///
   /// ## Android
   ///
-  /// On Android, calling
-  /// [`FlutterView.setInitialRoute`](/javadoc/io/flutter/view/FlutterView.html#setInitialRoute-java.lang.String-)
-  /// will set this value. The value must be set sufficiently early, i.e. before
-  /// the [runApp] call is executed in Dart, for this to have any effect on the
-  /// framework. The `createFlutterView` method in your `FlutterActivity`
-  /// subclass is a suitable time to set the value. The application's
-  /// `AndroidManifest.xml` file must also be updated to have a suitable
-  /// [`<intent-filter>`](https://developer.android.com/guide/topics/manifest/intent-filter-element.html).
+  /// On Android, the initial route can be set on the [initialRoute](/javadoc/io/flutter/embedding/android/FlutterActivity.NewEngineIntentBuilder.html#initialRoute-java.lang.String-)
+  /// method of the [FlutterActivity](/javadoc/io/flutter/embedding/android/FlutterActivity.html)'s
+  /// intent builder.
+  ///
+  /// On a standalone engine, see https://flutter.dev/docs/development/add-to-app/android/add-flutter-screen#initial-route-with-a-cached-engine.
   ///
   /// ## iOS
   ///
-  /// On iOS, calling
-  /// [`FlutterViewController.setInitialRoute`](/objcdoc/Classes/FlutterViewController.html#/c:objc%28cs%29FlutterViewController%28im%29setInitialRoute:)
-  /// will set this value. The value must be set sufficiently early, i.e. before
-  /// the [runApp] call is executed in Dart, for this to have any effect on the
-  /// framework. The `application:didFinishLaunchingWithOptions:` method is a
-  /// suitable time to set this value.
+  /// On iOS, the initial route can be set on the `initialRoute`
+  /// parameter of the [FlutterViewController](/objcdoc/Classes/FlutterViewController.html)'s
+  /// initializer.
+  ///
+  /// On a standalone engine, see https://flutter.dev/docs/development/add-to-app/ios/add-flutter-screen#route.
   ///
   /// See also:
   ///

lib/web_ui/lib/src/ui/window.dart

@@ -710,26 +710,6 @@ abstract class Window {
   ///
   /// This will be the string "`/`" if no particular route was requested.
   ///
-  /// ## Android
-  ///
-  /// On Android, calling
-  /// [`FlutterView.setInitialRoute`](/javadoc/io/flutter/view/FlutterView.html#setInitialRoute-java.lang.String-)
-  /// will set this value. The value must be set sufficiently early, i.e. before
-  /// the [runApp] call is executed in Dart, for this to have any effect on the
-  /// framework. The `createFlutterView` method in your `FlutterActivity`
-  /// subclass is a suitable time to set the value. The application's
-  /// `AndroidManifest.xml` file must also be updated to have a suitable
-  /// [`<intent-filter>`](https://developer.android.com/guide/topics/manifest/intent-filter-element.html).
-  ///
-  /// ## iOS
-  ///
-  /// On iOS, calling
-  /// [`FlutterViewController.setInitialRoute`](/objcdoc/Classes/FlutterViewController.html#/c:objc%28cs%29FlutterViewController%28im%29setInitialRoute:)
-  /// will set this value. The value must be set sufficiently early, i.e. before
-  /// the [runApp] call is executed in Dart, for this to have any effect on the
-  /// framework. The `application:didFinishLaunchingWithOptions:` method is a
-  /// suitable time to set this value.
-  ///
   /// See also:
   ///
   ///  * [Navigator], a widget that handles routing.

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

@@ -5,52 +5,6 @@
 #ifndef FLUTTER_FLUTTER_H_
 #define FLUTTER_FLUTTER_H_
 
-/**
- BREAKING CHANGES:
-
- December 17, 2018:
-  - Changed designated initializer on FlutterEngine
-
- 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.
-
- July 26, 2018: Marked -[FlutterDartProject
- initFromDefaultSourceForConfiguration] deprecated.
-
- February 28, 2018: Removed "initWithFLXArchive" and
- "initWithFLXArchiveWithScriptSnapshot".
-
- January 15, 2018: Marked "initWithFLXArchive" and
- "initWithFLXArchiveWithScriptSnapshot" as unavailable following the
- deprecation from December 11, 2017. Scheduled to be removed on February
- 19, 2018.
-
- January 09, 2018: Deprecated "FlutterStandardBigInteger" and its use in
- "FlutterStandardMessageCodec" and "FlutterStandardMethodCodec". Scheduled to
- be marked as unavailable once the deprecation has been available on the
- flutter/flutter alpha branch for four weeks. "FlutterStandardBigInteger" was
- needed because the Dart 1.0 int type had no size limit. With Dart 2.0, the
- int type is a fixed-size, 64-bit signed integer. If you need to communicate
- larger integers, use NSString encoding instead.
-
- December 11, 2017: Deprecated "initWithFLXArchive" and
- "initWithFLXArchiveWithScriptSnapshot" and scheculed the same to be marked as
- unavailable on January 15, 2018. Instead, "initWithFlutterAssets" and
- "initWithFlutterAssetsWithScriptSnapshot" should be used. The reason for this
- change is that the FLX archive will be deprecated and replaced with a flutter
- assets directory containing the same files as the FLX did.
-
- November 29, 2017: Added a BREAKING CHANGES section.
- */
-
 #include "FlutterAppDelegate.h"
 #include "FlutterBinaryMessenger.h"
 #include "FlutterCallbackCache.h"

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

@@ -24,6 +24,11 @@ NS_ASSUME_NONNULL_BEGIN
  */
 extern NSString* const FlutterDefaultDartEntrypoint;
 
+/**
+ * The default Flutter initial route ("/").
+ */
+extern NSString* const FlutterDefaultInitialRoute;
+
 /**
  * The FlutterEngine class coordinates a single instance of execution for a
  * `FlutterDartProject`.  It may have zero or one `FlutterViewController` at a
@@ -53,6 +58,24 @@ extern NSString* const FlutterDefaultDartEntrypoint;
 FLUTTER_EXPORT
 @interface FlutterEngine : NSObject <FlutterTextureRegistry, FlutterPluginRegistry>
 
+/**
+ * Default initializer for a FlutterEngine.
+ *
+ * Threads created by this FlutterEngine will appear as "FlutterEngine #" in
+ * Instruments. The prefix can be customized using `initWithName`.
+ *
+ * The engine will execute the project located in the bundle with the identifier
+ * "io.flutter.flutter.app" (the default for Flutter projects).
+ *
+ * A newly initialized engine will not run until either `-runWithEntrypoint:` or
+ * `-runWithEntrypoint:libraryURI:` is called.
+ *
+ * FlutterEngine created with this method will have allowHeadlessExecution set to `YES`.
+ * This means that the engine will continue to run regardless of whether a `FlutterViewController`
+ * is attached to it or not, until `-destroyContext:` is called or the process finishes.
+ */
+- (instancetype)init;
+
 /**
  * Initialize this FlutterEngine.
  *
@@ -114,17 +137,12 @@ FLUTTER_EXPORT
                      project:(nullable FlutterDartProject*)project
       allowHeadlessExecution:(BOOL)allowHeadlessExecution NS_DESIGNATED_INITIALIZER;
 
-/**
- * The default initializer is not available for this object.
- * Callers must use `-[FlutterEngine initWithName:project:]`.
- */
-- (instancetype)init NS_UNAVAILABLE;
-
 + (instancetype)new NS_UNAVAILABLE;
 
 /**
  * Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
- * contains `main()`), using `main()` as the entrypoint (the default for Flutter projects).
+ * contains `main()`), using `main()` as the entrypoint (the default for Flutter projects),
+ * and using "/" (the default route) as the initial route.
  *
  * The first call to this method will create a new Isolate. Subsequent calls will return
  * immediately and have no effect.
@@ -135,7 +153,7 @@ FLUTTER_EXPORT
 
 /**
  * Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
- * contains `main()`).
+ * contains `main()`), using "/" (the default route) as the initial route.
  *
  * The first call to this method will create a new Isolate. Subsequent calls will return
  * immediately and have no effect.
@@ -149,6 +167,25 @@ FLUTTER_EXPORT
  */
 - (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint;
 
+/**
+ * Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
+ * contains `main()`).
+ *
+ * The first call to this method will create a new Isolate. Subsequent calls will return
+ * immediately and have no effect.
+ *
+ * @param entrypoint The name of a top-level function from the same Dart
+ *   library that contains the app's main() function.  If this is FlutterDefaultDartEntrypoint (or
+ *   nil), it will default to `main()`.  If it is not the app's main() function, that function must
+ *   be decorated with `@pragma(vm:entry-point)` to ensure the method is not tree-shaken by the Dart
+ *   compiler.
+ * @param initialRoute The name of the initial Flutter `Navigator` `Route` to load. If this is
+ *   FlutterDefaultInitialRoute (or nil), it will default to the "/" route.
+ * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
+ */
+- (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint
+             initialRoute:(nullable NSString*)initialRoute;
+
 /**
  * Runs a Dart program on an Isolate using the specified entrypoint and Dart library,
  * which may not be the same as the library containing the Dart program's `main()` function.

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

@@ -55,7 +55,7 @@ FLUTTER_EXPORT
  *
  * The initialized viewcontroller will attach itself to the engine as part of this process.
  *
- * @param engine The `FlutterEngine` instance to attach to.
+ * @param engine The `FlutterEngine` instance to attach to. Cannot be nil.
  * @param nibName The NIB name to initialize this UIViewController with.
  * @param nibBundle The NIB bundle.
  */
@@ -78,6 +78,23 @@ FLUTTER_EXPORT
                         nibName:(nullable NSString*)nibName
                          bundle:(nullable NSBundle*)nibBundle NS_DESIGNATED_INITIALIZER;
 
+/**
+ * Initializes a new FlutterViewController and `FlutterEngine` with the specified
+ * `FlutterDartProject` and `initialRoute`.
+ *
+ * This will implicitly create a new `FlutterEngine` which is retrievable via the `engine` property
+ * after initialization.
+ *
+ * @param project The `FlutterDartProject` to initialize the `FlutterEngine` with.
+ * @param initialRoute The initial `Navigator` route to load.
+ * @param nibName The NIB name to initialize this UIViewController with.
+ * @param nibBundle The NIB bundle.
+ */
+- (instancetype)initWithProject:(nullable FlutterDartProject*)project
+                   initialRoute:(nullable NSString*)initialRoute
+                        nibName:(nullable NSString*)nibName
+                         bundle:(nullable NSBundle*)nibBundle NS_DESIGNATED_INITIALIZER;
+
 /**
  * Initializer that is called from loading a FlutterViewController from a XIB.
  *
@@ -117,6 +134,8 @@ FLUTTER_EXPORT
 - (NSString*)lookupKeyForAsset:(NSString*)asset fromPackage:(NSString*)package;
 
 /**
+ * Deprecated API to set initial route.
+ *
  * Attempts to set the first route that the Flutter app shows if the Flutter
  * runtime hasn't yet started. The default is "/".
  *
@@ -127,9 +146,15 @@ FLUTTER_EXPORT
  * Setting this after the Flutter started running has no effect. See `pushRoute`
  * and `popRoute` to change the route after Flutter started running.
  *
+ * This is deprecated because it needs to be called at the time of initialization
+ * and thus should just be in the `initWithProject` initializer. If using
+ * `initWithEngine`, the initial route should be set on the engine's
+ * initializer.
+ *
  * @param route The name of the first route to show.
  */
-- (void)setInitialRoute:(NSString*)route;
+- (void)setInitialRoute:(NSString*)route
+    FLUTTER_DEPRECATED("Use FlutterViewController initializer to specify initial route");
 
 /**
  * Instructs the Flutter Navigator (if any) to go back.
@@ -138,8 +163,7 @@ FLUTTER_EXPORT
 
 /**
  * Instructs the Flutter Navigator (if any) to push a route on to the navigation
- * stack.  The setInitialRoute method should be preferred if this is called before the
- * FlutterViewController has come into view.
+ * stack.
  *
  * @param route The name of the route to push to the navigation stack.
  */