viewport.dart 11.9 KB
Newer Older
1 2 3 4 5 6 7
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'package:flutter/foundation.dart';
import 'package:flutter/rendering.dart';

8
import 'basic.dart';
9 10 11 12 13 14
import 'framework.dart';

export 'package:flutter/rendering.dart' show
  AxisDirection,
  GrowthDirection;

15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
/// A widget that is bigger on the inside.
///
/// [Viewport] is the visual workhorse of the scrolling machinery. It displays a
/// subset of its children according to its own dimensions and the given
/// [offset]. As the offset varies, different children are visible through
/// the viewport.
///
/// [Viewport] hosts a bidirectional list of slivers, anchored on a [center]
/// sliver, which is placed at the zero scroll offset. The center widget is
/// displayed in the viewport according to the [anchor] property.
///
/// Slivers that are earlier in the child list than [center] are displayed in
/// reverse order in the reverse [axisDirection] starting from the [center]. For
/// example, if the [axisDirection] is [AxisDirection.down], the first sliver
/// before [center] is placed above the [center]. The slivers that are later in
/// the child list than [center] are placed in order in the [axisDirection]. For
Yegor's avatar
Yegor committed
31
/// example, in the preceding scenario, the first sliver after [center] is
32 33 34 35 36 37 38 39 40 41 42 43 44 45
/// placed below the [center].
///
/// [Viewport] cannot contain box children directly. Instead, use a
/// [SliverList], [SliverFixedExtentList], [SliverGrid], or a
/// [SliverToBoxAdapter], for example.
///
/// See also:
///
///  * [ListView], [PageView], [GridView], and [CustomScrollView], which combine
///    [Scrollable] and [Viewport] into widgets that are easier to use.
///  * [SliverToBoxAdapter], which allows a box widget to be placed inside a
///    sliver context (the opposite of this widget).
///  * [ShrinkWrappingViewport], a variant of [Viewport] that shrink-wraps its
///    contents along the main axis.
Adam Barth's avatar
Adam Barth committed
46
class Viewport extends MultiChildRenderObjectWidget {
47 48 49 50 51 52
  /// Creates a widget that is bigger on the inside.
  ///
  /// The viewport listens to the [offset], which means you do not need to
  /// rebuild this widget when the [offset] changes.
  ///
  /// The [offset] argument must not be null.
Adam Barth's avatar
Adam Barth committed
53
  Viewport({
54 55
    Key key,
    this.axisDirection: AxisDirection.down,
56
    this.crossAxisDirection,
57
    this.anchor: 0.0,
Ian Hickson's avatar
Ian Hickson committed
58
    @required this.offset,
59
    this.center,
60
    List<Widget> slivers: const <Widget>[],
61 62 63 64
  }) : assert(offset != null),
       assert(slivers != null),
       assert(center == null || slivers.where((Widget child) => child.key == center).length == 1),
       super(key: key, children: slivers);
65

66
  /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
67 68 69 70
  ///
  /// For example, if the [axisDirection] is [AxisDirection.down], a scroll
  /// offset of zero is at the top of the viewport and increases towards the
  /// bottom of the viewport.
71
  final AxisDirection axisDirection;
72

73 74 75 76 77 78 79 80 81 82 83
  /// The direction in which child should be laid out in the cross axis.
  ///
  /// If the [axisDirection] is [AxisDirection.down] or [AxisDirection.up], this
  /// property defaults to [AxisDirection.left] if the ambient [Directionality]
  /// is [TextDirection.rtl] and [AxisDirection.right] if the ambient
  /// [Directionality] is [TextDirection.ltr].
  ///
  /// If the [axisDirection] is [AxisDirection.left] or [AxisDirection.right],
  /// this property defaults to [AxisDirection.down].
  final AxisDirection crossAxisDirection;

84 85 86 87 88 89 90
  /// The relative position of the zero scroll offset.
  ///
  /// For example, if [anchor] is 0.5 and the [axisDirection] is
  /// [AxisDirection.down] or [AxisDirection.up], then the zero scroll offset is
  /// vertically centered within the viewport. If the [anchor] is 1.0, and the
  /// [axisDirection] is [AxisDirection.right], then the zero scroll offset is
  /// on the left edge of the viewport.
91
  final double anchor;
92 93 94 95 96 97 98 99 100

  /// Which part of the content inside the viewport should be visible.
  ///
  /// The [ViewportOffset.pixels] value determines the scroll offset that the
  /// viewport uses to select which part of its content to display. As the user
  /// scrolls the viewport, this value changes, which changes the content that
  /// is displayed.
  ///
  /// Typically a [ScrollPosition].
101
  final ViewportOffset offset;
102 103 104 105 106 107 108 109

  /// The first child in the [GrowthDirection.forward] growth direction.
  ///
  /// Children after [center] will be placed in the [axisDirection] relative to
  /// the [center]. Children before [center] will be placed in the opposite of
  /// the [axisDirection] relative to the [center].
  ///
  /// The [center] must be the key of a child of the viewport.
110 111
  final Key center;

112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
  /// Given a [BuildContext] and an [AxisDirection], determine the correct cross
  /// axis direction.
  ///
  /// This depends on the [Directionality] if the `axisDirection` is vertical;
  /// otherwise, the default cross axis direction is downwards.
  static AxisDirection getDefaultCrossAxisDirection(BuildContext context, AxisDirection axisDirection) {
    assert(axisDirection != null);
    switch (axisDirection) {
      case AxisDirection.up:
        return textDirectionToAxisDirection(Directionality.of(context));
      case AxisDirection.right:
        return AxisDirection.down;
      case AxisDirection.down:
        return textDirectionToAxisDirection(Directionality.of(context));
      case AxisDirection.left:
        return AxisDirection.down;
    }
    return null;
  }

132
  @override
Adam Barth's avatar
Adam Barth committed
133 134
  RenderViewport createRenderObject(BuildContext context) {
    return new RenderViewport(
135
      axisDirection: axisDirection,
136
      crossAxisDirection: crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection),
137 138 139 140 141 142
      anchor: anchor,
      offset: offset,
    );
  }

  @override
Adam Barth's avatar
Adam Barth committed
143
  void updateRenderObject(BuildContext context, RenderViewport renderObject) {
144 145
    renderObject
      ..axisDirection = axisDirection
146
      ..crossAxisDirection = crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection)
147 148
      ..anchor = anchor
      ..offset = offset;
149 150 151
  }

  @override
152
  _ViewportElement createElement() => new _ViewportElement(this);
153 154

  @override
155
  void debugFillProperties(DiagnosticPropertiesBuilder description) {
156 157
    super.debugFillProperties(description);
    description.add(new EnumProperty<AxisDirection>('axisDirection', axisDirection));
158
    description.add(new EnumProperty<AxisDirection>('crossAxisDirection', crossAxisDirection, defaultValue: null));
159 160
    description.add(new DoubleProperty('anchor', anchor));
    description.add(new DiagnosticsProperty<ViewportOffset>('offset', offset));
161
    if (center != null) {
162
      description.add(new DiagnosticsProperty<Key>('center', center));
163
    } else if (children.isNotEmpty && children.first.key != null) {
164
      description.add(new DiagnosticsProperty<Key>('center', children.first.key, tooltip: 'implicit'));
165 166 167 168
    }
  }
}

169
class _ViewportElement extends MultiChildRenderObjectElement {
170
  /// Creates an element that uses the given widget as its configuration.
171
  _ViewportElement(Viewport widget) : super(widget);
172 173

  @override
Adam Barth's avatar
Adam Barth committed
174
  Viewport get widget => super.widget;
175 176

  @override
Adam Barth's avatar
Adam Barth committed
177
  RenderViewport get renderObject => super.renderObject;
178 179 180 181

  @override
  void mount(Element parent, dynamic newSlot) {
    super.mount(parent, newSlot);
182
    _updateCenter();
183 184 185 186 187
  }

  @override
  void update(MultiChildRenderObjectWidget newWidget) {
    super.update(newWidget);
188
    _updateCenter();
189 190
  }

191
  void _updateCenter() {
192 193 194 195 196 197 198 199 200 201 202 203
    // TODO(ianh): cache the keys to make this faster
    if (widget.center != null) {
      renderObject.center = children.singleWhere(
        (Element element) => element.widget.key == widget.center
      ).renderObject;
    } else if (children.isNotEmpty) {
      renderObject.center = children.first.renderObject;
    } else {
      renderObject.center = null;
    }
  }
}
204

205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
/// A widget that is bigger on the inside and shrink wraps its children in the
/// main axis.
///
/// [ShrinkWrappingViewport] displays a subset of its children according to its
/// own dimensions and the given [offset]. As the offset varies, different
/// children are visible through the viewport.
///
/// [ShrinkWrappingViewport] differs from [Viewport] in that [Viewport] expands
/// to fill the main axis whereas [ShrinkWrappingViewport] sizes itself to match
/// its children in the main axis. This shrink wrapping behavior is expensive
/// because the children, and hence the viewport, could potentially change size
/// whenever the [offset] changes (e.g., because of a collapsing header).
///
/// [ShrinkWrappingViewport] cannot contain box children directly. Instead, use
/// a [SliverList], [SliverFixedExtentList], [SliverGrid], or a
/// [SliverToBoxAdapter], for example.
///
/// See also:
///
///  * [ListView], [PageView], [GridView], and [CustomScrollView], which combine
///    [Scrollable] and [ShrinkWrappingViewport] into widgets that are easier to
///    use.
///  * [SliverToBoxAdapter], which allows a box widget to be placed inside a
///    sliver context (the opposite of this widget).
///  * [Viewport], a viewport that does not shrink-wrap its contents
230
class ShrinkWrappingViewport extends MultiChildRenderObjectWidget {
231 232 233 234 235 236 237
  /// Creates a widget that is bigger on the inside and shrink wraps its
  /// children in the main axis.
  ///
  /// The viewport listens to the [offset], which means you do not need to
  /// rebuild this widget when the [offset] changes.
  ///
  /// The [offset] argument must not be null.
238 239 240
  ShrinkWrappingViewport({
    Key key,
    this.axisDirection: AxisDirection.down,
241
    this.crossAxisDirection,
242 243
    @required this.offset,
    List<Widget> slivers: const <Widget>[],
244 245
  }) : assert(offset != null),
       super(key: key, children: slivers);
246

247
  /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
248 249 250 251
  ///
  /// For example, if the [axisDirection] is [AxisDirection.down], a scroll
  /// offset of zero is at the top of the viewport and increases towards the
  /// bottom of the viewport.
252
  final AxisDirection axisDirection;
253

254 255 256 257 258 259 260 261 262 263 264
  /// The direction in which child should be laid out in the cross axis.
  ///
  /// If the [axisDirection] is [AxisDirection.down] or [AxisDirection.up], this
  /// property defaults to [AxisDirection.left] if the ambient [Directionality]
  /// is [TextDirection.rtl] and [AxisDirection.right] if the ambient
  /// [Directionality] is [TextDirection.ltr].
  ///
  /// If the [axisDirection] is [AxisDirection.left] or [AxisDirection.right],
  /// this property defaults to [AxisDirection.down].
  final AxisDirection crossAxisDirection;

265 266 267 268 269 270 271 272
  /// Which part of the content inside the viewport should be visible.
  ///
  /// The [ViewportOffset.pixels] value determines the scroll offset that the
  /// viewport uses to select which part of its content to display. As the user
  /// scrolls the viewport, this value changes, which changes the content that
  /// is displayed.
  ///
  /// Typically a [ScrollPosition].
273 274 275 276 277 278
  final ViewportOffset offset;

  @override
  RenderShrinkWrappingViewport createRenderObject(BuildContext context) {
    return new RenderShrinkWrappingViewport(
      axisDirection: axisDirection,
279
      crossAxisDirection: crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection),
280 281 282 283 284 285 286 287
      offset: offset,
    );
  }

  @override
  void updateRenderObject(BuildContext context, RenderShrinkWrappingViewport renderObject) {
    renderObject
      ..axisDirection = axisDirection
288
      ..crossAxisDirection = crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection)
289 290 291 292
      ..offset = offset;
  }

  @override
293
  void debugFillProperties(DiagnosticPropertiesBuilder description) {
294 295
    super.debugFillProperties(description);
    description.add(new EnumProperty<AxisDirection>('axisDirection', axisDirection));
296
    description.add(new EnumProperty<AxisDirection>('crossAxisDirection', crossAxisDirection, defaultValue: null));
297
    description.add(new DiagnosticsProperty<ViewportOffset>('offset', offset));
298 299
  }
}