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

import 'package:flutter/rendering.dart';

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

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

14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
/// 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
30
/// example, in the preceding scenario, the first sliver after [center] is
31 32 33 34 35 36 37 38 39 40 41 42 43 44
/// 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
45
class Viewport extends MultiChildRenderObjectWidget {
46 47 48 49 50 51
  /// 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
52
  Viewport({
53
    Key key,
54
    this.axisDirection = AxisDirection.down,
55
    this.crossAxisDirection,
56
    this.anchor = 0.0,
Ian Hickson's avatar
Ian Hickson committed
57
    @required this.offset,
58
    this.center,
59
    this.cacheExtent,
60
    this.cacheExtentStyle = CacheExtentStyle.pixel,
61
    List<Widget> slivers = const <Widget>[],
62 63 64
  }) : assert(offset != null),
       assert(slivers != null),
       assert(center == null || slivers.where((Widget child) => child.key == center).length == 1),
65 66
       assert(cacheExtentStyle != null),
       assert(cacheExtentStyle != CacheExtentStyle.viewport || cacheExtent != null),
67
       super(key: key, children: slivers);
68

69
  /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
70 71 72 73
  ///
  /// 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.
74
  final AxisDirection axisDirection;
75

76 77 78 79 80 81 82 83 84 85 86
  /// 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;

87 88 89 90 91 92 93
  /// 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.
94
  final double anchor;
95 96 97 98 99 100 101 102 103

  /// 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].
104
  final ViewportOffset offset;
105 106 107 108 109 110 111 112

  /// 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.
113 114
  final Key center;

115 116 117
  /// {@macro flutter.rendering.viewport.cacheExtent}
  final double cacheExtent;

118 119 120
  /// {@macro flutter.rendering.viewport.cacheExtentStyle}
  final CacheExtentStyle cacheExtentStyle;

121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
  /// 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;
  }

141
  @override
Adam Barth's avatar
Adam Barth committed
142
  RenderViewport createRenderObject(BuildContext context) {
143
    return RenderViewport(
144
      axisDirection: axisDirection,
145
      crossAxisDirection: crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection),
146 147
      anchor: anchor,
      offset: offset,
148
      cacheExtent: cacheExtent,
149
      cacheExtentStyle: cacheExtentStyle,
150 151 152 153
    );
  }

  @override
Adam Barth's avatar
Adam Barth committed
154
  void updateRenderObject(BuildContext context, RenderViewport renderObject) {
155 156
    renderObject
      ..axisDirection = axisDirection
157
      ..crossAxisDirection = crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection)
158
      ..anchor = anchor
159
      ..offset = offset
160 161
      ..cacheExtent = cacheExtent
      ..cacheExtentStyle = cacheExtentStyle;
162 163 164
  }

  @override
165
  _ViewportElement createElement() => _ViewportElement(this);
166 167

  @override
168 169
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
170 171 172 173
    properties.add(EnumProperty<AxisDirection>('axisDirection', axisDirection));
    properties.add(EnumProperty<AxisDirection>('crossAxisDirection', crossAxisDirection, defaultValue: null));
    properties.add(DoubleProperty('anchor', anchor));
    properties.add(DiagnosticsProperty<ViewportOffset>('offset', offset));
174
    if (center != null) {
175
      properties.add(DiagnosticsProperty<Key>('center', center));
176
    } else if (children.isNotEmpty && children.first.key != null) {
177
      properties.add(DiagnosticsProperty<Key>('center', children.first.key, tooltip: 'implicit'));
178
    }
179 180
    properties.add(DiagnosticsProperty<double>('cacheExtent', cacheExtent));
    properties.add(DiagnosticsProperty<CacheExtentStyle>('cacheExtentStyle', cacheExtentStyle));
181 182 183
  }
}

184
class _ViewportElement extends MultiChildRenderObjectElement {
185
  /// Creates an element that uses the given widget as its configuration.
186
  _ViewportElement(Viewport widget) : super(widget);
187 188

  @override
189
  Viewport get widget => super.widget as Viewport;
190 191

  @override
192
  RenderViewport get renderObject => super.renderObject as RenderViewport;
193 194 195 196

  @override
  void mount(Element parent, dynamic newSlot) {
    super.mount(parent, newSlot);
197
    _updateCenter();
198 199 200 201 202
  }

  @override
  void update(MultiChildRenderObjectWidget newWidget) {
    super.update(newWidget);
203
    _updateCenter();
204 205
  }

206
  void _updateCenter() {
207 208 209 210
    // TODO(ianh): cache the keys to make this faster
    if (widget.center != null) {
      renderObject.center = children.singleWhere(
        (Element element) => element.widget.key == widget.center
211
      ).renderObject as RenderSliver;
212
    } else if (children.isNotEmpty) {
213
      renderObject.center = children.first.renderObject as RenderSliver;
214 215 216 217
    } else {
      renderObject.center = null;
    }
  }
218 219 220

  @override
  void debugVisitOnstageChildren(ElementVisitor visitor) {
221
    children.where((Element e) {
222
      final RenderSliver renderSliver = e.renderObject as RenderSliver;
223 224
      return renderSliver.geometry.visible;
    }).forEach(visitor);
225
  }
226
}
227

228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
/// 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).
252
///  * [Viewport], a viewport that does not shrink-wrap its contents.
253
class ShrinkWrappingViewport extends MultiChildRenderObjectWidget {
254 255 256 257 258 259 260
  /// 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.
261 262
  ShrinkWrappingViewport({
    Key key,
263
    this.axisDirection = AxisDirection.down,
264
    this.crossAxisDirection,
265
    @required this.offset,
266
    List<Widget> slivers = const <Widget>[],
267 268
  }) : assert(offset != null),
       super(key: key, children: slivers);
269

270
  /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
271 272 273 274
  ///
  /// 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.
275
  final AxisDirection axisDirection;
276

277 278 279 280 281 282 283 284 285 286 287
  /// 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;

288 289 290 291 292 293 294 295
  /// 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].
296 297 298 299
  final ViewportOffset offset;

  @override
  RenderShrinkWrappingViewport createRenderObject(BuildContext context) {
300
    return RenderShrinkWrappingViewport(
301
      axisDirection: axisDirection,
302
      crossAxisDirection: crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection),
303 304 305 306 307 308 309 310
      offset: offset,
    );
  }

  @override
  void updateRenderObject(BuildContext context, RenderShrinkWrappingViewport renderObject) {
    renderObject
      ..axisDirection = axisDirection
311
      ..crossAxisDirection = crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection)
312 313 314 315
      ..offset = offset;
  }

  @override
316 317
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
318 319 320
    properties.add(EnumProperty<AxisDirection>('axisDirection', axisDirection));
    properties.add(EnumProperty<AxisDirection>('crossAxisDirection', crossAxisDirection, defaultValue: null));
    properties.add(DiagnosticsProperty<ViewportOffset>('offset', offset));
321 322
  }
}