viewport.dart 15.5 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
import 'debug.dart';
9
import 'framework.dart';
10
import 'scroll_notification.dart';
11 12 13 14 15

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

16 17
/// A widget through which a portion of larger content can be viewed, typically
/// in combination with a [Scrollable].
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
///
/// [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
33
/// example, in the preceding scenario, the first sliver after [center] is
34 35 36 37 38 39 40 41 42 43 44 45 46 47
/// 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.
48 49
///  * [ViewportElementMixin], which should be mixed in to the [Element] type used
///    by viewport-like widgets to correctly handle scroll notifications.
Adam Barth's avatar
Adam Barth committed
50
class Viewport extends MultiChildRenderObjectWidget {
51 52 53 54 55
  /// 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.
  ///
56 57
  /// The [cacheExtent] must be specified if the [cacheExtentStyle] is
  /// not [CacheExtentStyle.pixel].
Adam Barth's avatar
Adam Barth committed
58
  Viewport({
59
    super.key,
60
    this.axisDirection = AxisDirection.down,
61
    this.crossAxisDirection,
62
    this.anchor = 0.0,
63
    required this.offset,
64
    this.center,
65
    this.cacheExtent,
66
    this.cacheExtentStyle = CacheExtentStyle.pixel,
67
    this.clipBehavior = Clip.hardEdge,
68
    List<Widget> slivers = const <Widget>[],
69
  }) : assert(center == null || slivers.where((Widget child) => child.key == center).length == 1),
70
       assert(cacheExtentStyle != CacheExtentStyle.viewport || cacheExtent != null),
71
       super(children: slivers);
72

73
  /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
74 75 76 77
  ///
  /// 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.
78
  final AxisDirection axisDirection;
79

80 81 82 83 84 85 86 87 88
  /// 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].
89
  final AxisDirection? crossAxisDirection;
90

91 92 93 94 95 96 97
  /// 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.
98 99
  ///
  /// {@macro flutter.rendering.GrowthDirection.sample}
100
  final double anchor;
101 102 103 104 105 106 107 108 109

  /// 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].
110
  final ViewportOffset offset;
111 112 113 114 115 116 117 118

  /// 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.
119 120
  ///
  /// {@macro flutter.rendering.GrowthDirection.sample}
121
  final Key? center;
122

123
  /// {@macro flutter.rendering.RenderViewportBase.cacheExtent}
124 125 126 127
  ///
  /// See also:
  ///
  ///  * [cacheExtentStyle], which controls the units of the [cacheExtent].
128
  final double? cacheExtent;
129

130
  /// {@macro flutter.rendering.RenderViewportBase.cacheExtentStyle}
131 132
  final CacheExtentStyle cacheExtentStyle;

133
  /// {@macro flutter.material.Material.clipBehavior}
134
  ///
135
  /// Defaults to [Clip.hardEdge].
136 137
  final Clip clipBehavior;

138 139 140 141 142 143 144 145
  /// 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) {
    switch (axisDirection) {
      case AxisDirection.up:
146 147
        assert(debugCheckHasDirectionality(
          context,
148 149
          why: "to determine the cross-axis direction when the viewport has an 'up' axisDirection",
          alternative: "Alternatively, consider specifying the 'crossAxisDirection' argument on the Viewport.",
150
        ));
151
        return textDirectionToAxisDirection(Directionality.of(context));
152 153 154
      case AxisDirection.right:
        return AxisDirection.down;
      case AxisDirection.down:
155 156
        assert(debugCheckHasDirectionality(
          context,
157 158
          why: "to determine the cross-axis direction when the viewport has a 'down' axisDirection",
          alternative: "Alternatively, consider specifying the 'crossAxisDirection' argument on the Viewport.",
159
        ));
160
        return textDirectionToAxisDirection(Directionality.of(context));
161 162 163 164 165
      case AxisDirection.left:
        return AxisDirection.down;
    }
  }

166
  @override
Adam Barth's avatar
Adam Barth committed
167
  RenderViewport createRenderObject(BuildContext context) {
168
    return RenderViewport(
169
      axisDirection: axisDirection,
170
      crossAxisDirection: crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection),
171 172
      anchor: anchor,
      offset: offset,
173
      cacheExtent: cacheExtent,
174
      cacheExtentStyle: cacheExtentStyle,
175
      clipBehavior: clipBehavior,
176 177 178 179
    );
  }

  @override
Adam Barth's avatar
Adam Barth committed
180
  void updateRenderObject(BuildContext context, RenderViewport renderObject) {
181 182
    renderObject
      ..axisDirection = axisDirection
183
      ..crossAxisDirection = crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection)
184
      ..anchor = anchor
185
      ..offset = offset
186
      ..cacheExtent = cacheExtent
187 188
      ..cacheExtentStyle = cacheExtentStyle
      ..clipBehavior = clipBehavior;
189 190 191
  }

  @override
192
  MultiChildRenderObjectElement createElement() => _ViewportElement(this);
193 194

  @override
195 196
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
197 198 199 200
    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));
201
    if (center != null) {
202
      properties.add(DiagnosticsProperty<Key>('center', center));
203
    } else if (children.isNotEmpty && children.first.key != null) {
204
      properties.add(DiagnosticsProperty<Key>('center', children.first.key, tooltip: 'implicit'));
205
    }
206 207
    properties.add(DiagnosticsProperty<double>('cacheExtent', cacheExtent));
    properties.add(DiagnosticsProperty<CacheExtentStyle>('cacheExtentStyle', cacheExtentStyle));
208 209 210
  }
}

211
class _ViewportElement extends MultiChildRenderObjectElement with NotifiableElementMixin, ViewportElementMixin {
212
  /// Creates an element that uses the given widget as its configuration.
213
  _ViewportElement(Viewport super.widget);
214

215 216 217
  bool _doingMountOrUpdate = false;
  int? _centerSlotIndex;

218
  @override
219
  RenderViewport get renderObject => super.renderObject as RenderViewport;
220 221

  @override
222
  void mount(Element? parent, Object? newSlot) {
223 224
    assert(!_doingMountOrUpdate);
    _doingMountOrUpdate = true;
225
    super.mount(parent, newSlot);
226
    _updateCenter();
227 228
    assert(_doingMountOrUpdate);
    _doingMountOrUpdate = false;
229 230 231 232
  }

  @override
  void update(MultiChildRenderObjectWidget newWidget) {
233 234
    assert(!_doingMountOrUpdate);
    _doingMountOrUpdate = true;
235
    super.update(newWidget);
236
    _updateCenter();
237 238
    assert(_doingMountOrUpdate);
    _doingMountOrUpdate = false;
239 240
  }

241
  void _updateCenter() {
242
    // TODO(ianh): cache the keys to make this faster
243 244
    final Viewport viewport = widget as Viewport;
    if (viewport.center != null) {
245 246
      int elementIndex = 0;
      for (final Element e in children) {
247
        if (e.widget.key == viewport.center) {
248 249 250 251 252 253 254
          renderObject.center = e.renderObject as RenderSliver?;
          break;
        }
        elementIndex++;
      }
      assert(elementIndex < children.length);
      _centerSlotIndex = elementIndex;
255
    } else if (children.isNotEmpty) {
256
      renderObject.center = children.first.renderObject as RenderSliver?;
257
      _centerSlotIndex = 0;
258 259
    } else {
      renderObject.center = null;
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284
      _centerSlotIndex = null;
    }
  }

  @override
  void insertRenderObjectChild(RenderObject child, IndexedSlot<Element?> slot) {
    super.insertRenderObjectChild(child, slot);
    // Once [mount]/[update] are done, the `renderObject.center` will be updated
    // in [_updateCenter].
    if (!_doingMountOrUpdate && slot.index == _centerSlotIndex) {
      renderObject.center = child as RenderSliver?;
    }
  }

  @override
  void moveRenderObjectChild(RenderObject child, IndexedSlot<Element?> oldSlot, IndexedSlot<Element?> newSlot) {
    super.moveRenderObjectChild(child, oldSlot, newSlot);
    assert(_doingMountOrUpdate);
  }

  @override
  void removeRenderObjectChild(RenderObject child, Object? slot) {
    super.removeRenderObjectChild(child, slot);
    if (!_doingMountOrUpdate && renderObject.center == child) {
      renderObject.center = null;
285 286
    }
  }
287 288 289

  @override
  void debugVisitOnstageChildren(ElementVisitor visitor) {
290
    children.where((Element e) {
291
      final RenderSliver renderSliver = e.renderObject! as RenderSliver;
292
      return renderSliver.geometry!.visible;
293
    }).forEach(visitor);
294
  }
295
}
296

297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320
/// 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).
321
///  * [Viewport], a viewport that does not shrink-wrap its contents.
322
class ShrinkWrappingViewport extends MultiChildRenderObjectWidget {
323 324 325 326 327
  /// 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.
328
  const ShrinkWrappingViewport({
329
    super.key,
330
    this.axisDirection = AxisDirection.down,
331
    this.crossAxisDirection,
332
    required this.offset,
333
    this.clipBehavior = Clip.hardEdge,
334
    List<Widget> slivers = const <Widget>[],
335
  }) : super(children: slivers);
336

337
  /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
338 339 340 341
  ///
  /// 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.
342
  final AxisDirection axisDirection;
343

344 345 346 347 348 349 350 351 352
  /// 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].
353
  final AxisDirection? crossAxisDirection;
354

355 356 357 358 359 360 361 362
  /// 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].
363 364
  final ViewportOffset offset;

365
  /// {@macro flutter.material.Material.clipBehavior}
366 367 368 369
  ///
  /// Defaults to [Clip.hardEdge].
  final Clip clipBehavior;

370 371
  @override
  RenderShrinkWrappingViewport createRenderObject(BuildContext context) {
372
    return RenderShrinkWrappingViewport(
373
      axisDirection: axisDirection,
374
      crossAxisDirection: crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection),
375
      offset: offset,
376
      clipBehavior: clipBehavior,
377 378 379 380 381 382 383
    );
  }

  @override
  void updateRenderObject(BuildContext context, RenderShrinkWrappingViewport renderObject) {
    renderObject
      ..axisDirection = axisDirection
384
      ..crossAxisDirection = crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection(context, axisDirection)
385 386
      ..offset = offset
      ..clipBehavior = clipBehavior;
387 388 389
  }

  @override
390 391
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
392 393 394
    properties.add(EnumProperty<AxisDirection>('axisDirection', axisDirection));
    properties.add(EnumProperty<AxisDirection>('crossAxisDirection', crossAxisDirection, defaultValue: null));
    properties.add(DiagnosticsProperty<ViewportOffset>('offset', offset));
395 396
  }
}