Revert "Refactor initial route code (#19684)" (#20450)

This reverts commit 8d08e6c.

Author: gaaclarke

ci/licenses_golden/licenses_flutter

@@ -925,7 +925,6 @@ 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,19 +1056,23 @@ class Window {
   ///
   /// ## Android
   ///
-  /// 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.
+  /// 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, 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.
+  /// 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:
   ///

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

@@ -710,6 +710,26 @@ 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,6 +5,52 @@
 #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,11 +24,6 @@ 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
@@ -58,24 +53,6 @@ extern NSString* const FlutterDefaultInitialRoute;
 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.
  *
@@ -137,12 +114,17 @@ 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),
- * and using "/" (the default route) as the initial route.
+ * contains `main()`), using `main()` as the entrypoint (the default for Flutter projects).
  *
  * The first call to this method will create a new Isolate. Subsequent calls will return
  * immediately and have no effect.
@@ -153,7 +135,7 @@ FLUTTER_EXPORT
 
 /**
  * Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
- * contains `main()`), using "/" (the default route) as the initial route.
+ * contains `main()`).
  *
  * The first call to this method will create a new Isolate. Subsequent calls will return
  * immediately and have no effect.
@@ -167,25 +149,6 @@ 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. Cannot be nil.
+ * @param engine The `FlutterEngine` instance to attach to.
  * @param nibName The NIB name to initialize this UIViewController with.
  * @param nibBundle The NIB bundle.
  */
@@ -78,23 +78,6 @@ 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.
  *
@@ -134,8 +117,6 @@ 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 "/".
  *
@@ -146,15 +127,9 @@ 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
-    FLUTTER_DEPRECATED("Use FlutterViewController initializer to specify initial route");
+- (void)setInitialRoute:(NSString*)route;
 
 /**
  * Instructs the Flutter Navigator (if any) to go back.
@@ -163,7 +138,8 @@ FLUTTER_EXPORT
 
 /**
  * Instructs the Flutter Navigator (if any) to push a route on to the navigation
- * stack.
+ * stack.  The setInitialRoute method should be preferred if this is called before the
+ * FlutterViewController has come into view.
  *
  * @param route The name of the route to push to the navigation stack.
  */