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

5
import 'package:flutter/cupertino.dart';
6

7
import 'page_transitions_theme.dart';
8
import 'theme.dart';
9

10 11
/// A modal route that replaces the entire screen with a platform-adaptive
/// transition.
12
///
13
/// {@macro flutter.material.materialRouteTransitionMixin}
14
///
15 16 17
/// By default, when a modal route is replaced by another, the previous route
/// remains in memory. To free all the resources when this is not necessary, set
/// [maintainState] to false.
18
///
19 20
/// The `fullscreenDialog` property specifies whether the incoming route is a
/// fullscreen modal dialog. On iOS, those routes animate from the bottom to the
21
/// top rather than horizontally.
22
///
23 24 25
/// If `barrierDismissible` is true, then pressing the escape key on the keyboard
/// will cause the current route to be popped with null as the value.
///
26
/// The type `T` specifies the return type of the route which can be supplied as
27 28
/// the route is popped from the stack via [Navigator.pop] by providing the
/// optional `result` argument.
29
///
30 31
/// See also:
///
32 33 34 35
///  * [MaterialRouteTransitionMixin], which provides the material transition
///    for this route.
///  * [MaterialPage], which is a [Page] of this class.
class MaterialPageRoute<T> extends PageRoute<T> with MaterialRouteTransitionMixin<T> {
36
  /// Construct a MaterialPageRoute whose contents are defined by [builder].
37
  MaterialPageRoute({
38
    required this.builder,
39
    super.settings,
40
    this.maintainState = true,
41
    super.fullscreenDialog,
42
    super.allowSnapshotting = true,
43
    super.barrierDismissible = false,
44
  }) {
45 46
    assert(opaque);
  }
47

48
  /// Builds the primary contents of the route.
49
  final WidgetBuilder builder;
Adam Barth's avatar
Adam Barth committed
50

51 52 53
  @override
  Widget buildContent(BuildContext context) => builder(context);

54 55 56
  @override
  final bool maintainState;

57 58 59 60 61 62 63 64
  @override
  String get debugLabel => '${super.debugLabel}(${settings.name})';
}


/// A mixin that provides platform-adaptive transitions for a [PageRoute].
///
/// {@template flutter.material.materialRouteTransitionMixin}
65 66 67
/// For Android, the entrance transition for the page zooms in and fades in
/// while the exiting page zooms out and fades out. The exit transition is similar,
/// but in reverse.
68
///
69 70 71 72
/// For iOS, the page slides in from the right and exits in reverse. The page
/// also shifts to the left in parallax when another page enters to cover it.
/// (These directions are flipped in environments with a right-to-left reading
/// direction.)
73 74 75 76 77 78
/// {@endtemplate}
///
/// See also:
///
///  * [PageTransitionsTheme], which defines the default page transitions used
///    by the [MaterialRouteTransitionMixin.buildTransitions].
79 80 81 82
///  * [ZoomPageTransitionsBuilder], which is the default page transition used
///    by the [PageTransitionsTheme].
///  * [CupertinoPageTransitionsBuilder], which is the default page transition
///    for iOS and macOS.
83 84
mixin MaterialRouteTransitionMixin<T> on PageRoute<T> {
  /// Builds the primary contents of the route.
85 86
  @protected
  Widget buildContent(BuildContext context);
87

88
  @override
89
  Duration get transitionDuration => const Duration(milliseconds: 300);
90 91

  @override
92
  Color? get barrierColor => null;
93

94
  @override
95
  String? get barrierLabel => null;
96

97 98 99
  @override
  bool canTransitionTo(TransitionRoute<dynamic> nextRoute) {
    // Don't perform outgoing animation if the next route is a fullscreen dialog.
100 101
    return (nextRoute is MaterialRouteTransitionMixin && !nextRoute.fullscreenDialog)
      || (nextRoute is CupertinoRouteTransitionMixin && !nextRoute.fullscreenDialog);
102 103
  }

104
  @override
105 106 107 108 109
  Widget buildPage(
    BuildContext context,
    Animation<double> animation,
    Animation<double> secondaryAnimation,
  ) {
110
    final Widget result = buildContent(context);
111 112 113 114 115
    return Semantics(
      scopesRoute: true,
      explicitChildNodes: true,
      child: result,
    );
116 117
  }

118
  @override
119
  Widget buildTransitions(BuildContext context, Animation<double> animation, Animation<double> secondaryAnimation, Widget child) {
120 121
    final PageTransitionsTheme theme = Theme.of(context).pageTransitionsTheme;
    return theme.buildTransitions<T>(this, context, animation, secondaryAnimation, child);
122
  }
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
}

/// A page that creates a material style [PageRoute].
///
/// {@macro flutter.material.materialRouteTransitionMixin}
///
/// By default, when the created route is replaced by another, the previous
/// route remains in memory. To free all the resources when this is not
/// necessary, set [maintainState] to false.
///
/// The `fullscreenDialog` property specifies whether the created route is a
/// fullscreen modal dialog. On iOS, those routes animate from the bottom to the
/// top rather than horizontally.
///
/// The type `T` specifies the return type of the route which can be supplied as
/// the route is popped from the stack via [Navigator.transitionDelegate] by
/// providing the optional `result` argument to the
/// [RouteTransitionRecord.markForPop] in the [TransitionDelegate.resolve].
///
/// See also:
///
///  * [MaterialPageRoute], which is the [PageRoute] version of this class
class MaterialPage<T> extends Page<T> {
  /// Creates a material page.
  const MaterialPage({
148
    required this.child,
149 150
    this.maintainState = true,
    this.fullscreenDialog = false,
151
    this.allowSnapshotting = true,
152 153 154 155
    super.key,
    super.name,
    super.arguments,
    super.restorationId,
156
  });
157

158 159
  /// The content to be shown in the [Route] created by this page.
  final Widget child;
160

161
  /// {@macro flutter.widgets.ModalRoute.maintainState}
162 163
  final bool maintainState;

164
  /// {@macro flutter.widgets.PageRoute.fullscreenDialog}
165
  final bool fullscreenDialog;
166

167 168
  /// {@macro flutter.widgets.TransitionRoute.allowSnapshotting}
  final bool allowSnapshotting;
169

170
  @override
171
  Route<T> createRoute(BuildContext context) {
172
    return _PageBasedMaterialPageRoute<T>(page: this, allowSnapshotting: allowSnapshotting);
173 174 175 176 177 178 179 180 181
  }
}

// A page-based version of MaterialPageRoute.
//
// This route uses the builder from the page to build its content. This ensures
// the content is up to date after page updates.
class _PageBasedMaterialPageRoute<T> extends PageRoute<T> with MaterialRouteTransitionMixin<T> {
  _PageBasedMaterialPageRoute({
182
    required MaterialPage<T> page,
183
    super.allowSnapshotting,
184
  }) : super(settings: page) {
185 186
    assert(opaque);
  }
187 188 189 190

  MaterialPage<T> get _page => settings as MaterialPage<T>;

  @override
191 192 193
  Widget buildContent(BuildContext context) {
    return _page.child;
  }
194 195 196 197 198 199 200 201 202

  @override
  bool get maintainState => _page.maintainState;

  @override
  bool get fullscreenDialog => _page.fullscreenDialog;

  @override
  String get debugLabel => '${super.debugLabel}(${_page.name})';
203
}