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

5 6
// @dart = 2.8

Ian Hickson's avatar
Ian Hickson committed
7 8 9 10 11
import 'package:flutter/foundation.dart';
import 'package:flutter/rendering.dart';

import 'framework.dart';

12
/// Delegate for configuring a [SliverPersistentHeader].
13
abstract class SliverPersistentHeaderDelegate {
Ian Hickson's avatar
Ian Hickson committed
14 15
  /// Abstract const constructor. This constructor enables subclasses to provide
  /// const constructors so that they can be used in const expressions.
16
  const SliverPersistentHeaderDelegate();
Ian Hickson's avatar
Ian Hickson committed
17

18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
  /// The widget to place inside the [SliverPersistentHeader].
  ///
  /// The `context` is the [BuildContext] of the sliver.
  ///
  /// The `shrinkOffset` is a distance from [maxExtent] towards [minExtent]
  /// representing the current amount by which the sliver has been shrunk. When
  /// the `shrinkOffset` is zero, the contents will be rendered with a dimension
  /// of [maxExtent] in the main axis. When `shrinkOffset` equals the difference
  /// between [maxExtent] and [minExtent] (a positive number), the contents will
  /// be rendered with a dimension of [minExtent] in the main axis. The
  /// `shrinkOffset` will always be a positive number in that range.
  ///
  /// The `overlapsContent` argument is true if subsequent slivers (if any) will
  /// be rendered beneath this one, and false if the sliver will not have any
  /// contents below it. Typically this is used to decide whether to draw a
  /// shadow to simulate the sliver being above the contents below it. Typically
  /// this is true when `shrinkOffset` is at its greatest value and false
  /// otherwise, but that is not guaranteed. See [NestedScrollView] for an
  /// example of a case where `overlapsContent`'s value can be unrelated to
  /// `shrinkOffset`.
38 39
  Widget build(BuildContext context, double shrinkOffset, bool overlapsContent);

40 41 42 43 44 45 46 47 48
  /// The smallest size to allow the header to reach, when it shrinks at the
  /// start of the viewport.
  ///
  /// This must return a value equal to or less than [maxExtent].
  ///
  /// This value should not change over the lifetime of the delegate. It should
  /// be based entirely on the constructor arguments passed to the delegate. See
  /// [shouldRebuild], which must return true if a new delegate would return a
  /// different value.
49
  double get minExtent;
Ian Hickson's avatar
Ian Hickson committed
50

51 52 53 54 55 56 57 58 59
  /// The size of the header when it is not shrinking at the top of the
  /// viewport.
  ///
  /// This must return a value equal to or greater than [minExtent].
  ///
  /// This value should not change over the lifetime of the delegate. It should
  /// be based entirely on the constructor arguments passed to the delegate. See
  /// [shouldRebuild], which must return true if a new delegate would return a
  /// different value.
Ian Hickson's avatar
Ian Hickson committed
60 61
  double get maxExtent;

62 63 64 65
  /// Specifies how floating headers should animate in and out of view.
  ///
  /// If the value of this property is null, then floating headers will
  /// not animate into place.
66 67 68 69 70
  ///
  /// This is only used for floating headers (those with
  /// [SliverPersistentHeader.floating] set to true).
  ///
  /// Defaults to null.
71
  FloatingHeaderSnapConfiguration get snapConfiguration => null;
72

73 74 75 76 77 78 79 80 81 82 83
  /// Specifies an [AsyncCallback] and offset for execution.
  ///
  /// If the value of this property is null, then callback will not be
  /// triggered.
  ///
  /// This is only used for stretching headers (those with
  /// [SliverAppBar.stretch] set to true).
  ///
  /// Defaults to null.
  OverScrollHeaderStretchConfiguration get stretchConfiguration => null;

84 85 86 87 88 89 90 91 92 93
  /// Whether this delegate is meaningfully different from the old delegate.
  ///
  /// If this returns false, then the header might not be rebuilt, even though
  /// the instance of the delegate changed.
  ///
  /// This must return true if `oldDelegate` and this object would return
  /// different values for [minExtent], [maxExtent], [snapConfiguration], or
  /// would return a meaningfully different widget tree from [build] for the
  /// same arguments.
  bool shouldRebuild(covariant SliverPersistentHeaderDelegate oldDelegate);
Ian Hickson's avatar
Ian Hickson committed
94 95
}

96 97 98 99 100
/// A sliver whose size varies when the sliver is scrolled to the edge
/// of the viewport opposite the sliver's [GrowthDirection].
///
/// In the normal case of a [CustomScrollView] with no centered sliver, this
/// sliver will vary its size when scrolled to the leading edge of the viewport.
101 102 103
///
/// This is the layout primitive that [SliverAppBar] uses for its
/// shrinking/growing effect.
104
class SliverPersistentHeader extends StatelessWidget {
105 106 107 108
  /// Creates a sliver that varies its size when it is scrolled to the start of
  /// a viewport.
  ///
  /// The [delegate], [pinned], and [floating] arguments must not be null.
109
  const SliverPersistentHeader({
Ian Hickson's avatar
Ian Hickson committed
110 111
    Key key,
    @required this.delegate,
112 113
    this.pinned = false,
    this.floating = false,
114 115 116 117
  }) : assert(delegate != null),
       assert(pinned != null),
       assert(floating != null),
       super(key: key);
Ian Hickson's avatar
Ian Hickson committed
118

119 120 121 122 123 124 125 126 127
  /// Configuration for the sliver's layout.
  ///
  /// The delegate provides the following information:
  ///
  ///  * The minimum and maximum dimensions of the sliver.
  ///
  ///  * The builder for generating the widgets of the sliver.
  ///
  ///  * The instructions for snapping the scroll offset, if [floating] is true.
128
  final SliverPersistentHeaderDelegate delegate;
Ian Hickson's avatar
Ian Hickson committed
129

130 131 132 133 134
  /// Whether to stick the header to the start of the viewport once it has
  /// reached its minimum size.
  ///
  /// If this is false, the header will continue scrolling off the screen after
  /// it has shrunk to its minimum extent.
Ian Hickson's avatar
Ian Hickson committed
135 136
  final bool pinned;

137 138 139 140 141 142 143 144
  /// Whether the header should immediately grow again if the user reverses
  /// scroll direction.
  ///
  /// If this is false, the header only grows again once the user reaches the
  /// part of the viewport that contains the sliver.
  ///
  /// The [delegate]'s [SliverPersistentHeaderDelegate.snapConfiguration] is
  /// ignored unless [floating] is true.
Ian Hickson's avatar
Ian Hickson committed
145 146 147 148
  final bool floating;

  @override
  Widget build(BuildContext context) {
149
    if (floating && pinned)
150
      return _SliverFloatingPinnedPersistentHeader(delegate: delegate);
Ian Hickson's avatar
Ian Hickson committed
151
    if (pinned)
152
      return _SliverPinnedPersistentHeader(delegate: delegate);
Ian Hickson's avatar
Ian Hickson committed
153
    if (floating)
154 155
      return _SliverFloatingPersistentHeader(delegate: delegate);
    return _SliverScrollingPersistentHeader(delegate: delegate);
Ian Hickson's avatar
Ian Hickson committed
156 157 158
  }

  @override
159 160
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
161 162 163 164 165 166
    properties.add(
      DiagnosticsProperty<SliverPersistentHeaderDelegate>(
        'delegate',
        delegate,
      )
    );
167 168 169 170
    final List<String> flags = <String>[
      if (pinned) 'pinned',
      if (floating) 'floating',
    ];
Ian Hickson's avatar
Ian Hickson committed
171 172
    if (flags.isEmpty)
      flags.add('normal');
173
    properties.add(IterableProperty<String>('mode', flags));
Ian Hickson's avatar
Ian Hickson committed
174 175 176
  }
}

177 178
class _SliverPersistentHeaderElement extends RenderObjectElement {
  _SliverPersistentHeaderElement(_SliverPersistentHeaderRenderObjectWidget widget) : super(widget);
Ian Hickson's avatar
Ian Hickson committed
179 180

  @override
181
  _SliverPersistentHeaderRenderObjectWidget get widget => super.widget as _SliverPersistentHeaderRenderObjectWidget;
Ian Hickson's avatar
Ian Hickson committed
182 183

  @override
184
  _RenderSliverPersistentHeaderForWidgetsMixin get renderObject => super.renderObject as _RenderSliverPersistentHeaderForWidgetsMixin;
Ian Hickson's avatar
Ian Hickson committed
185 186 187 188 189 190 191 192 193 194 195 196 197 198

  @override
  void mount(Element parent, dynamic newSlot) {
    super.mount(parent, newSlot);
    renderObject._element = this;
  }

  @override
  void unmount() {
    super.unmount();
    renderObject._element = null;
  }

  @override
199 200
  void update(_SliverPersistentHeaderRenderObjectWidget newWidget) {
    final _SliverPersistentHeaderRenderObjectWidget oldWidget = widget;
Ian Hickson's avatar
Ian Hickson committed
201
    super.update(newWidget);
202 203
    final SliverPersistentHeaderDelegate newDelegate = newWidget.delegate;
    final SliverPersistentHeaderDelegate oldDelegate = oldWidget.delegate;
Ian Hickson's avatar
Ian Hickson committed
204 205 206 207 208 209 210
    if (newDelegate != oldDelegate &&
        (newDelegate.runtimeType != oldDelegate.runtimeType || newDelegate.shouldRebuild(oldDelegate)))
      renderObject.triggerRebuild();
  }

  @override
  void performRebuild() {
211
    super.performRebuild();
Ian Hickson's avatar
Ian Hickson committed
212 213 214 215 216
    renderObject.triggerRebuild();
  }

  Element child;

217
  void _build(double shrinkOffset, bool overlapsContent) {
Ian Hickson's avatar
Ian Hickson committed
218
    owner.buildScope(this, () {
219 220 221 222 223 224 225 226 227
      child = updateChild(
        child,
        widget.delegate.build(
          this,
          shrinkOffset,
          overlapsContent
        ),
        null,
      );
Ian Hickson's avatar
Ian Hickson committed
228 229 230 231 232 233 234
    });
  }

  @override
  void forgetChild(Element child) {
    assert(child == this.child);
    this.child = null;
235
    super.forgetChild(child);
Ian Hickson's avatar
Ian Hickson committed
236 237 238
  }

  @override
239
  void insertChildRenderObject(covariant RenderBox child, dynamic slot) {
240
    assert(renderObject.debugValidateChild(child));
Ian Hickson's avatar
Ian Hickson committed
241 242 243 244
    renderObject.child = child;
  }

  @override
245
  void moveChildRenderObject(covariant RenderObject child, dynamic slot) {
Ian Hickson's avatar
Ian Hickson committed
246 247 248 249
    assert(false);
  }

  @override
250
  void removeChildRenderObject(covariant RenderObject child) {
Ian Hickson's avatar
Ian Hickson committed
251 252 253 254 255
    renderObject.child = null;
  }

  @override
  void visitChildren(ElementVisitor visitor) {
256 257
    if (child != null)
      visitor(child);
Ian Hickson's avatar
Ian Hickson committed
258 259 260
  }
}

261
abstract class _SliverPersistentHeaderRenderObjectWidget extends RenderObjectWidget {
262
  const _SliverPersistentHeaderRenderObjectWidget({
Ian Hickson's avatar
Ian Hickson committed
263 264
    Key key,
    @required this.delegate,
265 266
  }) : assert(delegate != null),
       super(key: key);
Ian Hickson's avatar
Ian Hickson committed
267

268
  final SliverPersistentHeaderDelegate delegate;
Ian Hickson's avatar
Ian Hickson committed
269 270

  @override
271
  _SliverPersistentHeaderElement createElement() => _SliverPersistentHeaderElement(this);
Ian Hickson's avatar
Ian Hickson committed
272 273

  @override
274
  _RenderSliverPersistentHeaderForWidgetsMixin createRenderObject(BuildContext context);
Ian Hickson's avatar
Ian Hickson committed
275 276

  @override
277
  void debugFillProperties(DiagnosticPropertiesBuilder description) {
278
    super.debugFillProperties(description);
279 280 281 282 283 284
    description.add(
      DiagnosticsProperty<SliverPersistentHeaderDelegate>(
        'delegate',
        delegate,
      )
    );
Ian Hickson's avatar
Ian Hickson committed
285 286 287
  }
}

288
mixin _RenderSliverPersistentHeaderForWidgetsMixin on RenderSliverPersistentHeader {
289
  _SliverPersistentHeaderElement _element;
Ian Hickson's avatar
Ian Hickson committed
290

291 292 293
  @override
  double get minExtent => _element.widget.delegate.minExtent;

Ian Hickson's avatar
Ian Hickson committed
294 295 296 297
  @override
  double get maxExtent => _element.widget.delegate.maxExtent;

  @override
298
  void updateChild(double shrinkOffset, bool overlapsContent) {
Ian Hickson's avatar
Ian Hickson committed
299
    assert(_element != null);
300
    _element._build(shrinkOffset, overlapsContent);
Ian Hickson's avatar
Ian Hickson committed
301 302 303 304
  }

  @protected
  void triggerRebuild() {
305
    markNeedsLayout();
Ian Hickson's avatar
Ian Hickson committed
306 307 308
  }
}

309
class _SliverScrollingPersistentHeader extends _SliverPersistentHeaderRenderObjectWidget {
310
  const _SliverScrollingPersistentHeader({
Ian Hickson's avatar
Ian Hickson committed
311
    Key key,
312
    @required SliverPersistentHeaderDelegate delegate,
313 314 315 316
  }) : super(
    key: key,
    delegate: delegate,
  );
Ian Hickson's avatar
Ian Hickson committed
317 318

  @override
319
  _RenderSliverPersistentHeaderForWidgetsMixin createRenderObject(BuildContext context) {
320 321 322
    return _RenderSliverScrollingPersistentHeaderForWidgets(
      stretchConfiguration: delegate.stretchConfiguration
    );
Ian Hickson's avatar
Ian Hickson committed
323 324 325
  }
}

326
class _RenderSliverScrollingPersistentHeaderForWidgets extends RenderSliverScrollingPersistentHeader
327 328 329 330 331 332 333 334 335
  with _RenderSliverPersistentHeaderForWidgetsMixin {
  _RenderSliverScrollingPersistentHeaderForWidgets({
    RenderBox child,
    OverScrollHeaderStretchConfiguration stretchConfiguration,
  }) : super(
    child: child,
    stretchConfiguration: stretchConfiguration,
  );
}
Ian Hickson's avatar
Ian Hickson committed
336

337
class _SliverPinnedPersistentHeader extends _SliverPersistentHeaderRenderObjectWidget {
338
  const _SliverPinnedPersistentHeader({
Ian Hickson's avatar
Ian Hickson committed
339
    Key key,
340
    @required SliverPersistentHeaderDelegate delegate,
341 342 343 344
  }) : super(
    key: key,
    delegate: delegate,
  );
Ian Hickson's avatar
Ian Hickson committed
345 346

  @override
347
  _RenderSliverPersistentHeaderForWidgetsMixin createRenderObject(BuildContext context) {
348 349 350
    return _RenderSliverPinnedPersistentHeaderForWidgets(
      stretchConfiguration: delegate.stretchConfiguration
    );
Ian Hickson's avatar
Ian Hickson committed
351 352 353
  }
}

354 355 356 357 358 359 360 361 362 363
class _RenderSliverPinnedPersistentHeaderForWidgets extends RenderSliverPinnedPersistentHeader
  with _RenderSliverPersistentHeaderForWidgetsMixin {
  _RenderSliverPinnedPersistentHeaderForWidgets({
    RenderBox child,
    OverScrollHeaderStretchConfiguration stretchConfiguration,
  }) : super(
    child: child,
    stretchConfiguration: stretchConfiguration,
  );
}
Ian Hickson's avatar
Ian Hickson committed
364

365
class _SliverFloatingPersistentHeader extends _SliverPersistentHeaderRenderObjectWidget {
366
  const _SliverFloatingPersistentHeader({
Ian Hickson's avatar
Ian Hickson committed
367
    Key key,
368
    @required SliverPersistentHeaderDelegate delegate,
369 370 371 372
  }) : super(
    key: key,
    delegate: delegate,
  );
Ian Hickson's avatar
Ian Hickson committed
373 374

  @override
375
  _RenderSliverPersistentHeaderForWidgetsMixin createRenderObject(BuildContext context) {
376 377 378 379
    return _RenderSliverFloatingPersistentHeaderForWidgets(
      snapConfiguration: delegate.snapConfiguration,
      stretchConfiguration: delegate.stretchConfiguration,
    );
380 381 382 383 384
  }

  @override
  void updateRenderObject(BuildContext context, _RenderSliverFloatingPersistentHeaderForWidgets renderObject) {
    renderObject.snapConfiguration = delegate.snapConfiguration;
385
    renderObject.stretchConfiguration = delegate.stretchConfiguration;
Ian Hickson's avatar
Ian Hickson committed
386 387 388
  }
}

389 390
class _RenderSliverFloatingPinnedPersistentHeaderForWidgets extends RenderSliverFloatingPinnedPersistentHeader
  with _RenderSliverPersistentHeaderForWidgetsMixin {
391 392 393
  _RenderSliverFloatingPinnedPersistentHeaderForWidgets({
    RenderBox child,
    FloatingHeaderSnapConfiguration snapConfiguration,
394 395 396 397 398 399
    OverScrollHeaderStretchConfiguration stretchConfiguration,
  }) : super(
    child: child,
    snapConfiguration: snapConfiguration,
    stretchConfiguration: stretchConfiguration,
  );
400
}
401 402

class _SliverFloatingPinnedPersistentHeader extends _SliverPersistentHeaderRenderObjectWidget {
403
  const _SliverFloatingPinnedPersistentHeader({
404 405
    Key key,
    @required SliverPersistentHeaderDelegate delegate,
406 407 408 409
  }) : super(
    key: key,
    delegate: delegate,
  );
410 411 412

  @override
  _RenderSliverPersistentHeaderForWidgetsMixin createRenderObject(BuildContext context) {
413 414 415 416
    return _RenderSliverFloatingPinnedPersistentHeaderForWidgets(
      snapConfiguration: delegate.snapConfiguration,
      stretchConfiguration: delegate.stretchConfiguration,
    );
417 418 419 420 421
  }

  @override
  void updateRenderObject(BuildContext context, _RenderSliverFloatingPinnedPersistentHeaderForWidgets renderObject) {
    renderObject.snapConfiguration = delegate.snapConfiguration;
422
    renderObject.stretchConfiguration = delegate.stretchConfiguration;
423 424 425
  }
}

426 427
class _RenderSliverFloatingPersistentHeaderForWidgets extends RenderSliverFloatingPersistentHeader
  with _RenderSliverPersistentHeaderForWidgetsMixin {
428 429 430
  _RenderSliverFloatingPersistentHeaderForWidgets({
    RenderBox child,
    FloatingHeaderSnapConfiguration snapConfiguration,
431 432 433 434 435 436
    OverScrollHeaderStretchConfiguration stretchConfiguration,
  }) : super(
    child: child,
    snapConfiguration: snapConfiguration,
    stretchConfiguration: stretchConfiguration,
  );
437
}