Create a CupertinoApp (#18469)

bin/internal/goldens.version

-bc99a4bdea0533994b34bc49f160af75f4904952
+413041fd6bbedd1c8bc6ca0b6ea6ea948079b669

packages/flutter/lib/cupertino.dart

@@ -8,6 +8,7 @@
 library cupertino;
 
 export 'src/cupertino/activity_indicator.dart';
+export 'src/cupertino/app.dart';
 export 'src/cupertino/bottom_tab_bar.dart';
 export 'src/cupertino/button.dart';
 export 'src/cupertino/colors.dart';

packages/flutter/lib/src/widgets/app.dart

@@ -123,6 +123,7 @@ class WidgetsApp extends StatefulWidget {
   /// null, [navigatorKey] must also be null.
   final GlobalKey<NavigatorState> navigatorKey;
 
+  /// {@template flutter.widgets.widgetsApp.onGenerateRoute}
   /// The route generator callback used when the app is navigated to a
   /// named route.
   ///
@@ -133,6 +134,7 @@ class WidgetsApp extends StatefulWidget {
   /// During normal app operation, the [onGenerateRoute] callback will only be
   /// applied to route names pushed by the application, and so should never
   /// return null.
+  /// {@endtemplate}
   ///
   /// The [Navigator] is only built if [onGenerateRoute] is not null. If
   /// [onGenerateRoute] is null, the [builder] must be non-null.
@@ -140,18 +142,21 @@ class WidgetsApp extends StatefulWidget {
 
   /// Called when [onGenerateRoute] fails to generate a route.
   ///
+  /// {@template flutter.widgets.widgetsApp.onUnknownRoute}
   /// This callback is typically used for error handling. For example, this
   /// callback might always generate a "not found" page that describes the route
   /// that wasn't found.
   ///
   /// Unknown routes can arise either from errors in the app or from external
   /// requests to push routes, such as from Android intents.
+  /// {@endtemplate}
   ///
   /// The [Navigator] is only built if [onGenerateRoute] is not null; if it is
   /// null, [onUnknownRoute] must also be null.
   final RouteFactory onUnknownRoute;
 
-  /// The name of the first route to show.
+  /// {@template flutter.widgets.widgetsApp.initialRoute}
+  /// The name of the first route to show, if a [Navigator] is built.
   ///
   /// Defaults to [Window.defaultRouteName], which may be overridden by the code
   /// that launched the application.
@@ -165,6 +170,7 @@ class WidgetsApp extends StatefulWidget {
   /// [initialRoute] is ignored and [Navigator.defaultRouteName] is used instead
   /// (`/`). This can happen if the app is started with an intent that specifies
   /// a non-existent route.
+  /// {@endtemplate}
   ///
   /// The [Navigator] is only built if [onGenerateRoute] is not null; if it is
   /// null, [initialRoute] must also be null.
@@ -176,16 +182,19 @@ class WidgetsApp extends StatefulWidget {
   ///  * [Navigator.pop], for removing a route from the stack.
   final String initialRoute;
 
+  /// {@template flutter.widgets.widgetsApp.navigatorObservers}
   /// The list of observers for the [Navigator] created for this app.
   ///
   /// This list must be replaced by a list of newly-created observers if the
   /// [navigatorKey] is changed.
+  /// {@endtemplate}
   ///
   /// The [Navigator] is only built if [onGenerateRoute] is not null; if it is
   /// null, [navigatorObservers] must be left to its default value, the empty
   /// list.
   final List<NavigatorObserver> navigatorObservers;
 
+  /// {@template flutter.widgets.widgetsApp.builder}
   /// A builder for inserting widgets above the [Navigator] but below the other
   /// widgets created by the [WidgetsApp] widget, or for replacing the
   /// [Navigator] entirely.
@@ -200,8 +209,12 @@ class WidgetsApp extends StatefulWidget {
   /// mode despite being in English, or to override the [MediaQuery] metrics
   /// (e.g. to leave a gap for advertisements shown by a plugin from OEM code).
   ///
+  /// For specifically overriding the [title] with a value based on the
+  /// [Localizations], consider [onGenerateTitle] instead.
+  ///
   /// The [builder] callback is passed two arguments, the [BuildContext] (as
   /// `context`) and a [Navigator] widget (as `child`).
+  /// {@endtemplate}
   ///
   /// If [onGenerateRoute] is null, the `child` will be null, and it is the
   /// responsibility of the [builder] to provide the application's routing
@@ -216,11 +229,9 @@ class WidgetsApp extends StatefulWidget {
   /// If [builder] is null, it is as if a builder was specified that returned
   /// the `child` directly. At least one of either [onGenerateRoute] or
   /// [builder] must be non-null.
-  ///
-  /// For specifically overriding the [title] with a value based on the
-  /// [Localizations], consider [onGenerateTitle] instead.
   final TransitionBuilder builder;
 
+  /// {@template flutter.widgets.widgetsApp.title}
   /// A one-line description used by the device to identify the app for the user.
   ///
   /// On Android the titles appear above the task manager's app snapshots which are
@@ -229,8 +240,10 @@ class WidgetsApp extends StatefulWidget {
   /// home button.
   ///
   /// To provide a localized title instead, use [onGenerateTitle].
+  /// {@endtemplate}
   final String title;
 
+  /// {@template flutter.widgets.widgetsApp.onGenerateTitle}
   /// If non-null this callback function is called to produce the app's
   /// title string, otherwise [title] is used.
   ///
@@ -242,29 +255,37 @@ class WidgetsApp extends StatefulWidget {
   ///
   /// The [onGenerateTitle] callback is called each time the [WidgetsApp]
   /// rebuilds.
+  /// {@endtemplate}
   final GenerateAppTitle onGenerateTitle;
 
   /// The default text style for [Text] in the application.
   final TextStyle textStyle;
 
+  /// {@template flutter.widgets.widgetsApp.color}
   /// The primary color to use for the application in the operating system
   /// interface.
   ///
   /// For example, on Android this is the color used for the application in the
   /// application switcher.
+  /// {@endtemplate}
   final Color color;
 
+  /// {@template flutter.widgets.widgetsApp.locale}
   /// The initial locale for this app's [Localizations] widget.
   ///
   /// If the 'locale' is null the system's locale value is used.
+  /// {@endtemplate}
   final Locale locale;
 
+  /// {@template flutter.widgets.widgetsApp.localizationsDelegates}
   /// The delegates for this app's [Localizations] widget.
   ///
   /// The delegates collectively define all of the localized resources
   /// for this application's [Localizations] widget.
+  /// {@endtemplate}
   final Iterable<LocalizationsDelegate<dynamic>> localizationsDelegates;
 
+  /// {@template flutter.widgets.widgetsApp.localeResolutionCallback}
   /// This callback is responsible for choosing the app's locale
   /// when the app is started, and when the user changes the
   /// device's locale.
@@ -281,6 +302,7 @@ class WidgetsApp extends StatefulWidget {
   /// - The first supported locale with the same [Locale.languageCode] as the
   ///   callback's `locale` parameter.
   /// - The first locale in [supportedLocales].
+  /// {@endtemplate}
   ///
   /// See also:
   ///
@@ -288,6 +310,7 @@ class WidgetsApp extends StatefulWidget {
   ///    [WidgetsApp] it creates.
   final LocaleResolutionCallback localeResolutionCallback;
 
+  /// {@template flutter.widgets.widgetsApp.supportedLocales}
   /// The list of locales that this app has been localized for.
   ///
   /// By default only the American English locale is supported. Apps should
@@ -301,6 +324,7 @@ class WidgetsApp extends StatefulWidget {
   /// [supportedLocales] with a matching [Locale.languageCode] is used. If that
   /// fails then the first locale in [supportedLocales] is used. The default
   /// locale resolution algorithm can be overridden with [localeResolutionCallback].
+  /// {@endtemplate}
   ///
   /// See also:
   ///
@@ -315,7 +339,10 @@ class WidgetsApp extends StatefulWidget {
   final Iterable<Locale> supportedLocales;
 
   /// Turns on a performance overlay.
-  /// https://flutter.io/debugging/#performanceoverlay
+  ///
+  /// See also:
+  ///
+  ///  * <https://flutter.io/debugging/#performanceoverlay>
   final bool showPerformanceOverlay;
 
   /// Checkerboards raster cache images.
@@ -347,7 +374,8 @@ class WidgetsApp extends StatefulWidget {
   /// material package.
   final InspectorSelectButtonBuilder inspectorSelectButtonBuilder;
 
-  /// Turns on a "DEBUG" little banner in checked mode to indicate
+  /// {@template flutter.widgets.widgetsApp.debugShowCheckedModeBanner}
+  /// Turns on a little "DEBUG" banner in checked mode to indicate
   /// that the app is in checked mode. This is on by default (in
   /// checked mode), to turn it off, set the constructor argument to
   /// false. In release mode this has no effect.
@@ -355,11 +383,12 @@ class WidgetsApp extends StatefulWidget {
   /// To get this banner in your application if you're not using
   /// WidgetsApp, include a [CheckedModeBanner] widget in your app.
   ///
-  /// This banner is intended to avoid people complaining that your
+  /// This banner is intended to deter people from complaining that your
   /// app is slow when it's in checked mode. In checked mode, Flutter
   /// enables a large number of expensive diagnostics to aid in
   /// development, and so performance in checked mode is not
   /// representative of what will happen in release mode.
+  /// {@endtemplate}
   final bool debugShowCheckedModeBanner;
 
   /// If true, forces the performance overlay to be visible in all instances.

packages/flutter/test/cupertino/page_test.dart

@@ -8,8 +8,7 @@ import 'package:flutter_test/flutter_test.dart';
 void main() {
   testWidgets('test iOS page transition (LTR)', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
+      new CupertinoApp(
         onGenerateRoute: (RouteSettings settings) {
           return new CupertinoPageRoute<void>(
             settings: settings,
@@ -76,11 +75,10 @@ void main() {
 
   testWidgets('test iOS page transition (RTL)', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
+      new CupertinoApp(
         localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
           const RtlOverrideWidgetsDelegate(),
         ],
-        color: const Color(0xFFFFFFFF),
         onGenerateRoute: (RouteSettings settings) {
           return new CupertinoPageRoute<void>(
             settings: settings,
@@ -148,16 +146,8 @@ void main() {
 
   testWidgets('test iOS fullscreen dialog transition', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return const Center(child: const Text('Page 1'));
-            }
-          );
-        },
+      new CupertinoApp(
+        home: const Center(child: const Text('Page 1')),
       ),
     );
 
@@ -216,8 +206,7 @@ void main() {
 
   testWidgets('test only edge swipes work (LTR)', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
+      new CupertinoApp(
         onGenerateRoute: (RouteSettings settings) {
           return new CupertinoPageRoute<void>(
             settings: settings,
@@ -278,11 +267,10 @@ void main() {
 
   testWidgets('test only edge swipes work (RTL)', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
+      new CupertinoApp(
         localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
           const RtlOverrideWidgetsDelegate(),
         ],
-        color: const Color(0xFFFFFFFF),
         onGenerateRoute: (RouteSettings settings) {
           return new CupertinoPageRoute<void>(
             settings: settings,

packages/flutter/test/cupertino/scaffold_test.dart

@@ -11,22 +11,14 @@ import '../painting/mocks_for_image_cache.dart';
 void main() {
   testWidgets('Contents are behind translucent bar', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return const CupertinoPageScaffold(
+      new CupertinoApp(
+        home: const CupertinoPageScaffold(
           // Default nav bar is translucent.
           navigationBar: const CupertinoNavigationBar(
             middle: const Text('Title'),
           ),
           child: const Center(),
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -37,13 +29,8 @@ void main() {
     const Center page1Center = const Center();
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new CupertinoTabScaffold(
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
           tabBar: new CupertinoTabBar(
             backgroundColor: CupertinoColors.white,
             items: const <BottomNavigationBarItem>[
@@ -67,12 +54,9 @@ void main() {
                   child: page1Center,
                 )
                 : new Stack();
-                }
-              );
-            },
-          );
           },
         ),
+      ),
     );
 
     expect(tester.getSize(find.byWidget(page1Center)).height, 600.0 - 44.0 - 50.0);
@@ -82,13 +66,8 @@ void main() {
     final Container content = new Container(height: 600.0, width: 600.0);
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new MediaQuery(
+      new CupertinoApp(
+        home: new MediaQuery(
           data: const MediaQueryData(
             padding: const EdgeInsets.symmetric(vertical: 20.0),
           ),
@@ -120,10 +99,7 @@ void main() {
                   : new Stack();
             }
           ),
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -132,6 +108,8 @@ void main() {
 
     // Overscroll to the bottom.
     await tester.drag(find.byWidget(content), const Offset(0.0, -400.0));
+    // Let it bounce back.
+    await tester.pump();
     await tester.pump(const Duration(seconds: 1));
 
     // List content automatically padded by tab bar and bottom media query padding.
@@ -142,13 +120,8 @@ void main() {
     // A full on iOS information architecture app with 2 tabs, and 2 pages
     // in each with independent navigation states.
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new CupertinoTabScaffold(
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
           tabBar: new CupertinoTabBar(
             items: const <BottomNavigationBarItem>[
               const BottomNavigationBarItem(
@@ -200,10 +173,7 @@ void main() {
               },
             );
           },
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -257,18 +227,10 @@ void main() {
 
   testWidgets('Decorated with white background by default', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return const CupertinoPageScaffold(
+      new CupertinoApp(
+        home: const CupertinoPageScaffold(
           child: const Center(),
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -281,19 +243,11 @@ void main() {
 
   testWidgets('Overrides background color', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return const CupertinoPageScaffold(
+      new CupertinoApp(
+        home: const CupertinoPageScaffold(
           child: const Center(),
           backgroundColor: const Color(0xFF010203),
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 

packages/flutter/test/cupertino/tab_scaffold_test.dart

@@ -20,13 +20,8 @@ void main() {
     final List<int> tabsPainted = <int>[];
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new CupertinoTabScaffold(
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
           tabBar: _buildTabBar(),
           tabBuilder: (BuildContext context, int index) {
             return new CustomPaint(
@@ -36,10 +31,7 @@ void main() {
               )
             );
           },
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -82,22 +74,14 @@ void main() {
     final List<int> tabsBuilt = <int>[];
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new CupertinoTabScaffold(
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
           tabBar: _buildTabBar(),
           tabBuilder: (BuildContext context, int index) {
             tabsBuilt.add(index);
             return new Text('Page ${index + 1}');
           },
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -126,13 +110,8 @@ void main() {
     final List<FocusNode> focusNodes = <FocusNode>[new FocusNode(), new FocusNode()];
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new Material(
+      new CupertinoApp(
+        home: new Material(
           child: new CupertinoTabScaffold(
             tabBar: _buildTabBar(),
             tabBuilder: (BuildContext context, int index) {
@@ -142,10 +121,7 @@ void main() {
               );
             },
           ),
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -170,13 +146,8 @@ void main() {
     ];
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new Material(
+      new CupertinoApp(
+        home: new Material(
           child: new CupertinoTabScaffold(
             tabBar: _buildTabBar(),
             tabBuilder: (BuildContext context, int index) {
@@ -198,10 +169,7 @@ void main() {
               );
             },
           ),
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -242,10 +210,8 @@ void main() {
     final List<int> tabsPainted = <int>[];
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        builder: (BuildContext context, Widget child) {
-          return new CupertinoTabScaffold(
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
           tabBar: _buildTabBar(),
           tabBuilder: (BuildContext context, int index) {
             return new CustomPaint(
@@ -255,18 +221,15 @@ void main() {
               )
             );
           },
-          );
-        },
+        ),
       ),
     );
 
     expect(tabsPainted, <int>[0]);
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        builder: (BuildContext context, Widget child) {
-          return new CupertinoTabScaffold(
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
           tabBar: _buildTabBar(selectedTab: 1), // Programmatically change the tab now.
           tabBuilder: (BuildContext context, int index) {
             return new CustomPaint(
@@ -276,8 +239,7 @@ void main() {
               )
             );
           },
-          );
-        },
+        ),
       ),
     );
 

packages/flutter/test/cupertino/tab_test.dart

@@ -8,18 +8,10 @@ import 'package:flutter_test/flutter_test.dart';
 void main() {
   testWidgets('Use home', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new CupertinoTabView(
+      new CupertinoApp(
+        home: new CupertinoTabView(
           builder: (BuildContext context) => const Text('home'),
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -28,20 +20,12 @@ void main() {
 
   testWidgets('Use routes', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new CupertinoTabView(
+      new CupertinoApp(
+        home: new CupertinoTabView(
           routes: <String, WidgetBuilder>{
             '/': (BuildContext context) => const Text('first route'),
           },
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -50,13 +34,8 @@ void main() {
 
   testWidgets('Use home and named routes', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new CupertinoTabView(
+      new CupertinoApp(
+        home: new CupertinoTabView(
           builder: (BuildContext context) {
             return new CupertinoButton(
               child: const Text('go to second page'),
@@ -68,10 +47,7 @@ void main() {
           routes: <String, WidgetBuilder>{
             '/2': (BuildContext context) => const Text('second named route'),
           },
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -84,13 +60,8 @@ void main() {
 
   testWidgets('Use onGenerateRoute', (WidgetTester tester) async {
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new CupertinoTabView(
+      new CupertinoApp(
+        home: new CupertinoTabView(
           onGenerateRoute: (RouteSettings settings) {
             if (settings.name == Navigator.defaultRouteName) {
               return new CupertinoPageRoute<void>(
@@ -101,10 +72,7 @@ void main() {
               );
             }
           },
-              );
-            },
-          );
-        },
+        ),
       ),
     );
 
@@ -114,20 +82,12 @@ void main() {
   testWidgets('Use onUnknownRoute', (WidgetTester tester) async {
     String unknownForRouteCalled;
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        onGenerateRoute: (RouteSettings settings) {
-          return new CupertinoPageRoute<void>(
-            settings: settings,
-            builder: (BuildContext context) {
-              return new CupertinoTabView(
+      new CupertinoApp(
+        home: new CupertinoTabView(
           onUnknownRoute: (RouteSettings settings) {
             unknownForRouteCalled = settings.name;
           },
-              );
-            },
-          );
-        },
+        ),
       ),
     );