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/tab_scaffold_test.dart

@@ -20,26 +20,18 @@ 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(
-                tabBar: _buildTabBar(),
-                tabBuilder: (BuildContext context, int index) {
-                  return new CustomPaint(
-                    child: new Text('Page ${index + 1}'),
-                    painter: new TestCallbackPainter(
-                      onPaint: () { tabsPainted.add(index); }
-                    )
-                  );
-                },
-              );
-            },
-          );
-        },
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
+          tabBar: _buildTabBar(),
+          tabBuilder: (BuildContext context, int index) {
+            return new CustomPaint(
+              child: new Text('Page ${index + 1}'),
+              painter: new TestCallbackPainter(
+                onPaint: () { tabsPainted.add(index); }
+              )
+            );
+          },
+        ),
       ),
     );
 
@@ -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(
-                tabBar: _buildTabBar(),
-                tabBuilder: (BuildContext context, int index) {
-                  tabsBuilt.add(index);
-                  return new Text('Page ${index + 1}');
-                },
-              );
-            },
-          );
-        },
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
+          tabBar: _buildTabBar(),
+          tabBuilder: (BuildContext context, int index) {
+            tabsBuilt.add(index);
+            return new Text('Page ${index + 1}');
+          },
+        ),
       ),
     );
 
@@ -126,26 +110,18 @@ 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(
-                child: new CupertinoTabScaffold(
-                  tabBar: _buildTabBar(),
-                  tabBuilder: (BuildContext context, int index) {
-                    return new TextField(
-                      focusNode: focusNodes[index],
-                      autofocus: true,
-                    );
-                  },
-                ),
+      new CupertinoApp(
+        home: new Material(
+          child: new CupertinoTabScaffold(
+            tabBar: _buildTabBar(),
+            tabBuilder: (BuildContext context, int index) {
+              return new TextField(
+                focusNode: focusNodes[index],
+                autofocus: true,
               );
             },
-          );
-        },
+          ),
+        ),
       ),
     );
 
@@ -170,38 +146,30 @@ 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(
-                child: new CupertinoTabScaffold(
-                  tabBar: _buildTabBar(),
-                  tabBuilder: (BuildContext context, int index) {
-                    return new Column(
-                      children: <Widget>[
-                        new TextField(
-                          focusNode: focusNodes[index * 2],
-                          decoration: const InputDecoration(
-                            hintText: 'TextField 1',
-                          ),
-                        ),
-                        new TextField(
-                          focusNode: focusNodes[index * 2 + 1],
-                          decoration: const InputDecoration(
-                            hintText: 'TextField 2',
-                          ),
-                        ),
-                      ],
-                    );
-                  },
-                ),
+      new CupertinoApp(
+        home: new Material(
+          child: new CupertinoTabScaffold(
+            tabBar: _buildTabBar(),
+            tabBuilder: (BuildContext context, int index) {
+              return new Column(
+                children: <Widget>[
+                  new TextField(
+                    focusNode: focusNodes[index * 2],
+                    decoration: const InputDecoration(
+                      hintText: 'TextField 1',
+                    ),
+                  ),
+                  new TextField(
+                    focusNode: focusNodes[index * 2 + 1],
+                    decoration: const InputDecoration(
+                      hintText: 'TextField 2',
+                    ),
+                  ),
+                ],
               );
             },
-          );
-        },
+          ),
+        ),
       ),
     );
 
@@ -242,42 +210,36 @@ void main() {
     final List<int> tabsPainted = <int>[];
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        builder: (BuildContext context, Widget child) {
-          return new CupertinoTabScaffold(
-            tabBar: _buildTabBar(),
-            tabBuilder: (BuildContext context, int index) {
-              return new CustomPaint(
-                child: new Text('Page ${index + 1}'),
-                painter: new TestCallbackPainter(
-                  onPaint: () { tabsPainted.add(index); }
-                )
-              );
-            },
-          );
-        },
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
+          tabBar: _buildTabBar(),
+          tabBuilder: (BuildContext context, int index) {
+            return new CustomPaint(
+              child: new Text('Page ${index + 1}'),
+              painter: new TestCallbackPainter(
+                onPaint: () { tabsPainted.add(index); }
+              )
+            );
+          },
+        ),
       ),
     );
 
     expect(tabsPainted, <int>[0]);
 
     await tester.pumpWidget(
-      new WidgetsApp(
-        color: const Color(0xFFFFFFFF),
-        builder: (BuildContext context, Widget child) {
-          return new CupertinoTabScaffold(
-            tabBar: _buildTabBar(selectedTab: 1), // Programmatically change the tab now.
-            tabBuilder: (BuildContext context, int index) {
-              return new CustomPaint(
-                child: new Text('Page ${index + 1}'),
-                painter: new TestCallbackPainter(
-                  onPaint: () { tabsPainted.add(index); }
-                )
-              );
-            },
-          );
-        },
+      new CupertinoApp(
+        home: new CupertinoTabScaffold(
+          tabBar: _buildTabBar(selectedTab: 1), // Programmatically change the tab now.
+          tabBuilder: (BuildContext context, int index) {
+            return new CustomPaint(
+              child: new Text('Page ${index + 1}'),
+              painter: new TestCallbackPainter(
+                onPaint: () { tabsPainted.add(index); }
+              )
+            );
+          },
+        ),
       ),
     );
 

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(
-                builder: (BuildContext context) => const Text('home'),
-              );
-            },
-          );
-        },
+      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(
-                routes: <String, WidgetBuilder>{
-                  '/': (BuildContext context) => const Text('first route'),
-                },
-              );
-            },
-          );
-        },
+      new CupertinoApp(
+        home: new CupertinoTabView(
+          routes: <String, WidgetBuilder>{
+            '/': (BuildContext context) => const Text('first route'),
+          },
+        ),
       ),
     );
 
@@ -50,28 +34,20 @@ 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(
-                builder: (BuildContext context) {
-                  return new CupertinoButton(
-                    child: const Text('go to second page'),
-                    onPressed: () {
-                      Navigator.of(context).pushNamed('/2');
-                    },
-                  );
-                },
-                routes: <String, WidgetBuilder>{
-                  '/2': (BuildContext context) => const Text('second named route'),
-                },
-              );
-            },
-          );
-        },
+      new CupertinoApp(
+        home: new CupertinoTabView(
+          builder: (BuildContext context) {
+            return new CupertinoButton(
+              child: const Text('go to second page'),
+              onPressed: () {
+                Navigator.of(context).pushNamed('/2');
+              },
+            );
+          },
+          routes: <String, WidgetBuilder>{
+            '/2': (BuildContext context) => const Text('second named route'),
+          },
+        ),
       ),
     );
 
@@ -84,27 +60,19 @@ 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(
-                onGenerateRoute: (RouteSettings settings) {
-                  if (settings.name == Navigator.defaultRouteName) {
-                    return new CupertinoPageRoute<void>(
-                      settings: settings,
-                      builder: (BuildContext context) {
-                        return const Text('generated home');
-                      }
-                    );
-                  }
-                },
+      new CupertinoApp(
+        home: new CupertinoTabView(
+          onGenerateRoute: (RouteSettings settings) {
+            if (settings.name == Navigator.defaultRouteName) {
+              return new CupertinoPageRoute<void>(
+                settings: settings,
+                builder: (BuildContext context) {
+                  return const Text('generated home');
+                }
               );
-            },
-          );
-        },
+            }
+          },
+        ),
       ),
     );
 
@@ -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(
-                onUnknownRoute: (RouteSettings settings) {
-                  unknownForRouteCalled = settings.name;
-                },
-              );
-            },
-          );
-        },
+      new CupertinoApp(
+        home: new CupertinoTabView(
+          onUnknownRoute: (RouteSettings settings) {
+            unknownForRouteCalled = settings.name;
+          },
+        ),
       ),
     );