app.dart 18.9 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
xster's avatar
xster committed
2 3 4 5 6 7 8 9
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'package:flutter/widgets.dart';

import 'button.dart';
import 'colors.dart';
import 'icons.dart';
10
import 'interface_level.dart';
11
import 'localizations.dart';
12
import 'route.dart';
xster's avatar
xster committed
13
import 'theme.dart';
xster's avatar
xster committed
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36

/// An application that uses Cupertino design.
///
/// A convenience widget that wraps a number of widgets that are commonly
/// required for an iOS-design targeting application. It builds upon a
/// [WidgetsApp] by iOS specific defaulting such as fonts and scrolling
/// physics.
///
/// The [CupertinoApp] configures the top-level [Navigator] to search for routes
/// in the following order:
///
///  1. For the `/` route, the [home] property, if non-null, is used.
///
///  2. Otherwise, the [routes] table is used, if it has an entry for the route.
///
///  3. Otherwise, [onGenerateRoute] is called, if provided. It should return a
///     non-null value for any _valid_ route not handled by [home] and [routes].
///
///  4. Finally if all else fails [onUnknownRoute] is called.
///
/// If [home], [routes], [onGenerateRoute], and [onUnknownRoute] are all null,
/// and [builder] is not null, then no [Navigator] is created.
///
37 38 39
/// This widget also configures the observer of the top-level [Navigator] (if
/// any) to perform [Hero] animations.
///
Sigurd Meldgaard's avatar
Sigurd Meldgaard committed
40
/// Use this widget with caution on Android since it may produce behaviors
xster's avatar
xster committed
41 42 43 44 45 46 47
/// Android users are not expecting such as:
///
///  * Pages will be dismissible via a back swipe.
///  * Scrolling past extremities will trigger iOS-style spring overscrolls.
///  * The San Francisco font family is unavailable on Android and can result
///    in undefined font behavior.
///
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
/// {@tool snippet}
/// This example shows how to create a [CupertinoApp] that disables the "debug"
/// banner with a [home] route that will be displayed when the app is launched.
///
/// ![The CupertinoApp displays a CupertinoPageScaffold](https://flutter.github.io/assets-for-api-docs/assets/cupertino/basic_cupertino_app.png)
///
/// ```dart
/// CupertinoApp(
///   home: CupertinoPageScaffold(
///     navigationBar: CupertinoNavigationBar(
///       middle: const Text('Home'),
///     ),
///     child: Center(child: Icon(CupertinoIcons.share)),
///   ),
///   debugShowCheckedModeBanner: false,
/// )
/// ```
/// {@end-tool}
///
/// {@tool snippet}
/// This example shows how to create a [CupertinoApp] that uses the [routes]
/// `Map` to define the "home" route and an "about" route.
///
/// ```dart
/// CupertinoApp(
///   routes: <String, WidgetBuilder>{
///     '/': (BuildContext context) {
///       return CupertinoPageScaffold(
///         navigationBar: CupertinoNavigationBar(
///           middle: const Text('Home Route'),
///         ),
///         child: Center(child: Icon(CupertinoIcons.share)),
///       );
///     },
///     '/about': (BuildContext context) {
///       return CupertinoPageScaffold(
///         navigationBar: CupertinoNavigationBar(
///           middle: const Text('About Route'),
///         ),
///         child: Center(child: Icon(CupertinoIcons.share)),
///       );
///     }
///   },
/// )
/// ```
/// {@end-tool}
///
/// {@tool snippet}
/// This example shows how to create a [CupertinoApp] that defines a [theme] that
/// will be used for Cupertino widgets in the app.
///
/// ![The CupertinoApp displays a CupertinoPageScaffold with orange-colored icons](https://flutter.github.io/assets-for-api-docs/assets/cupertino/theme_cupertino_app.png)
///
/// ```dart
/// CupertinoApp(
///   theme: CupertinoThemeData(
///     brightness: Brightness.dark,
///     primaryColor: CupertinoColors.systemOrange,
///   ),
///   home: CupertinoPageScaffold(
///     navigationBar: CupertinoNavigationBar(
///       middle: const Text('CupertinoApp Theme'),
///     ),
///     child: Center(child: Icon(CupertinoIcons.share)),
///   ),
/// )
/// ```
/// {@end-tool}
///
xster's avatar
xster committed
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
/// See also:
///
///  * [CupertinoPageScaffold], which provides a standard page layout default
///    with nav bars.
///  * [Navigator], which is used to manage the app's stack of pages.
///  * [CupertinoPageRoute], which defines an app page that transitions in an
///    iOS-specific way.
///  * [WidgetsApp], which defines the basic app elements but does not depend
///    on the Cupertino library.
class CupertinoApp extends StatefulWidget {
  /// Creates a CupertinoApp.
  ///
  /// At least one of [home], [routes], [onGenerateRoute], or [builder] must be
  /// non-null. If only [routes] is given, it must include an entry for the
  /// [Navigator.defaultRouteName] (`/`), since that is the route used when the
  /// application is launched with an intent that specifies an otherwise
  /// unsupported route.
  ///
  /// This class creates an instance of [WidgetsApp].
  ///
  /// The boolean arguments, [routes], and [navigatorObservers], must not be null.
138
  const CupertinoApp({
139
    Key? key,
140
    this.navigatorKey,
xster's avatar
xster committed
141
    this.home,
xster's avatar
xster committed
142
    this.theme,
143
    Map<String, Widget Function(BuildContext)> this.routes = const <String, WidgetBuilder>{},
xster's avatar
xster committed
144 145
    this.initialRoute,
    this.onGenerateRoute,
146
    this.onGenerateInitialRoutes,
xster's avatar
xster committed
147
    this.onUnknownRoute,
148
    List<NavigatorObserver> this.navigatorObservers = const <NavigatorObserver>[],
xster's avatar
xster committed
149 150 151 152 153 154
    this.builder,
    this.title = '',
    this.onGenerateTitle,
    this.color,
    this.locale,
    this.localizationsDelegates,
155
    this.localeListResolutionCallback,
xster's avatar
xster committed
156
    this.localeResolutionCallback,
157
    this.supportedLocales = const <Locale>[Locale('en', 'US')],
xster's avatar
xster committed
158 159 160 161 162
    this.showPerformanceOverlay = false,
    this.checkerboardRasterCacheImages = false,
    this.checkerboardOffscreenLayers = false,
    this.showSemanticsDebugger = false,
    this.debugShowCheckedModeBanner = true,
163 164
    this.shortcuts,
    this.actions,
165
    this.restorationScopeId,
xster's avatar
xster committed
166 167 168 169 170 171 172 173
  }) : assert(routes != null),
       assert(navigatorObservers != null),
       assert(title != null),
       assert(showPerformanceOverlay != null),
       assert(checkerboardRasterCacheImages != null),
       assert(checkerboardOffscreenLayers != null),
       assert(showSemanticsDebugger != null),
       assert(debugShowCheckedModeBanner != null),
174 175 176 177 178 179 180 181
       routeInformationProvider = null,
       routeInformationParser = null,
       routerDelegate = null,
       backButtonDispatcher = null,
       super(key: key);

  /// Creates a [CupertinoApp] that uses the [Router] instead of a [Navigator].
  const CupertinoApp.router({
182
    Key? key,
183
    this.routeInformationProvider,
184 185
    required RouteInformationParser<Object> this.routeInformationParser,
    required RouterDelegate<Object> this.routerDelegate,
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
    this.backButtonDispatcher,
    this.theme,
    this.builder,
    this.title = '',
    this.onGenerateTitle,
    this.color,
    this.locale,
    this.localizationsDelegates,
    this.localeListResolutionCallback,
    this.localeResolutionCallback,
    this.supportedLocales = const <Locale>[Locale('en', 'US')],
    this.showPerformanceOverlay = false,
    this.checkerboardRasterCacheImages = false,
    this.checkerboardOffscreenLayers = false,
    this.showSemanticsDebugger = false,
    this.debugShowCheckedModeBanner = true,
    this.shortcuts,
    this.actions,
204
    this.restorationScopeId,
205 206 207 208 209 210 211 212 213 214 215 216 217 218
  }) : assert(title != null),
       assert(showPerformanceOverlay != null),
       assert(checkerboardRasterCacheImages != null),
       assert(checkerboardOffscreenLayers != null),
       assert(showSemanticsDebugger != null),
       assert(debugShowCheckedModeBanner != null),
       navigatorObservers = null,
       navigatorKey = null,
       onGenerateRoute = null,
       home = null,
       onGenerateInitialRoutes = null,
       onUnknownRoute = null,
       routes = null,
       initialRoute = null,
xster's avatar
xster committed
219 220
       super(key: key);

221
  /// {@macro flutter.widgets.widgetsApp.navigatorKey}
222
  final GlobalKey<NavigatorState>? navigatorKey;
223 224

  /// {@macro flutter.widgets.widgetsApp.home}
225
  final Widget? home;
xster's avatar
xster committed
226

xster's avatar
xster committed
227 228 229 230
  /// The top-level [CupertinoTheme] styling.
  ///
  /// A null [theme] or unspecified [theme] attributes will default to iOS
  /// system values.
231
  final CupertinoThemeData? theme;
xster's avatar
xster committed
232

xster's avatar
xster committed
233 234 235 236 237
  /// The application's top-level routing table.
  ///
  /// When a named route is pushed with [Navigator.pushNamed], the route name is
  /// looked up in this map. If the name is present, the associated
  /// [WidgetBuilder] is used to construct a [CupertinoPageRoute] that performs
238
  /// an appropriate transition, including [Hero] animations, to the new route.
xster's avatar
xster committed
239
  ///
240
  /// {@macro flutter.widgets.widgetsApp.routes}
241
  final Map<String, WidgetBuilder>? routes;
xster's avatar
xster committed
242 243

  /// {@macro flutter.widgets.widgetsApp.initialRoute}
244
  final String? initialRoute;
xster's avatar
xster committed
245 246

  /// {@macro flutter.widgets.widgetsApp.onGenerateRoute}
247
  final RouteFactory? onGenerateRoute;
xster's avatar
xster committed
248

249
  /// {@macro flutter.widgets.widgetsApp.onGenerateInitialRoutes}
250
  final InitialRouteListFactory? onGenerateInitialRoutes;
251

xster's avatar
xster committed
252
  /// {@macro flutter.widgets.widgetsApp.onUnknownRoute}
253
  final RouteFactory? onUnknownRoute;
xster's avatar
xster committed
254 255

  /// {@macro flutter.widgets.widgetsApp.navigatorObservers}
256
  final List<NavigatorObserver>? navigatorObservers;
xster's avatar
xster committed
257

258
  /// {@macro flutter.widgets.widgetsApp.routeInformationProvider}
259
  final RouteInformationProvider? routeInformationProvider;
260 261

  /// {@macro flutter.widgets.widgetsApp.routeInformationParser}
262
  final RouteInformationParser<Object>? routeInformationParser;
263 264

  /// {@macro flutter.widgets.widgetsApp.routerDelegate}
265
  final RouterDelegate<Object>? routerDelegate;
266 267

  /// {@macro flutter.widgets.widgetsApp.backButtonDispatcher}
268
  final BackButtonDispatcher? backButtonDispatcher;
269

xster's avatar
xster committed
270
  /// {@macro flutter.widgets.widgetsApp.builder}
271
  final TransitionBuilder? builder;
xster's avatar
xster committed
272 273 274 275 276 277 278 279 280

  /// {@macro flutter.widgets.widgetsApp.title}
  ///
  /// This value is passed unmodified to [WidgetsApp.title].
  final String title;

  /// {@macro flutter.widgets.widgetsApp.onGenerateTitle}
  ///
  /// This value is passed unmodified to [WidgetsApp.onGenerateTitle].
281
  final GenerateAppTitle? onGenerateTitle;
xster's avatar
xster committed
282 283

  /// {@macro flutter.widgets.widgetsApp.color}
284
  final Color? color;
xster's avatar
xster committed
285 286

  /// {@macro flutter.widgets.widgetsApp.locale}
287
  final Locale? locale;
xster's avatar
xster committed
288 289

  /// {@macro flutter.widgets.widgetsApp.localizationsDelegates}
290
  final Iterable<LocalizationsDelegate<dynamic>>? localizationsDelegates;
xster's avatar
xster committed
291

292 293 294
  /// {@macro flutter.widgets.widgetsApp.localeListResolutionCallback}
  ///
  /// This callback is passed along to the [WidgetsApp] built by this widget.
295
  final LocaleListResolutionCallback? localeListResolutionCallback;
296

297
  /// {@macro flutter.widgets.LocaleResolutionCallback}
xster's avatar
xster committed
298 299
  ///
  /// This callback is passed along to the [WidgetsApp] built by this widget.
300
  final LocaleResolutionCallback? localeResolutionCallback;
xster's avatar
xster committed
301 302 303 304 305 306 307 308 309 310

  /// {@macro flutter.widgets.widgetsApp.supportedLocales}
  ///
  /// It is passed along unmodified to the [WidgetsApp] built by this widget.
  final Iterable<Locale> supportedLocales;

  /// Turns on a performance overlay.
  ///
  /// See also:
  ///
311
  ///  * <https://flutter.dev/debugging/#performanceoverlay>
xster's avatar
xster committed
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
  final bool showPerformanceOverlay;

  /// Turns on checkerboarding of raster cache images.
  final bool checkerboardRasterCacheImages;

  /// Turns on checkerboarding of layers rendered to offscreen bitmaps.
  final bool checkerboardOffscreenLayers;

  /// Turns on an overlay that shows the accessibility information
  /// reported by the framework.
  final bool showSemanticsDebugger;

  /// {@macro flutter.widgets.widgetsApp.debugShowCheckedModeBanner}
  final bool debugShowCheckedModeBanner;

327
  /// {@macro flutter.widgets.widgetsApp.shortcuts}
328
  /// {@tool snippet}
329 330 331 332 333 334 335 336 337 338 339 340 341
  /// This example shows how to add a single shortcut for
  /// [LogicalKeyboardKey.select] to the default shortcuts without needing to
  /// add your own [Shortcuts] widget.
  ///
  /// Alternatively, you could insert a [Shortcuts] widget with just the mapping
  /// you want to add between the [WidgetsApp] and its child and get the same
  /// effect.
  ///
  /// ```dart
  /// Widget build(BuildContext context) {
  ///   return WidgetsApp(
  ///     shortcuts: <LogicalKeySet, Intent>{
  ///       ... WidgetsApp.defaultShortcuts,
342
  ///       LogicalKeySet(LogicalKeyboardKey.select): const ActivateIntent(),
343 344
  ///     },
  ///     color: const Color(0xFFFF0000),
345
  ///     builder: (BuildContext context, Widget? child) {
346 347 348 349 350 351 352
  ///       return const Placeholder();
  ///     },
  ///   );
  /// }
  /// ```
  /// {@end-tool}
  /// {@macro flutter.widgets.widgetsApp.shortcuts.seeAlso}
353
  final Map<LogicalKeySet, Intent>? shortcuts;
354 355

  /// {@macro flutter.widgets.widgetsApp.actions}
356
  /// {@tool snippet}
357 358 359 360 361 362 363 364 365 366 367
  /// This example shows how to add a single action handling an
  /// [ActivateAction] to the default actions without needing to
  /// add your own [Actions] widget.
  ///
  /// Alternatively, you could insert a [Actions] widget with just the mapping
  /// you want to add between the [WidgetsApp] and its child and get the same
  /// effect.
  ///
  /// ```dart
  /// Widget build(BuildContext context) {
  ///   return WidgetsApp(
368
  ///     actions: <Type, Action<Intent>>{
369
  ///       ... WidgetsApp.defaultActions,
370 371
  ///       ActivateAction: CallbackAction(
  ///         onInvoke: (Intent intent) {
372
  ///           // Do something here...
373
  ///           return null;
374 375 376 377
  ///         },
  ///       ),
  ///     },
  ///     color: const Color(0xFFFF0000),
378
  ///     builder: (BuildContext context, Widget? child) {
379 380 381 382 383 384 385
  ///       return const Placeholder();
  ///     },
  ///   );
  /// }
  /// ```
  /// {@end-tool}
  /// {@macro flutter.widgets.widgetsApp.actions.seeAlso}
386
  final Map<Type, Action<Intent>>? actions;
387

388 389 390
  /// {@macro flutter.widgets.widgetsApp.restorationScopeId}
  final String? restorationScopeId;

xster's avatar
xster committed
391
  @override
392
  _CupertinoAppState createState() => _CupertinoAppState();
393 394 395 396 397 398

  /// The [HeroController] used for Cupertino page transitions.
  ///
  /// Used by [CupertinoTabView] and [CupertinoApp].
  static HeroController createCupertinoHeroController() =>
      HeroController(); // Linear tweening.
xster's avatar
xster committed
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414
}

class _AlwaysCupertinoScrollBehavior extends ScrollBehavior {
  @override
  Widget buildViewportChrome(BuildContext context, Widget child, AxisDirection axisDirection) {
    // Never build any overscroll glow indicators.
    return child;
  }

  @override
  ScrollPhysics getScrollPhysics(BuildContext context) {
    return const BouncingScrollPhysics();
  }
}

class _CupertinoAppState extends State<CupertinoApp> {
415
  late HeroController _heroController;
416
  bool get _usesRouter => widget.routerDelegate != null;
417

xster's avatar
xster committed
418 419 420
  @override
  void initState() {
    super.initState();
421
    _heroController = CupertinoApp.createCupertinoHeroController();
xster's avatar
xster committed
422 423
  }

424 425 426 427 428 429 430
  // Combine the default localization for Cupertino with the ones contributed
  // by the localizationsDelegates parameter, if any. Only the first delegate
  // of a particular LocalizationsDelegate.type is loaded so the
  // localizationsDelegate parameter can be used to override
  // _CupertinoLocalizationsDelegate.
  Iterable<LocalizationsDelegate<dynamic>> get _localizationsDelegates sync* {
    if (widget.localizationsDelegates != null)
431
      yield* widget.localizationsDelegates!;
432 433 434
    yield DefaultCupertinoLocalizations.delegate;
  }

435 436 437 438 439 440 441 442 443 444 445 446 447 448
  Widget _inspectorSelectButtonBuilder(BuildContext context, VoidCallback onPressed) {
    return CupertinoButton.filled(
      child: const Icon(
        CupertinoIcons.search,
        size: 28.0,
        color: CupertinoColors.white,
      ),
      padding: EdgeInsets.zero,
      onPressed: onPressed,
    );
  }

  WidgetsApp _buildWidgetApp(BuildContext context) {
    final CupertinoThemeData effectiveThemeData = CupertinoTheme.of(context);
449
    final Color color = CupertinoDynamicColor.resolve(widget.color ?? effectiveThemeData.primaryColor, context);
450 451 452 453 454

    if (_usesRouter) {
      return WidgetsApp.router(
        key: GlobalObjectKey(this),
        routeInformationProvider: widget.routeInformationProvider,
455 456
        routeInformationParser: widget.routeInformationParser!,
        routerDelegate: widget.routerDelegate!,
457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475
        backButtonDispatcher: widget.backButtonDispatcher,
        builder: widget.builder,
        title: widget.title,
        onGenerateTitle: widget.onGenerateTitle,
        textStyle: effectiveThemeData.textTheme.textStyle,
        color: color,
        locale: widget.locale,
        localizationsDelegates: _localizationsDelegates,
        localeResolutionCallback: widget.localeResolutionCallback,
        localeListResolutionCallback: widget.localeListResolutionCallback,
        supportedLocales: widget.supportedLocales,
        showPerformanceOverlay: widget.showPerformanceOverlay,
        checkerboardRasterCacheImages: widget.checkerboardRasterCacheImages,
        checkerboardOffscreenLayers: widget.checkerboardOffscreenLayers,
        showSemanticsDebugger: widget.showSemanticsDebugger,
        debugShowCheckedModeBanner: widget.debugShowCheckedModeBanner,
        inspectorSelectButtonBuilder: _inspectorSelectButtonBuilder,
        shortcuts: widget.shortcuts,
        actions: widget.actions,
476
        restorationScopeId: widget.restorationScopeId,
477 478 479 480 481
      );
    }
    return WidgetsApp(
      key: GlobalObjectKey(this),
      navigatorKey: widget.navigatorKey,
482
      navigatorObservers: widget.navigatorObservers!,
483 484 485 486
      pageRouteBuilder: <T>(RouteSettings settings, WidgetBuilder builder) {
        return CupertinoPageRoute<T>(settings: settings, builder: builder);
      },
      home: widget.home,
487
      routes: widget.routes!,
488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509
      initialRoute: widget.initialRoute,
      onGenerateRoute: widget.onGenerateRoute,
      onGenerateInitialRoutes: widget.onGenerateInitialRoutes,
      onUnknownRoute: widget.onUnknownRoute,
      builder: widget.builder,
      title: widget.title,
      onGenerateTitle: widget.onGenerateTitle,
      textStyle: effectiveThemeData.textTheme.textStyle,
      color: color,
      locale: widget.locale,
      localizationsDelegates: _localizationsDelegates,
      localeResolutionCallback: widget.localeResolutionCallback,
      localeListResolutionCallback: widget.localeListResolutionCallback,
      supportedLocales: widget.supportedLocales,
      showPerformanceOverlay: widget.showPerformanceOverlay,
      checkerboardRasterCacheImages: widget.checkerboardRasterCacheImages,
      checkerboardOffscreenLayers: widget.checkerboardOffscreenLayers,
      showSemanticsDebugger: widget.showSemanticsDebugger,
      debugShowCheckedModeBanner: widget.debugShowCheckedModeBanner,
      inspectorSelectButtonBuilder: _inspectorSelectButtonBuilder,
      shortcuts: widget.shortcuts,
      actions: widget.actions,
510
      restorationScopeId: widget.restorationScopeId,
511 512 513
    );
  }

xster's avatar
xster committed
514 515
  @override
  Widget build(BuildContext context) {
xster's avatar
xster committed
516 517
    final CupertinoThemeData effectiveThemeData = widget.theme ?? const CupertinoThemeData();

518 519
    return ScrollConfiguration(
      behavior: _AlwaysCupertinoScrollBehavior(),
520 521 522 523
      child: CupertinoUserInterfaceLevel(
        data: CupertinoUserInterfaceLevelData.base,
        child: CupertinoTheme(
          data: effectiveThemeData,
524 525 526 527 528
          child: HeroControllerScope(
            controller: _heroController,
            child: Builder(
              builder: _buildWidgetApp,
            ),
529
          ),
xster's avatar
xster committed
530
        ),
xster's avatar
xster committed
531 532 533 534
      ),
    );
  }
}