From 44ecd80358821e3e3a1719d36e9890b496cef67e Mon Sep 17 00:00:00 2001 From: Adam Barth Date: Mon, 7 Mar 2016 20:54:45 -0800 Subject: [PATCH] More dartdoc for routes.dart --- packages/flutter/lib/src/widgets/routes.dart | 102 ++++++++++++++++++- 1 file changed, 99 insertions(+), 3 deletions(-) diff --git a/packages/flutter/lib/src/widgets/routes.dart b/packages/flutter/lib/src/widgets/routes.dart index 09ea237496..e412fa08b2 100644 --- a/packages/flutter/lib/src/widgets/routes.dart +++ b/packages/flutter/lib/src/widgets/routes.dart @@ -63,6 +63,7 @@ abstract class OverlayRoute extends Route { } } +/// A route with entrance and exit transitions. abstract class TransitionRoute extends OverlayRoute { TransitionRoute({ Completer popCompleter, @@ -70,6 +71,7 @@ abstract class TransitionRoute extends OverlayRoute { }) : _popCompleter = popCompleter, _transitionCompleter = transitionCompleter; + /// The same as the default constructor but callable with mixins. TransitionRoute.explicit( Completer popCompleter, Completer transitionCompleter @@ -87,9 +89,17 @@ abstract class TransitionRoute extends OverlayRoute { Future get completed => _transitionCompleter?.future; final Completer _transitionCompleter; + /// The duration the transition lasts. Duration get transitionDuration; + + /// Whether the route obscures previous routes when the transition is complete. + /// + /// When an opaque route's entrance transition is complete, the routes behind + /// the opaque route will not be built to save resources. bool get opaque; + /// The animation that drives the route's transition and the previous route's + /// forward transition. Animation get animation => _animation; Animation _animation; AnimationController _controller; @@ -113,7 +123,7 @@ abstract class TransitionRoute extends OverlayRoute { T _result; - void handleStatusChanged(AnimationStatus status) { + void _handleStatusChanged(AnimationStatus status) { switch (status) { case AnimationStatus.completed: if (overlayEntries.isNotEmpty) @@ -144,7 +154,7 @@ abstract class TransitionRoute extends OverlayRoute { } void didPush() { - _animation.addStatusListener(handleStatusChanged); + _animation.addStatusListener(_handleStatusChanged); _controller.forward(); super.didPush(); } @@ -152,7 +162,7 @@ abstract class TransitionRoute extends OverlayRoute { void didReplace(Route oldRoute) { if (oldRoute is TransitionRoute) _controller.value = oldRoute._controller.value; - _animation.addStatusListener(handleStatusChanged); + _animation.addStatusListener(_handleStatusChanged); super.didReplace(oldRoute); } @@ -202,7 +212,16 @@ abstract class TransitionRoute extends OverlayRoute { } } + /// Whether this route can perform a transition to the given route. + /// + /// Subclasses can override this function to restrict the set of routes they + /// need to coordinate transitions with. bool canTransitionTo(TransitionRoute nextRoute) => true; + + /// Whether this route can perform a transition from the given route. + /// + /// Subclasses can override this function to restrict the set of routes they + /// need to coordinate transitions with. bool canTransitionFrom(TransitionRoute nextRoute) => true; void finished() { @@ -219,28 +238,55 @@ abstract class TransitionRoute extends OverlayRoute { String toString() => '$runtimeType(animation: $_controller)'; } +/// An entry in the history of a [LocalHistoryRoute]. class LocalHistoryEntry { LocalHistoryEntry({ this.onRemove }); + + /// Called when this entry is removed from the history of its associated [LocalHistoryRoute]. final VoidCallback onRemove; + LocalHistoryRoute _owner; + + /// Remove this entry from the history of its associated [LocalHistoryRoute]. void remove() { _owner.removeLocalHistoryEntry(this); assert(_owner == null); } + void _notifyRemoved() { if (onRemove != null) onRemove(); } } +/// A route that can handle back navigations internally by popping a list. +/// +/// When a [Navigator] is instructed to pop, the current route is given an +/// opportunity to handle the pop internally. A LocalHistoryRoute handles the +/// pop internally if its list of local history entries is non-empty. Rather +/// than being removed as the current route, the most recent [LocalHistoryEntry] +/// is removed from the list and its [onRemove] is called. abstract class LocalHistoryRoute extends Route { List _localHistory; + + /// Adds a local history entry to this route. + /// + /// When asked to pop, if this route has any local history entires, this route + /// will handle the pop internally by removing the most recently added local + /// history entry. + /// + /// The given local history entry must not already be part of another local + /// history route. void addLocalHistoryEntry(LocalHistoryEntry entry) { assert(entry._owner == null); entry._owner = this; _localHistory ??= []; _localHistory.add(entry); } + + /// Remove a local history entry from this route. + /// + /// The entry's [onRemove] callback, if any, will be called synchronously. void removeLocalHistoryEntry(LocalHistoryEntry entry) { assert(entry != null); assert(entry._owner == this); @@ -364,14 +410,24 @@ class _ModalScopeState extends State<_ModalScope> { } } +/// Where a [ModalRoute] should be positioned within the [Navigator]'s [Overlay]. class ModalPosition { const ModalPosition({ this.top, this.right, this.bottom, this.left }); + + /// The offset of the route's top edge from the top of the overlay. final double top; + + /// The offset of the route's right edge from the right of the overlay. final double right; + + /// The offset of the route's bottom edge from the bottom of the overlay. final double bottom; + + /// The offset of the route's left edge from the left of the overlay. final double left; } +/// A route that blocks interaction with previous routes. abstract class ModalRoute extends TransitionRoute with LocalHistoryRoute { ModalRoute({ Completer completer, @@ -380,6 +436,9 @@ abstract class ModalRoute extends TransitionRoute with LocalHistoryRoute extends TransitionRoute with LocalHistoryRoute null; + + /// Override this function to build the primary content of this route. + /// + /// * [context] The context in which the route is being built. + /// * [animation] The animation for this route's transition. When entering, + /// the animation runs forward from 0.0 to 1.0. When exiting, this animation + /// runs backwards from 1.0 to 0.0. + /// * [forwardAnimation] The animation for the route being pushed on top of + /// this route. This animation lets this route coordinate with the entrance + /// and exit transition of routes pushed on top of this route. Widget buildPage(BuildContext context, Animation animation, Animation forwardAnimation); + + /// Override this function to wrap the route in a number of transition widgets. + /// + /// For example, to create a fade entrance transition, wrap the given child + /// widget in a [FadeTransition] using the given animation as the opacity. + /// + /// By default, the child is not wrapped in any transition widgets. + /// + /// * [context] The context in which the route is being built. + /// * [animation] The animation for this route's transition. When entering, + /// the animation runs forward from 0.0 to 1.0. When exiting, this animation + /// runs backwards from 1.0 to 0.0. + /// * [forwardAnimation] The animation for the route being pushed on top of + /// this route. This animation lets this route coordinate with the entrance + /// and exit transition of routes pushed on top of this route. Widget buildTransitions(BuildContext context, Animation animation, Animation forwardAnimation, Widget child) { return child; } @@ -408,6 +495,7 @@ abstract class ModalRoute extends TransitionRoute with LocalHistoryRoute extends TransitionRoute with LocalHistoryRoute _offstage; bool _offstage = false; void set offstage (bool value) { @@ -431,6 +526,7 @@ abstract class ModalRoute extends TransitionRoute with LocalHistoryRoute _subtreeKey.currentContext;