Skip to content

Commit ea6bf47

Browse files
authored
Fix the losing of state when pushing opaque routes (#5624)
Fixes #5283 Other changes in this patch: Rename OffStage to Offstage. Fixes #5378 Add a lot of docs. Some minor punctuation and whitespace fixes.
1 parent 43d0eeb commit ea6bf47

28 files changed

Lines changed: 1188 additions & 324 deletions

‎packages/flutter/lib/src/material/page.dart‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,12 +148,17 @@ class _CupertinoBackGestureController extends NavigationGestureController {
148148
///
149149
/// [MaterialApp] creates material page routes for entries in the
150150
/// [MaterialApp.routes] map.
151+
///
152+
/// By default, when a modal route is replaced by another, the previous route
153+
/// remains in memory. To free all the resources when this is not necessary, set
154+
/// [maintainState] to false.
151155
class MaterialPageRoute<T> extends PageRoute<T> {
152156
/// Creates a page route for use in a material design app.
153157
MaterialPageRoute({
154158
this.builder,
155159
Completer<T> completer,
156-
RouteSettings settings: const RouteSettings()
160+
RouteSettings settings: const RouteSettings(),
161+
this.maintainState: true,
157162
}) : super(completer: completer, settings: settings) {
158163
assert(builder != null);
159164
assert(opaque);
@@ -162,6 +167,9 @@ class MaterialPageRoute<T> extends PageRoute<T> {
162167
/// Builds the primary contents of the route.
163168
final WidgetBuilder builder;
164169

170+
@override
171+
final bool maintainState;
172+
165173
@override
166174
Duration get transitionDuration => const Duration(milliseconds: 300);
167175

‎packages/flutter/lib/src/rendering/binding.dart‎

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,53 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
148148

149149
/// Pump the rendering pipeline to generate a frame.
150150
///
151-
/// Called automatically by the engine when it is time to lay out and paint a frame.
151+
/// This method is called by [handleBeginFrame], which itself is called
152+
/// automatically by the engine when when it is time to lay out and paint a
153+
/// frame.
154+
///
155+
/// Each frame consists of the following phases:
156+
///
157+
/// 1. The animation phase: The [handleBeginFrame] method, which is registered
158+
/// with [ui.window.onBeginFrame], invokes all the transient frame callbacks
159+
/// registered with [scheduleFrameCallback] and [addFrameCallback], in
160+
/// registration order. This includes all the [Ticker] instances that are
161+
/// driving [AnimationController] objects, which means all of the active
162+
/// [Animation] objects tick at this point.
163+
///
164+
/// [handleBeginFrame] then invokes all the persistent frame callbacks, of which
165+
/// the most notable is this method, [beginFrame], which proceeds as follows:
166+
///
167+
/// 2. The layout phase: All the dirty [RenderObject]s in the system are laid
168+
/// out (see [RenderObject.performLayout]). See [RenderObject.markNeedsLayout]
169+
/// for further details on marking an object dirty for layout.
170+
///
171+
/// 3. The compositing bits phase: The compositing bits on any dirty
172+
/// [RenderObject] objects are updated. See
173+
/// [RenderObject.markNeedsCompositingBitsUpdate].
174+
///
175+
/// 4. The paint phase: All the dirty [RenderObject]s in the system are
176+
/// repainted (see [RenderObject.paint]). This generates the [Layer] tree. See
177+
/// [RenderObject.markNeedsPaint] for further details on marking an object
178+
/// dirty for paint.
179+
///
180+
/// 5. The compositing phase: The layer tree is turned into a [ui.Scene] and
181+
/// sent to the GPU.
182+
///
183+
/// 6. The semantics phase: All the dirty [RenderObject]s in the system have
184+
/// their semantics updated (see [RenderObject.semanticAnnotator]). This
185+
/// generates the [SemanticsNode] tree. See
186+
/// [RenderObject.markNeedsSemanticsUpdate] for further details on marking an
187+
/// object dirty for semantics.
188+
///
189+
/// For more details on steps 2-6, see [PipelineOwner].
190+
///
191+
/// 7. The finalization phase: After [beginFrame] returns, [handleBeginFrame]
192+
/// then invokes post-frame callbacks (registered with [addPostFrameCallback].
193+
///
194+
/// Some bindings (for example, the [WidgetsBinding]) add extra steps to this
195+
/// list.
196+
//
197+
// When editing the above, also update widgets/binding.dart's copy.
152198
void beginFrame() {
153199
assert(renderView != null);
154200
pipelineOwner.flushLayout();

‎packages/flutter/lib/src/rendering/layer.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import 'package:mojo_services/mojo/gfx/composition/scene_token.mojom.dart' as mo
1212

1313
import 'debug.dart';
1414

15-
/// A composited layer
15+
/// A composited layer.
1616
///
1717
/// During painting, the render tree generates a tree of composited layers that
1818
/// are uploaded into the engine and displayed by the compositor. This class is

‎packages/flutter/lib/src/rendering/object.dart‎

Lines changed: 35 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1956,26 +1956,24 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
19561956
/// Mark this node as needing an update to its semantics
19571957
/// description.
19581958
///
1959-
/// If the change did not involve a removal or addition of
1960-
/// semantics, only the change of semantics (e.g. isChecked changing
1961-
/// from true to false, as opposed to isChecked changing from being
1962-
/// true to not being changed at all), then you can pass the
1963-
/// onlyChanges argument with the value true to reduce the cost. If
1964-
/// semantics are being added or removed, more work needs to be done
1965-
/// to update the semantics tree. If you pass 'onlyChanges: true'
1966-
/// but this node, which previously had a SemanticsNode, no longer
1967-
/// has one, or previously did not set any semantics, but now does,
1968-
/// or previously had a child that returned annotators, but no
1969-
/// longer does, or other such combinations, then you will either
1970-
/// assert during the subsequent call to [flushSemantics()] or you
1971-
/// will have out-of-date information in the semantics tree.
1972-
///
1973-
/// If the geometry might have changed in any way, then again, more
1974-
/// work needs to be done to update the semantics tree (to deal with
1975-
/// clips). You can pass the noGeometry argument to avoid this work
1976-
/// in the case where only the labels or flags changed. If you pass
1977-
/// 'noGeometry: true' when the geometry did change, the semantic
1978-
/// tree will be out of date.
1959+
/// If the change did not involve a removal or addition of semantics, only the
1960+
/// change of semantics (e.g. isChecked changing from true to false, as
1961+
/// opposed to isChecked changing from being true to not being changed at
1962+
/// all), then you can pass the onlyChanges argument with the value true to
1963+
/// reduce the cost. If semantics are being added or removed, more work needs
1964+
/// to be done to update the semantics tree. If you pass 'onlyChanges: true'
1965+
/// but this node, which previously had a SemanticsNode, no longer has one, or
1966+
/// previously did not set any semantics, but now does, or previously had a
1967+
/// child that returned annotators, but no longer does, or other such
1968+
/// combinations, then you will either assert during the subsequent call to
1969+
/// [PipelineOwner.flushSemantics()] or you will have out-of-date information
1970+
/// in the semantics tree.
1971+
///
1972+
/// If the geometry might have changed in any way, then again, more work needs
1973+
/// to be done to update the semantics tree (to deal with clips). You can pass
1974+
/// the noGeometry argument to avoid this work in the case where only the
1975+
/// labels or flags changed. If you pass 'noGeometry: true' when the geometry
1976+
/// did change, the semantic tree will be out of date.
19791977
void markNeedsSemanticsUpdate({ bool onlyChanges: false, bool noGeometry: false }) {
19801978
assert(!attached || !owner._debugDoingSemantics);
19811979
if ((attached && owner._semanticsOwner == null) || (_needsSemanticsUpdate && onlyChanges && (_needsSemanticsGeometryUpdate || noGeometry)))
@@ -2089,31 +2087,30 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
20892087
visitChildren(visitor);
20902088
}
20912089

2092-
/// Returns functions that will annotate a SemanticsNode with the
2093-
/// semantics of this RenderObject.
2090+
/// Returns a function that will annotate a [SemanticsNode] with the semantics
2091+
/// of this [RenderObject].
20942092
///
2095-
/// To annotate a SemanticsNode for this node, return all the
2096-
/// annotators provided by the superclass, plus an annotator that
2097-
/// adds the annotations. When the behavior of the annotators would
2093+
/// To annotate a SemanticsNode for this node, return an annotator that
2094+
/// adds the annotations. When the behavior of the annotator would
20982095
/// change (e.g. the box is now checked rather than unchecked), call
2099-
/// [markNeedsSemanticsUpdate()] to indicate to the rendering system
2096+
/// [markNeedsSemanticsUpdate] to indicate to the rendering system
21002097
/// that the semantics tree needs to be rebuilt.
21012098
///
21022099
/// To introduce a new SemanticsNode, set hasSemantics to true for
2103-
/// this object. The functions returned by this function will be used
2100+
/// this object. The function returned by this function will be used
21042101
/// to annotate the SemanticsNode for this object.
21052102
///
21062103
/// Semantic annotations are persistent. Values set in one pass will
21072104
/// still be set in the next pass. Therefore it is important to
2108-
/// explicitly set fields to false once they are no longer true --
2105+
/// explicitly set fields to false once they are no longer true;
21092106
/// setting them to true when they are to be enabled, and not
21102107
/// setting them at all when they are not, will mean they remain set
21112108
/// once enabled once and will never get unset.
21122109
///
2113-
/// If the number of annotators you return will change from zero to
2114-
/// non-zero, and hasSemantics isn't true, then the associated call
2115-
/// to markNeedsSemanticsUpdate() must not have 'onlyChanges' set, as
2116-
/// it is possible that the node should be entirely removed.
2110+
/// If the value return will change from null to non-null (or vice versa), and
2111+
/// [hasSemantics] isn't true, then the associated call to
2112+
/// [markNeedsSemanticsUpdate] must not have `onlyChanges` set, as it is
2113+
/// possible that the node should be entirely removed.
21172114
SemanticAnnotator get semanticAnnotator => null;
21182115

21192116

@@ -2247,6 +2244,12 @@ abstract class RenderObjectWithChildMixin<ChildType extends RenderObject> implem
22472244
_child.detach();
22482245
}
22492246

2247+
@override
2248+
void redepthChildren() {
2249+
if (_child != null)
2250+
redepthChild(_child);
2251+
}
2252+
22502253
@override
22512254
void visitChildren(RenderObjectVisitor visitor) {
22522255
if (_child != null)

‎packages/flutter/lib/src/rendering/proxy_box.dart‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ export 'package:flutter/gestures.dart' show
3232
/// the proxy box with its child. However, RenderProxyBox is a useful base class
3333
/// for render objects that wish to mimic most, but not all, of the properties
3434
/// of their child.
35-
class RenderProxyBox extends RenderBox with RenderObjectWithChildMixin<RenderBox> {
35+
class RenderProxyBox extends RenderBox with RenderObjectWithChildMixin<RenderBox>, RenderProxyBoxMixin {
3636
/// Creates a proxy render box.
3737
///
3838
/// Proxy render boxes are rarely created directly because they simply proxy
@@ -41,7 +41,15 @@ class RenderProxyBox extends RenderBox with RenderObjectWithChildMixin<RenderBox
4141
RenderProxyBox([RenderBox child = null]) {
4242
this.child = child;
4343
}
44+
}
4445

46+
/// Implementation of [RenderProxyBox].
47+
///
48+
/// This class can be used as a mixin for situations where the proxying behavior
49+
/// of [RenderProxyBox] is desired but inheriting from [RenderProxyBox] is
50+
/// impractical (e.g. because you want to mix in other classes as well).
51+
// TODO(ianh): Remove this class once https://github.com/dart-lang/sdk/issues/15101 is fixed
52+
abstract class RenderProxyBoxMixin implements RenderBox, RenderObjectWithChildMixin<RenderBox> {
4553
@override
4654
double computeMinIntrinsicWidth(double height) {
4755
if (child != null)
@@ -2016,9 +2024,9 @@ class RenderIgnorePointer extends RenderProxyBox {
20162024
/// Lays the child out as if it was in the tree, but without painting anything,
20172025
/// without making the child available for hit testing, and without taking any
20182026
/// room in the parent.
2019-
class RenderOffStage extends RenderProxyBox {
2020-
/// Creates an off-stage render object.
2021-
RenderOffStage({
2027+
class RenderOffstage extends RenderProxyBox {
2028+
/// Creates an offstage render object.
2029+
RenderOffstage({
20222030
bool offstage: true,
20232031
RenderBox child
20242032
}) : _offstage = offstage, super(child) {

‎packages/flutter/lib/src/rendering/shifted_box.dart‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -422,14 +422,14 @@ class RenderPositionedBox extends RenderAligningShiftedBox {
422422
/// ignoring the child's dimensions.
423423
///
424424
/// For example, if you wanted a box to always render 50 pixels high, regardless
425-
/// of where it was rendered, you would wrap it in a RenderOverflow with
426-
/// minHeight and maxHeight set to 50.0. Generally speaking, to avoid confusing
427-
/// behavior around hit testing, a RenderOverflowBox should usually be wrapped
428-
/// in a RenderClipRect.
425+
/// of where it was rendered, you would wrap it in a
426+
/// RenderConstrainedOverflowBox with minHeight and maxHeight set to 50.0.
427+
/// Generally speaking, to avoid confusing behavior around hit testing, a
428+
/// RenderConstrainedOverflowBox should usually be wrapped in a RenderClipRect.
429429
///
430-
/// The child is positioned at the top left of the box. To position a smaller
430+
/// The child is positioned according to [alignment]. To position a smaller
431431
/// child inside a larger parent, use [RenderPositionedBox] and
432-
/// [RenderConstrainedBox] rather than RenderOverflowBox.
432+
/// [RenderConstrainedBox] rather than RenderConstrainedOverflowBox.
433433
class RenderConstrainedOverflowBox extends RenderAligningShiftedBox {
434434
/// Creates a render object that lets its child overflow itself.
435435
RenderConstrainedOverflowBox({

‎packages/flutter/lib/src/rendering/stack.dart‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -199,13 +199,13 @@ class StackParentData extends ContainerBoxParentDataMixin<RenderBox> {
199199
}
200200
}
201201

202-
/// Whether overflowing children should be clipped, or their overflows be
202+
/// Whether overflowing children should be clipped, or their overflow be
203203
/// visible.
204204
enum Overflow {
205-
/// Children's overflows will be visible.
205+
/// Overflowing children will be visible.
206206
visible,
207-
/// Children's overflows will be clipped.
208-
clip
207+
/// Overflowing children will be clipped to the bounds of their parent.
208+
clip,
209209
}
210210

211211
/// Implements the stack layout algorithm

‎packages/flutter/lib/src/widgets/basic.dart‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1077,9 +1077,9 @@ class SizedOverflowBox extends SingleChildRenderObjectWidget {
10771077
/// A widget that lays the child out as if it was in the tree, but without painting anything,
10781078
/// without making the child available for hit testing, and without taking any
10791079
/// room in the parent.
1080-
class OffStage extends SingleChildRenderObjectWidget {
1080+
class Offstage extends SingleChildRenderObjectWidget {
10811081
/// Creates a widget that visually hides its child.
1082-
OffStage({ Key key, this.offstage: true, Widget child })
1082+
Offstage({ Key key, this.offstage: true, Widget child })
10831083
: super(key: key, child: child) {
10841084
assert(offstage != null);
10851085
}
@@ -1094,10 +1094,10 @@ class OffStage extends SingleChildRenderObjectWidget {
10941094
final bool offstage;
10951095

10961096
@override
1097-
RenderOffStage createRenderObject(BuildContext context) => new RenderOffStage(offstage: offstage);
1097+
RenderOffstage createRenderObject(BuildContext context) => new RenderOffstage(offstage: offstage);
10981098

10991099
@override
1100-
void updateRenderObject(BuildContext context, RenderOffStage renderObject) {
1100+
void updateRenderObject(BuildContext context, RenderOffstage renderObject) {
11011101
renderObject.offstage = offstage;
11021102
}
11031103

@@ -1106,6 +1106,22 @@ class OffStage extends SingleChildRenderObjectWidget {
11061106
super.debugFillDescription(description);
11071107
description.add('offstage: $offstage');
11081108
}
1109+
1110+
@override
1111+
_OffstageElement createElement() => new _OffstageElement(this);
1112+
}
1113+
1114+
class _OffstageElement extends SingleChildRenderObjectElement {
1115+
_OffstageElement(Offstage widget) : super(widget);
1116+
1117+
@override
1118+
Offstage get widget => super.widget;
1119+
1120+
@override
1121+
void visitChildrenForSemantics(ElementVisitor visitor) {
1122+
if (!widget.offstage)
1123+
super.visitChildrenForSemantics(visitor);
1124+
}
11091125
}
11101126

11111127
/// A widget that attempts to size the child to a specific aspect ratio.
@@ -2646,6 +2662,14 @@ class IgnorePointer extends SingleChildRenderObjectWidget {
26462662
..ignoring = ignoring
26472663
..ignoringSemantics = ignoringSemantics;
26482664
}
2665+
2666+
@override
2667+
void debugFillDescription(List<String> description) {
2668+
super.debugFillDescription(description);
2669+
description.add('ignoring: $ignoring');
2670+
if (ignoringSemantics != null)
2671+
description.add('ignoringSemantics: $ignoringSemantics');
2672+
}
26492673
}
26502674

26512675
/// A widget that absorbs pointers during hit testing.

0 commit comments

Comments
 (0)