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

import 'dart:math' as math;

import 'package:flutter/foundation.dart';
import 'package:flutter/gestures.dart';
import 'package:vector_math/vector_math_64.dart';

11
import 'box.dart';
12 13
import 'debug.dart';
import 'object.dart';
14
import 'viewport.dart';
15
import 'viewport_offset.dart';
16 17 18 19 20 21 22 23 24 25 26 27 28 29

// CORE TYPES FOR SLIVERS
// The RenderSliver base class and its helper types.

/// The direction in which a sliver's contents are ordered, relative to the
/// scroll offset axis.
///
/// For example, a vertical alphabetical list that is going [AxisDirection.down]
/// with a [GrowthDirection.forward] would have the A at the top and the Z at
/// the bottom, with the A adjacent to the origin, as would such a list going
/// [AxisDirection.up] with a [GrowthDirection.reverse]. On the other hand, a
/// vertical alphabetical list that is going [AxisDirection.down] with a
/// [GrowthDirection.reverse] would have the Z at the top (at scroll offset
/// zero) and the A below it.
30 31 32
///
/// The direction in which the scroll offset increases is given by
/// [applyGrowthDirectionToAxisDirection].
33
enum GrowthDirection {
34 35
  /// This sliver's contents are ordered in the same direction as the
  /// [AxisDirection].
36 37
  forward,

38 39
  /// This sliver's contents are ordered in the opposite direction of the
  /// [AxisDirection].
40 41 42
  reverse,
}

43 44 45 46 47 48 49 50 51
/// Flips the [AxisDirection] if the [GrowthDirection] is [GrowthDirection.reverse].
///
/// Specifically, returns `axisDirection` if `growthDirection` is
/// [GrowthDirection.forward], otherwise returns [flipAxisDirection] applied to
/// `axisDirection`.
///
/// This function is useful in [RenderSliver] subclasses that are given both an
/// [AxisDirection] and a [GrowthDirection] and wish to compute the
/// [AxisDirection] in which growth will occur.
52 53 54 55 56 57 58
AxisDirection applyGrowthDirectionToAxisDirection(AxisDirection axisDirection, GrowthDirection growthDirection) {
  assert(axisDirection != null);
  assert(growthDirection != null);
  switch (growthDirection) {
    case GrowthDirection.forward:
      return axisDirection;
    case GrowthDirection.reverse:
59
      return flipAxisDirection(axisDirection);
60 61 62
  }
}

63 64 65 66 67 68 69 70 71
/// Flips the [ScrollDirection] if the [GrowthDirection] is [GrowthDirection.reverse].
///
/// Specifically, returns `scrollDirection` if `scrollDirection` is
/// [GrowthDirection.forward], otherwise returns [flipScrollDirection] applied to
/// `scrollDirection`.
///
/// This function is useful in [RenderSliver] subclasses that are given both an
/// [ScrollDirection] and a [GrowthDirection] and wish to compute the
/// [ScrollDirection] in which growth will occur.
Josh Soref's avatar
Josh Soref committed
72
ScrollDirection applyGrowthDirectionToScrollDirection(ScrollDirection scrollDirection, GrowthDirection growthDirection) {
73 74 75 76 77 78 79 80 81 82
  assert(scrollDirection != null);
  assert(growthDirection != null);
  switch (growthDirection) {
    case GrowthDirection.forward:
      return scrollDirection;
    case GrowthDirection.reverse:
      return flipScrollDirection(scrollDirection);
  }
}

83 84 85 86 87 88 89
/// Immutable layout constraints for [RenderSliver] layout.
///
/// The [SliverConstraints] describe the current scroll state of the viewport
/// from the point of view of the sliver receiving the constraints. For example,
/// a [scrollOffset] of zero means that the leading edge of the sliver is
/// visible in the viewport, not that the viewport itself has a zero scroll
/// offset.
90
class SliverConstraints extends Constraints {
91 92 93
  /// Creates sliver constraints with the given information.
  ///
  /// All of the argument must not be null.
94
  const SliverConstraints({
95 96 97 98 99 100 101 102 103 104 105 106
    required this.axisDirection,
    required this.growthDirection,
    required this.userScrollDirection,
    required this.scrollOffset,
    required this.precedingScrollExtent,
    required this.overlap,
    required this.remainingPaintExtent,
    required this.crossAxisExtent,
    required this.crossAxisDirection,
    required this.viewportMainAxisExtent,
    required this.remainingCacheExtent,
    required this.cacheOrigin,
107 108 109 110
  }) : assert(axisDirection != null),
       assert(growthDirection != null),
       assert(userScrollDirection != null),
       assert(scrollOffset != null),
111
       assert(precedingScrollExtent != null),
112 113 114
       assert(overlap != null),
       assert(remainingPaintExtent != null),
       assert(crossAxisExtent != null),
115
       assert(crossAxisDirection != null),
116 117 118
       assert(viewportMainAxisExtent != null),
       assert(remainingCacheExtent != null),
       assert(cacheOrigin != null);
119

120 121
  /// Creates a copy of this object but with the given fields replaced with the
  /// new values.
122
  SliverConstraints copyWith({
123 124 125 126 127 128 129 130 131 132 133 134
    AxisDirection? axisDirection,
    GrowthDirection? growthDirection,
    ScrollDirection? userScrollDirection,
    double? scrollOffset,
    double? precedingScrollExtent,
    double? overlap,
    double? remainingPaintExtent,
    double? crossAxisExtent,
    AxisDirection? crossAxisDirection,
    double? viewportMainAxisExtent,
    double? remainingCacheExtent,
    double? cacheOrigin,
135
  }) {
136
    return SliverConstraints(
137 138 139 140
      axisDirection: axisDirection ?? this.axisDirection,
      growthDirection: growthDirection ?? this.growthDirection,
      userScrollDirection: userScrollDirection ?? this.userScrollDirection,
      scrollOffset: scrollOffset ?? this.scrollOffset,
141
      precedingScrollExtent: precedingScrollExtent ?? this.precedingScrollExtent,
142 143 144
      overlap: overlap ?? this.overlap,
      remainingPaintExtent: remainingPaintExtent ?? this.remainingPaintExtent,
      crossAxisExtent: crossAxisExtent ?? this.crossAxisExtent,
145
      crossAxisDirection: crossAxisDirection ?? this.crossAxisDirection,
146
      viewportMainAxisExtent: viewportMainAxisExtent ?? this.viewportMainAxisExtent,
147 148
      remainingCacheExtent: remainingCacheExtent ?? this.remainingCacheExtent,
      cacheOrigin: cacheOrigin ?? this.cacheOrigin,
149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
    );
  }

  /// The direction in which the [scrollOffset] and [remainingPaintExtent]
  /// increase.
  final AxisDirection axisDirection;

  /// The direction in which the contents of slivers are ordered, relative to
  /// the [axisDirection].
  ///
  /// For example, if the [axisDirection] is [AxisDirection.up], and the
  /// [growthDirection] is [GrowthDirection.forward], then an alphabetical list
  /// will have A at the bottom, then B, then C, and so forth, with Z at the
  /// top, with the bottom of the A at scroll offset zero, and the top of the Z
  /// at the highest scroll offset.
  ///
  /// If a viewport has an overall [AxisDirection] of [AxisDirection.down], then
  /// slivers above the absolute zero offset will have an axis of
  /// [AxisDirection.up] and a growth direction of [GrowthDirection.reverse],
  /// while slivers below the absolute zero offset will have the same axis
  /// direction as the viewport and a growth direction of
  /// [GrowthDirection.forward]. (The slivers with a reverse growth direction
  /// still see only positive scroll offsets; the scroll offsets are reversed as
  /// well, with zero at the absolute zero point, and positive numbers going
  /// away from there.)
  ///
175 176
  /// Normally, the absolute zero offset is determined by the viewport's
  /// [RenderViewport.center] and [RenderViewport.anchor] properties.
177 178 179 180 181 182 183
  final GrowthDirection growthDirection;

  /// The direction in which the user is attempting to scroll, relative to the
  /// [axisDirection] and [growthDirection].
  ///
  /// For example, if [growthDirection] is [GrowthDirection.reverse] and
  /// [axisDirection] is [AxisDirection.down], then a
184
  /// [ScrollDirection.forward] means that the user is scrolling up, in the
185
  /// positive [scrollOffset] direction.
186 187 188 189 190 191 192 193 194
  ///
  /// If the _user_ is not scrolling, this will return [ScrollDirection.idle]
  /// even if there is (for example) a [ScrollActivity] currently animating the
  /// position.
  ///
  /// This is used by some slivers to determine how to react to a change in
  /// scroll offset. For example, [RenderSliverFloatingPersistentHeader] will
  /// only expand a floating app bar when the [userScrollDirection] is in the
  /// positive scroll offset direction.
195 196 197
  final ScrollDirection userScrollDirection;

  /// The scroll offset, in this sliver's coordinate system, that corresponds to
198 199 200
  /// the earliest visible part of this sliver in the [AxisDirection] if
  /// [growthDirection] is [GrowthDirection.forward] or in the opposite
  /// [AxisDirection] direction if [growthDirection] is [GrowthDirection.reverse].
201
  ///
202 203 204
  /// For example, if [AxisDirection] is [AxisDirection.down] and [growthDirection]
  /// is [GrowthDirection.forward], then scroll offset is the amount the top of
  /// the sliver has been scrolled past the top of the viewport.
205 206 207 208 209 210 211
  ///
  /// This value is typically used to compute whether this sliver should still
  /// protrude into the viewport via [SliverGeometry.paintExtent] and
  /// [SliverGeometry.layoutExtent] considering how far the beginning of the
  /// sliver is above the beginning of the viewport.
  ///
  /// For slivers whose top is not past the top of the viewport, the
212 213 214 215
  /// [scrollOffset] is `0` when [AxisDirection] is [AxisDirection.down] and
  /// [growthDirection] is [GrowthDirection.forward]. The set of slivers with
  /// [scrollOffset] `0` includes all the slivers that are below the bottom of the
  /// viewport.
216 217 218 219
  ///
  /// [SliverConstraints.remainingPaintExtent] is typically used to accomplish
  /// the same goal of computing whether scrolled out slivers should still
  /// partially 'protrude in' from the bottom of the viewport.
220 221 222 223 224
  ///
  /// Whether this corresponds to the beginning or the end of the sliver's
  /// contents depends on the [growthDirection].
  final double scrollOffset;

225 226
  /// The scroll distance that has been consumed by all [RenderSliver]s that
  /// came before this [RenderSliver].
227 228 229
  ///
  /// # Edge Cases
  ///
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
  /// [RenderSliver]s often lazily create their internal content as layout
  /// occurs, e.g., [SliverList]. In this case, when [RenderSliver]s exceed the
  /// viewport, their children are built lazily, and the [RenderSliver] does not
  /// have enough information to estimate its total extent,
  /// [precedingScrollExtent] will be [double.infinity] for all [RenderSliver]s
  /// that appear after the lazily constructed child. This is because a total
  /// [SliverGeometry.scrollExtent] cannot be calculated unless all inner
  /// children have been created and sized, or the number of children and
  /// estimated extents are provided. The infinite [SliverGeometry.scrollExtent]
  /// will become finite as soon as enough information is available to estimate
  /// the overall extent of all children within the given [RenderSliver].
  ///
  /// [RenderSliver]s may legitimately be infinite, meaning that they can scroll
  /// content forever without reaching the end. For any [RenderSliver]s that
  /// appear after the infinite [RenderSliver], the [precedingScrollExtent] will
  /// be [double.infinity].
246 247
  final double precedingScrollExtent;

248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
  /// The number of pixels from where the pixels corresponding to the
  /// [scrollOffset] will be painted up to the first pixel that has not yet been
  /// painted on by an earlier sliver, in the [axisDirection].
  ///
  /// For example, if the previous sliver had a [SliverGeometry.paintExtent] of
  /// 100.0 pixels but a [SliverGeometry.layoutExtent] of only 50.0 pixels,
  /// then the [overlap] of this sliver will be 50.0.
  ///
  /// This is typically ignored unless the sliver is itself going to be pinned
  /// or floating and wants to avoid doing so under the previous sliver.
  final double overlap;

  /// The number of pixels of content that the sliver should consider providing.
  /// (Providing more pixels than this is inefficient.)
  ///
  /// The actual number of pixels provided should be specified in the
  /// [RenderSliver.geometry] as [SliverGeometry.paintExtent].
265 266 267 268 269 270
  ///
  /// This value may be infinite, for example if the viewport is an
  /// unconstrained [RenderShrinkWrappingViewport].
  ///
  /// This value may be 0.0, for example if the sliver is scrolled off the
  /// bottom of a downwards vertical viewport.
271 272
  final double remainingPaintExtent;

273 274
  /// The number of pixels in the cross-axis.
  ///
275
  /// For a vertical list, this is the width of the sliver.
276 277
  final double crossAxisExtent;

278 279 280 281 282 283
  /// The direction in which children should be placed in the cross axis.
  ///
  /// Typically used in vertical lists to describe whether the ambient
  /// [TextDirection] is [TextDirection.rtl] or [TextDirection.ltr].
  final AxisDirection crossAxisDirection;

284 285 286 287 288
  /// The number of pixels the viewport can display in the main axis.
  ///
  /// For a vertical list, this is the height of the viewport.
  final double viewportMainAxisExtent;

289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307
  /// Where the cache area starts relative to the [scrollOffset].
  ///
  /// Slivers that fall into the cache area located before the leading edge and
  /// after the trailing edge of the viewport should still render content
  /// because they are about to become visible when the user scrolls.
  ///
  /// The [cacheOrigin] describes where the [remainingCacheExtent] starts relative
  /// to the [scrollOffset]. A cache origin of 0 means that the sliver does not
  /// have to provide any content before the current [scrollOffset]. A
  /// [cacheOrigin] of -250.0 means that even though the first visible part of
  /// the sliver will be at the provided [scrollOffset], the sliver should
  /// render content starting 250.0 before the [scrollOffset] to fill the
  /// cache area of the viewport.
  ///
  /// The [cacheOrigin] is always negative or zero and will never exceed
  /// -[scrollOffset]. In other words, a sliver is never asked to provide
  /// content before its zero [scrollOffset].
  ///
  /// See also:
308
  ///
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327
  ///  * [RenderViewport.cacheExtent] for a description of a viewport's cache area.
  final double cacheOrigin;


  /// Describes how much content the sliver should provide starting from the
  /// [cacheOrigin].
  ///
  /// Not all content in the [remainingCacheExtent] will be visible as some
  /// of it might fall into the cache area of the viewport.
  ///
  /// Each sliver should start laying out content at the [cacheOrigin] and
  /// try to provide as much content as the [remainingCacheExtent] allows.
  ///
  /// The [remainingCacheExtent] is always larger or equal to the
  /// [remainingPaintExtent]. Content, that falls in the [remainingCacheExtent],
  /// but is outside of the [remainingPaintExtent] is currently not visible
  /// in the viewport.
  ///
  /// See also:
328
  ///
329 330 331
  ///  * [RenderViewport.cacheExtent] for a description of a viewport's cache area.
  final double remainingCacheExtent;

332
  /// The axis along which the [scrollOffset] and [remainingPaintExtent] are measured.
333
  Axis get axis => axisDirectionToAxis(axisDirection);
334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367

  /// Return what the [growthDirection] would be if the [axisDirection] was
  /// either [AxisDirection.down] or [AxisDirection.right].
  ///
  /// This is the same as [growthDirection] unless the [axisDirection] is either
  /// [AxisDirection.up] or [AxisDirection.left], in which case it is the
  /// opposite growth direction.
  ///
  /// This can be useful in combination with [axis] to view the [axisDirection]
  /// and [growthDirection] in different terms.
  GrowthDirection get normalizedGrowthDirection {
    assert(axisDirection != null);
    switch (axisDirection) {
      case AxisDirection.down:
      case AxisDirection.right:
        return growthDirection;
      case AxisDirection.up:
      case AxisDirection.left:
        switch (growthDirection) {
          case GrowthDirection.forward:
            return GrowthDirection.reverse;
          case GrowthDirection.reverse:
            return GrowthDirection.forward;
        }
    }
  }

  @override
  bool get isTight => false;

  @override
  bool get isNormalized {
    return scrollOffset >= 0.0
        && crossAxisExtent >= 0.0
368
        && axisDirectionToAxis(axisDirection) != axisDirectionToAxis(crossAxisDirection)
369
        && viewportMainAxisExtent >= 0.0
370 371 372
        && remainingPaintExtent >= 0.0;
  }

373 374 375 376 377 378 379 380
  /// Returns [BoxConstraints] that reflects the sliver constraints.
  ///
  /// The `minExtent` and `maxExtent` are used as the constraints in the main
  /// axis. If non-null, the given `crossAxisExtent` is used as a tight
  /// constraint in the cross axis. Otherwise, the [crossAxisExtent] from this
  /// object is used as a constraint in the cross axis.
  ///
  /// Useful for slivers that have [RenderBox] children.
381
  BoxConstraints asBoxConstraints({
382 383
    double minExtent = 0.0,
    double maxExtent = double.infinity,
384
    double? crossAxisExtent,
385
  }) {
386
    crossAxisExtent ??= this.crossAxisExtent;
387 388
    switch (axis) {
      case Axis.horizontal:
389
        return BoxConstraints(
390 391 392 393 394 395
          minHeight: crossAxisExtent,
          maxHeight: crossAxisExtent,
          minWidth: minExtent,
          maxWidth: maxExtent,
        );
      case Axis.vertical:
396
        return BoxConstraints(
397 398 399 400 401 402 403 404 405 406
          minWidth: crossAxisExtent,
          maxWidth: crossAxisExtent,
          minHeight: minExtent,
          maxHeight: maxExtent,
        );
    }
  }

  @override
  bool debugAssertIsValid({
407
    bool isAppliedConstraint = false,
408
    InformationCollector? informationCollector,
409
  }) {
410
    assert(() {
411 412
      bool hasErrors = false;
      final StringBuffer errorMessage = StringBuffer('\n');
413 414 415
      void verify(bool check, String message) {
        if (check)
          return;
416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433
        hasErrors = true;
        errorMessage.writeln('  $message');
      }
      void verifyDouble(double property, String name, {bool mustBePositive = false, bool mustBeNegative = false}) {
        verify(property != null, 'The "$name" is null.');
        if (property.isNaN) {
          String additional = '.';
          if (mustBePositive) {
            additional = ', expected greater than or equal to zero.';
          } else if (mustBeNegative) {
            additional = ', expected less than or equal to zero.';
          }
          verify(false, 'The "$name" is NaN$additional');
        } else if (mustBePositive) {
          verify(property >= 0.0, 'The "$name" is negative.');
        } else if (mustBeNegative) {
          verify(property <= 0.0, 'The "$name" is positive.');
        }
434 435 436
      }
      verify(axis != null, 'The "axis" is null.');
      verify(growthDirection != null, 'The "growthDirection" is null.');
437 438 439 440
      verifyDouble(scrollOffset, 'scrollOffset');
      verifyDouble(overlap, 'overlap');
      verifyDouble(crossAxisExtent, 'crossAxisExtent');
      verifyDouble(scrollOffset, 'scrollOffset', mustBePositive: true);
441 442
      verify(crossAxisDirection != null, 'The "crossAxisDirection" is null.');
      verify(axisDirectionToAxis(axisDirection) != axisDirectionToAxis(crossAxisDirection), 'The "axisDirection" and the "crossAxisDirection" are along the same axis.');
443 444 445 446 447
      verifyDouble(viewportMainAxisExtent, 'viewportMainAxisExtent', mustBePositive: true);
      verifyDouble(remainingPaintExtent, 'remainingPaintExtent', mustBePositive: true);
      verifyDouble(remainingCacheExtent, 'remainingCacheExtent', mustBePositive: true);
      verifyDouble(cacheOrigin, 'cacheOrigin', mustBeNegative: true);
      verifyDouble(precedingScrollExtent, 'precedingScrollExtent', mustBePositive: true);
448
      verify(isNormalized, 'The constraints are not normalized.'); // should be redundant with earlier checks
449 450 451 452 453 454 455 456
      if (hasErrors) {
        throw FlutterError.fromParts(<DiagnosticsNode>[
          ErrorSummary('$runtimeType is not valid: $errorMessage'),
          if (informationCollector != null)
            ...informationCollector(),
          DiagnosticsProperty<SliverConstraints>('The offending constraints were', this, style: DiagnosticsTreeStyle.errorProperty),
        ]);
      }
457
      return true;
458
    }());
459 460 461 462
    return true;
  }

  @override
463
  bool operator ==(Object other) {
464 465 466 467
    if (identical(this, other))
      return true;
    if (other is! SliverConstraints)
      return false;
468 469
    assert(other.debugAssertIsValid());
    return other.axisDirection == axisDirection
470 471 472 473 474 475 476 477 478
        && other.growthDirection == growthDirection
        && other.scrollOffset == scrollOffset
        && other.overlap == overlap
        && other.remainingPaintExtent == remainingPaintExtent
        && other.crossAxisExtent == crossAxisExtent
        && other.crossAxisDirection == crossAxisDirection
        && other.viewportMainAxisExtent == viewportMainAxisExtent
        && other.remainingCacheExtent == remainingCacheExtent
        && other.cacheOrigin == cacheOrigin;
479 480 481 482
  }

  @override
  int get hashCode {
483 484 485 486 487 488 489 490 491
    return hashValues(
      axisDirection,
      growthDirection,
      scrollOffset,
      overlap,
      remainingPaintExtent,
      crossAxisExtent,
      crossAxisDirection,
      viewportMainAxisExtent,
492 493
      remainingCacheExtent,
      cacheOrigin,
494
    );
495 496 497 498
  }

  @override
  String toString() {
499 500 501 502 503 504 505 506 507 508 509 510 511 512
    final List<String> properties = <String>[
      '$axisDirection',
      '$growthDirection',
      '$userScrollDirection',
      'scrollOffset: ${scrollOffset.toStringAsFixed(1)}',
      'remainingPaintExtent: ${remainingPaintExtent.toStringAsFixed(1)}',
      if (overlap != 0.0) 'overlap: ${overlap.toStringAsFixed(1)}',
      'crossAxisExtent: ${crossAxisExtent.toStringAsFixed(1)}',
      'crossAxisDirection: $crossAxisDirection',
      'viewportMainAxisExtent: ${viewportMainAxisExtent.toStringAsFixed(1)}',
      'remainingCacheExtent: ${remainingCacheExtent.toStringAsFixed(1)}',
      'cacheOrigin: ${cacheOrigin.toStringAsFixed(1)}',
    ];
    return 'SliverConstraints(${properties.join(', ')})';
513 514 515
  }
}

516 517 518 519
/// Describes the amount of space occupied by a [RenderSliver].
///
/// A sliver can occupy space in several different ways, which is why this class
/// contains multiple values.
520
@immutable
521
class SliverGeometry with Diagnosticable {
522 523 524 525 526 527 528 529
  /// Creates an object that describes the amount of space occupied by a sliver.
  ///
  /// If the [layoutExtent] argument is null, [layoutExtent] defaults to the
  /// [paintExtent]. If the [hitTestExtent] argument is null, [hitTestExtent]
  /// defaults to the [paintExtent]. If [visible] is null, [visible] defaults to
  /// whether [paintExtent] is greater than zero.
  ///
  /// The other arguments must not be null.
530
  const SliverGeometry({
531 532 533
    this.scrollExtent = 0.0,
    this.paintExtent = 0.0,
    this.paintOrigin = 0.0,
534
    double? layoutExtent,
535 536
    this.maxPaintExtent = 0.0,
    this.maxScrollObstructionExtent = 0.0,
537 538
    double? hitTestExtent,
    bool? visible,
539
    this.hasVisualOverflow = false,
540
    this.scrollOffsetCorrection,
541
    double? cacheExtent,
542 543 544 545 546
  }) : assert(scrollExtent != null),
       assert(paintExtent != null),
       assert(paintOrigin != null),
       assert(maxPaintExtent != null),
       assert(hasVisualOverflow != null),
547
       assert(scrollOffsetCorrection != 0.0),
548
       layoutExtent = layoutExtent ?? paintExtent,
549
       hitTestExtent = hitTestExtent ?? paintExtent,
550
       cacheExtent = cacheExtent ?? layoutExtent ?? paintExtent,
551 552
       visible = visible ?? paintExtent > 0.0;

553
  /// A sliver that occupies no space at all.
554
  static const SliverGeometry zero = SliverGeometry();
555

556 557 558 559 560 561 562 563 564 565 566 567 568 569 570
  /// The (estimated) total scrollable extent that this sliver has content for.
  ///
  /// This is the amount of scrolling the user needs to do to get from the
  /// beginning of this sliver to the end of this sliver.
  ///
  /// The value is used to calculate the [SliverConstraints.scrollOffset] of
  /// all slivers in the scrollable and thus should be provided whether the
  /// sliver is currently in the viewport or not.
  ///
  /// In a typical scrolling scenario, the [scrollExtent] is constant for a
  /// sliver throughout the scrolling while [paintExtent] and [layoutExtent]
  /// will progress from `0` when offscreen to between `0` and [scrollExtent]
  /// as the sliver scrolls partially into and out of the screen and is
  /// equal to [scrollExtent] while the sliver is entirely on screen. However,
  /// these relationships can be customized to achieve more special effects.
571 572 573 574 575
  ///
  /// This value must be accurate if the [paintExtent] is less than the
  /// [SliverConstraints.remainingPaintExtent] provided during layout.
  final double scrollExtent;

576 577 578 579 580
  /// The visual location of the first visible part of this sliver relative to
  /// its layout position.
  ///
  /// For example, if the sliver wishes to paint visually before its layout
  /// position, the [paintOrigin] is negative. The coordinate system this sliver
581 582 583 584 585 586 587 588 589 590
  /// uses for painting is relative to this [paintOrigin]. In other words,
  /// when [RenderSliver.paint] is called, the (0, 0) position of the [Offset]
  /// given to it is at this [paintOrigin].
  ///
  /// The coordinate system used for the [paintOrigin] itself is relative
  /// to the start of this sliver's layout position rather than relative to
  /// its current position on the viewport. In other words, in a typical
  /// scrolling scenario, [paintOrigin] remains constant at 0.0 rather than
  /// tracking from 0.0 to [SliverConstraints.viewportMainAxisExtent] as the
  /// sliver scrolls past the viewport.
591 592 593 594 595 596 597 598 599 600 601
  ///
  /// This value does not affect the layout of subsequent slivers. The next
  /// sliver is still placed at [layoutExtent] after this sliver's layout
  /// position. This value does affect where the [paintExtent] extent is
  /// measured from when computing the [SliverConstraints.overlap] for the next
  /// sliver.
  ///
  /// Defaults to 0.0, which means slivers start painting at their layout
  /// position by default.
  final double paintOrigin;

602 603 604 605 606 607 608 609
  /// The amount of currently visible visual space that was taken by the sliver
  /// to render the subset of the sliver that covers all or part of the
  /// [SliverConstraints.remainingPaintExtent] in the current viewport.
  ///
  /// This value does not affect how the next sliver is positioned. In other
  /// words, if this value was 100 and [layoutExtent] was 0, typical slivers
  /// placed after it would end up drawing in the same 100 pixel space while
  /// painting.
610 611 612
  ///
  /// This must be between zero and [SliverConstraints.remainingPaintExtent].
  ///
613 614 615 616 617
  /// This value is typically 0 when outside of the viewport and grows or
  /// shrinks from 0 or to 0 as the sliver is being scrolled into and out of the
  /// viewport unless the sliver wants to achieve a special effect and paint
  /// even when scrolled away.
  ///
618 619 620 621 622 623 624 625 626
  /// This contributes to the calculation for the next sliver's
  /// [SliverConstraints.overlap].
  final double paintExtent;

  /// The distance from the first visible part of this sliver to the first
  /// visible part of the next sliver, assuming the next sliver's
  /// [SliverConstraints.scrollOffset] is zero.
  ///
  /// This must be between zero and [paintExtent]. It defaults to [paintExtent].
627 628 629
  ///
  /// This value is typically 0 when outside of the viewport and grows or
  /// shrinks from 0 or to 0 as the sliver is being scrolled into and out of the
630
  /// viewport unless the sliver wants to achieve a special effect and push
631 632
  /// down the layout start position of subsequent slivers before the sliver is
  /// even scrolled into the viewport.
633 634 635 636 637
  final double layoutExtent;

  /// The (estimated) total paint extent that this sliver would be able to
  /// provide if the [SliverConstraints.remainingPaintExtent] was infinite.
  ///
638
  /// This is used by viewports that implement shrink-wrapping.
639 640 641 642
  ///
  /// By definition, this cannot be less than [paintExtent].
  final double maxPaintExtent;

643 644 645 646 647 648 649 650 651 652
  /// The maximum extent by which this sliver can reduce the area in which
  /// content can scroll if the sliver were pinned at the edge.
  ///
  /// Slivers that never get pinned at the edge, should return zero.
  ///
  /// A pinned app bar is an example for a sliver that would use this setting:
  /// When the app bar is pinned to the top, the area in which content can
  /// actually scroll is reduced by the height of the app bar.
  final double maxScrollObstructionExtent;

653 654 655 656 657 658 659 660 661 662 663 664
  /// The distance from where this sliver started painting to the bottom of
  /// where it should accept hits.
  ///
  /// This must be between zero and [paintExtent]. It defaults to [paintExtent].
  final double hitTestExtent;

  /// Whether this sliver should be painted.
  ///
  /// By default, this is true if [paintExtent] is greater than zero, and
  /// false if [paintExtent] is zero.
  final bool visible;

665 666 667 668 669 670 671
  /// Whether this sliver has visual overflow.
  ///
  /// By default, this is false, which means the viewport does not need to clip
  /// its children. If any slivers have visual overflow, the viewport will apply
  /// a clip to its children.
  final bool hasVisualOverflow;

672 673 674
  /// If this is non-zero after [RenderSliver.performLayout] returns, the scroll
  /// offset will be adjusted by the parent and then the entire layout of the
  /// parent will be rerun.
675
  ///
676 677 678 679
  /// When the value is non-zero, the [RenderSliver] does not need to compute
  /// the rest of the values when constructing the [SliverGeometry] or call
  /// [RenderObject.layout] on its children since [RenderSliver.performLayout]
  /// will be called again on this sliver in the same frame after the
680
  /// [SliverConstraints.scrollOffset] correction has been applied, when the
681 682
  /// proper [SliverGeometry] and layout of its children can be computed.
  ///
683 684 685
  /// If the parent is also a [RenderSliver], it must propagate this value
  /// in its own [RenderSliver.geometry] property until a viewport which adjusts
  /// its offset based on this value.
686
  final double? scrollOffsetCorrection;
687

688 689 690 691
  /// How many pixels the sliver has consumed in the
  /// [SliverConstraints.remainingCacheExtent].
  ///
  /// This value should be equal to or larger than the [layoutExtent] because
692
  /// the sliver always consumes at least the [layoutExtent] from the
693 694 695 696
  /// [SliverConstraints.remainingCacheExtent] and possibly more if it falls
  /// into the cache area of the viewport.
  ///
  /// See also:
697
  ///
698 699 700
  ///  * [RenderViewport.cacheExtent] for a description of a viewport's cache area.
  final double cacheExtent;

701 702 703
  /// Asserts that this geometry is internally consistent.
  ///
  /// Does nothing if asserts are disabled. Always returns true.
704
  bool debugAssertIsValid({
705
    InformationCollector? informationCollector,
706
  }) {
707
    assert(() {
708
      void verify(bool check, String summary, {List<DiagnosticsNode>? details}) {
709 710
        if (check)
          return;
711
        throw FlutterError.fromParts(<DiagnosticsNode>[
712
          ErrorSummary('${objectRuntimeType(this, 'SliverGeometry')} is not valid: $summary'),
713 714 715 716
          ...?details,
          if (informationCollector != null)
            ...informationCollector(),
        ]);
717
      }
718

719 720 721 722 723 724 725
      verify(scrollExtent != null, 'The "scrollExtent" is null.');
      verify(scrollExtent >= 0.0, 'The "scrollExtent" is negative.');
      verify(paintExtent != null, 'The "paintExtent" is null.');
      verify(paintExtent >= 0.0, 'The "paintExtent" is negative.');
      verify(paintOrigin != null, 'The "paintOrigin" is null.');
      verify(layoutExtent != null, 'The "layoutExtent" is null.');
      verify(layoutExtent >= 0.0, 'The "layoutExtent" is negative.');
726
      verify(cacheExtent >= 0.0, 'The "cacheExtent" is negative.');
727
      if (layoutExtent > paintExtent) {
728
        verify(false,
729 730
          'The "layoutExtent" exceeds the "paintExtent".',
          details: _debugCompareFloats('paintExtent', paintExtent, 'layoutExtent', layoutExtent),
731 732
        );
      }
733
      verify(maxPaintExtent != null, 'The "maxPaintExtent" is null.');
734
      // If the paintExtent is slightly more than the maxPaintExtent, but the difference is still less
735 736
      // than precisionErrorTolerance, we will not throw the assert below.
      if (paintExtent - maxPaintExtent > precisionErrorTolerance) {
737
        verify(false,
738 739 740
          'The "maxPaintExtent" is less than the "paintExtent".',
          details:
            _debugCompareFloats('maxPaintExtent', maxPaintExtent, 'paintExtent', paintExtent)
741
              ..add(ErrorDescription("By definition, a sliver can't paint more than the maximum that it can paint!")),
742 743
        );
      }
744 745 746 747
      verify(hitTestExtent != null, 'The "hitTestExtent" is null.');
      verify(hitTestExtent >= 0.0, 'The "hitTestExtent" is negative.');
      verify(visible != null, 'The "visible" property is null.');
      verify(hasVisualOverflow != null, 'The "hasVisualOverflow" is null.');
748
      verify(scrollOffsetCorrection != 0.0, 'The "scrollOffsetCorrection" is zero.');
749
      return true;
750
    }());
751 752 753 754
    return true;
  }

  @override
755
  String toStringShort() => objectRuntimeType(this, 'SliverGeometry');
756 757

  @override
758 759
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
760
    properties.add(DoubleProperty('scrollExtent', scrollExtent));
761
    if (paintExtent > 0.0) {
762
      properties.add(DoubleProperty('paintExtent', paintExtent, unit : visible ? null : ' but not painting'));
763 764
    } else if (paintExtent == 0.0) {
      if (visible) {
765
        properties.add(DoubleProperty('paintExtent', paintExtent, unit: visible ? null : ' but visible'));
766
      }
767
      properties.add(FlagProperty('visible', value: visible, ifFalse: 'hidden'));
768 769
    } else {
      // Negative paintExtent!
770
      properties.add(DoubleProperty('paintExtent', paintExtent, tooltip: '!'));
771
    }
772 773 774 775 776 777 778
    properties.add(DoubleProperty('paintOrigin', paintOrigin, defaultValue: 0.0));
    properties.add(DoubleProperty('layoutExtent', layoutExtent, defaultValue: paintExtent));
    properties.add(DoubleProperty('maxPaintExtent', maxPaintExtent));
    properties.add(DoubleProperty('hitTestExtent', hitTestExtent, defaultValue: paintExtent));
    properties.add(DiagnosticsProperty<bool>('hasVisualOverflow', hasVisualOverflow, defaultValue: false));
    properties.add(DoubleProperty('scrollOffsetCorrection', scrollOffsetCorrection, defaultValue: null));
    properties.add(DoubleProperty('cacheExtent', cacheExtent, defaultValue: 0.0));
779 780 781
  }
}

782
/// Method signature for hit testing a [RenderSliver].
783 784 785 786 787 788 789 790
///
/// Used by [SliverHitTestResult.addWithAxisOffset] to hit test [RenderSliver]
/// children.
///
/// See also:
///
///  * [RenderSliver.hitTest], which documents more details around hit testing
///    [RenderSliver]s.
791
typedef SliverHitTest = bool Function(SliverHitTestResult result, { required double mainAxisPosition, required double crossAxisPosition });
792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841

/// The result of performing a hit test on [RenderSliver]s.
///
/// An instance of this class is provided to [RenderSliver.hitTest] to record
/// the result of the hit test.
class SliverHitTestResult extends HitTestResult {
  /// Creates an empty hit test result for hit testing on [RenderSliver].
  SliverHitTestResult() : super();

  /// Wraps `result` to create a [HitTestResult] that implements the
  /// [SliverHitTestResult] protocol for hit testing on [RenderSliver]s.
  ///
  /// This method is used by [RenderObject]s that adapt between the
  /// [RenderSliver]-world and the non-[RenderSliver]-world to convert a
  /// (subtype of) [HitTestResult] to a [SliverHitTestResult] for hit testing on
  /// [RenderSliver]s.
  ///
  /// The [HitTestEntry] instances added to the returned [SliverHitTestResult]
  /// are also added to the wrapped `result` (both share the same underlying
  /// data structure to store [HitTestEntry] instances).
  ///
  /// See also:
  ///
  ///  * [HitTestResult.wrap], which turns a [SliverHitTestResult] back into a
  ///    generic [HitTestResult].
  ///  * [BoxHitTestResult.wrap], which turns a [SliverHitTestResult] into a
  ///    [BoxHitTestResult] for hit testing on [RenderBox] children.
  SliverHitTestResult.wrap(HitTestResult result) : super.wrap(result);

  /// Transforms `mainAxisPosition` and `crossAxisPosition` to the local
  /// coordinate system of a child for hit-testing the child.
  ///
  /// The actual hit testing of the child needs to be implemented in the
  /// provided `hitTest` callback, which is invoked with the transformed
  /// `position` as argument.
  ///
  /// For the transform `mainAxisOffset` is subtracted from `mainAxisPosition`
  /// and `crossAxisOffset` is subtracted from `crossAxisPosition`.
  ///
  /// The `paintOffset` describes how the paint position of a point painted at
  /// the provided `mainAxisPosition` and `crossAxisPosition` would change after
  /// `mainAxisOffset` and `crossAxisOffset` have been applied. This
  /// `paintOffset` is used to properly convert [PointerEvent]s to the local
  /// coordinate system of the event receiver.
  ///
  /// The `paintOffset` may be null if `mainAxisOffset` and `crossAxisOffset` are
  /// both zero.
  ///
  /// The function returns the return value of `hitTest`.
  bool addWithAxisOffset({
842 843 844 845 846 847
    required Offset? paintOffset,
    required double mainAxisOffset,
    required double crossAxisOffset,
    required double mainAxisPosition,
    required double crossAxisPosition,
    required SliverHitTest hitTest,
848 849 850 851 852 853
  }) {
    assert(mainAxisOffset != null);
    assert(crossAxisOffset != null);
    assert(mainAxisPosition != null);
    assert(crossAxisPosition != null);
    assert(hitTest != null);
854
    if (paintOffset != null) {
855
      pushOffset(-paintOffset);
856 857
    }
    final bool isHit = hitTest(
858 859 860 861
      this,
      mainAxisPosition: mainAxisPosition - mainAxisOffset,
      crossAxisPosition: crossAxisPosition - crossAxisOffset,
    );
862 863 864 865
    if (paintOffset != null) {
      popTransform();
    }
    return isHit;
866 867 868
  }
}

869 870 871 872
/// A hit test entry used by [RenderSliver].
///
/// The coordinate system used by this hit test entry is relative to the
/// [AxisDirection] of the target sliver.
873
class SliverHitTestEntry extends HitTestEntry {
874 875 876
  /// Creates a sliver hit test entry.
  ///
  /// The [mainAxisPosition] and [crossAxisPosition] arguments must not be null.
877
  SliverHitTestEntry(
878
    RenderSliver target, {
879 880
    required this.mainAxisPosition,
    required this.crossAxisPosition,
881 882 883
  }) : assert(mainAxisPosition != null),
       assert(crossAxisPosition != null),
       super(target);
884 885

  @override
886
  RenderSliver get target => super.target as RenderSliver;
887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913

  /// The distance in the [AxisDirection] from the edge of the sliver's painted
  /// area (as given by the [SliverConstraints.scrollOffset]) to the hit point.
  /// This can be an unusual direction, for example in the [AxisDirection.up]
  /// case this is a distance from the _bottom_ of the sliver's painted area.
  final double mainAxisPosition;

  /// The distance to the hit point in the axis opposite the
  /// [SliverConstraints.axis].
  ///
  /// If the cross axis is horizontal (i.e. the
  /// [SliverConstraints.axisDirection] is either [AxisDirection.down] or
  /// [AxisDirection.up]), then the `crossAxisPosition` is a distance from the
  /// left edge of the sliver. If the cross axis is vertical (i.e. the
  /// [SliverConstraints.axisDirection] is either [AxisDirection.right] or
  /// [AxisDirection.left]), then the `crossAxisPosition` is a distance from the
  /// top edge of the sliver.
  ///
  /// This is always a distance from the left or top of the parent, never a
  /// distance from the right or bottom.
  final double crossAxisPosition;

  @override
  String toString() => '${target.runtimeType}@(mainAxis: $mainAxisPosition, crossAxis: $crossAxisPosition)';
}

/// Parent data structure used by parents of slivers that position their
914
/// children using layout offsets.
915
///
916
/// This data structure is optimized for fast layout. It is best used by parents
917 918 919
/// that expect to have many children whose relative positions don't change even
/// when the scroll offset does.
class SliverLogicalParentData extends ParentData {
920 921
  /// The position of the child relative to the zero scroll offset.
  ///
nt4f04uNd's avatar
nt4f04uNd committed
922
  /// The number of pixels from the zero scroll offset of the parent sliver
923
  /// (the line at which its [SliverConstraints.scrollOffset] is zero) to the
924 925
  /// side of the child closest to that offset. A [layoutOffset] can be null
  /// when it cannot be determined. The value will be set after layout.
926 927
  ///
  /// In a typical list, this does not change as the parent is scrolled.
928 929
  ///
  /// Defaults to null.
930
  double? layoutOffset;
931 932

  @override
933
  String toString() => 'layoutOffset=${layoutOffset == null ? 'None': layoutOffset!.toStringAsFixed(1)}';
934 935
}

936 937
/// Parent data for slivers that have multiple children and that position their
/// children using layout offsets.
938 939
class SliverLogicalContainerParentData extends SliverLogicalParentData with ContainerParentDataMixin<RenderSliver> { }

940
/// Parent data structure used by parents of slivers that position their
941 942 943
/// children using absolute coordinates.
///
/// For example, used by [RenderViewport].
944
///
945
/// This data structure is optimized for fast painting, at the cost of requiring
946 947 948 949 950 951 952 953 954 955
/// additional work during layout when the children change their offsets. It is
/// best used by parents that expect to have few children, especially if those
/// children will themselves be very tall relative to the parent.
class SliverPhysicalParentData extends ParentData {
  /// The position of the child relative to the parent.
  ///
  /// This is the distance from the top left visible corner of the parent to the
  /// top left visible corner of the sliver.
  Offset paintOffset = Offset.zero;

956 957 958 959
  /// Apply the [paintOffset] to the given [transform].
  ///
  /// Used to implement [RenderObject.applyPaintTransform] by slivers that use
  /// [SliverPhysicalParentData].
960
  void applyPaintTransform(Matrix4 transform) {
961
    // Hit test logic relies on this always providing an invertible matrix.
962 963 964 965 966 967 968
    transform.translate(paintOffset.dx, paintOffset.dy);
  }

  @override
  String toString() => 'paintOffset=$paintOffset';
}

969 970
/// Parent data for slivers that have multiple children and that position their
/// children using absolute coordinates.
971 972
class SliverPhysicalContainerParentData extends SliverPhysicalParentData with ContainerParentDataMixin<RenderSliver> { }

973
List<DiagnosticsNode> _debugCompareFloats(String labelA, double valueA, String labelB, double valueB) {
974 975 976 977
  return <DiagnosticsNode>[
    if (valueA.toStringAsFixed(1) != valueB.toStringAsFixed(1))
      ErrorDescription(
        'The $labelA is ${valueA.toStringAsFixed(1)}, but '
978
        'the $labelB is ${valueB.toStringAsFixed(1)}.',
979 980 981 982
      )
    else ...<DiagnosticsNode>[
      ErrorDescription('The $labelA is $valueA, but the $labelB is $valueB.'),
      ErrorHint(
983
        'Maybe you have fallen prey to floating point rounding errors, and should explicitly '
984
        'apply the min() or max() functions, or the clamp() method, to the $labelB?',
985 986 987
      ),
    ],
  ];
988 989
}

990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017
/// Base class for the render objects that implement scroll effects in viewports.
///
/// A [RenderViewport] has a list of child slivers. Each sliver — literally a
/// slice of the viewport's contents — is laid out in turn, covering the
/// viewport in the process. (Every sliver is laid out each time, including
/// those that have zero extent because they are "scrolled off" or are beyond
/// the end of the viewport.)
///
/// Slivers participate in the _sliver protocol_, wherein during [layout] each
/// sliver receives a [SliverConstraints] object and computes a corresponding
/// [SliverGeometry] that describes where it fits in the viewport. This is
/// analogous to the box protocol used by [RenderBox], which gets a
/// [BoxConstraints] as input and computes a [Size].
///
/// Slivers have a leading edge, which is where the position described by
/// [SliverConstraints.scrollOffset] for this sliver begins. Slivers have
/// several dimensions, the primary of which is [SliverGeometry.paintExtent],
/// which describes the extent of the sliver along the main axis, starting from
/// the leading edge, reaching either the end of the viewport or the end of the
/// sliver, whichever comes first.
///
/// Slivers can change dimensions based on the changing constraints in a
/// non-linear fashion, to achieve various scroll effects. For example, the
/// various [RenderSliverPersistentHeader] subclasses, on which [SliverAppBar]
/// is based, achieve effects such as staying visible despite the scroll offset,
/// or reappearing at different offsets based on the user's scroll direction
/// ([SliverConstraints.userScrollDirection]).
///
1018 1019
/// {@youtube 560 315 https://www.youtube.com/watch?v=Mz3kHQxBjGg}
///
1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126
/// ## Writing a RenderSliver subclass
///
/// Slivers can have sliver children, or children from another coordinate
/// system, typically box children. (For details on the box protocol, see
/// [RenderBox].) Slivers can also have different child models, typically having
/// either one child, or a list of children.
///
/// ### Examples of slivers
///
/// A good example of a sliver with a single child that is also itself a sliver
/// is [RenderSliverPadding], which indents its child. A sliver-to-sliver render
/// object such as this must construct a [SliverConstraints] object for its
/// child, then must take its child's [SliverGeometry] and use it to form its
/// own [geometry].
///
/// The other common kind of one-child sliver is a sliver that has a single
/// [RenderBox] child. An example of that would be [RenderSliverToBoxAdapter],
/// which lays out a single box and sizes itself around the box. Such a sliver
/// must use its [SliverConstraints] to create a [BoxConstraints] for the
/// child, lay the child out (using the child's [layout] method), and then use
/// the child's [RenderBox.size] to generate the sliver's [SliverGeometry].
///
/// The most common kind of sliver though is one with multiple children. The
/// most straight-forward example of this is [RenderSliverList], which arranges
/// its children one after the other in the main axis direction. As with the
/// one-box-child sliver case, it uses its [constraints] to create a
/// [BoxConstraints] for the children, and then it uses the aggregate
/// information from all its children to generate its [geometry]. Unlike the
/// one-child cases, however, it is judicious in which children it actually lays
/// out (and later paints). If the scroll offset is 1000 pixels, and it
/// previously determined that the first three children are each 400 pixels
/// tall, then it will skip the first two and start the layout with its third
/// child.
///
/// ### Layout
///
/// As they are laid out, slivers decide their [geometry], which includes their
/// size ([SliverGeometry.paintExtent]) and the position of the next sliver
/// ([SliverGeometry.layoutExtent]), as well as the position of each of their
/// children, based on the input [constraints] from the viewport such as the
/// scroll offset ([SliverConstraints.scrollOffset]).
///
/// For example, a sliver that just paints a box 100 pixels high would say its
/// [SliverGeometry.paintExtent] was 100 pixels when the scroll offset was zero,
/// but would say its [SliverGeometry.paintExtent] was 25 pixels when the scroll
/// offset was 75 pixels, and would say it was zero when the scroll offset was
/// 100 pixels or more. (This is assuming that
/// [SliverConstraints.remainingPaintExtent] was more than 100 pixels.)
///
/// The various dimensions that are provided as input to this system are in the
/// [constraints]. They are described in detail in the documentation for the
/// [SliverConstraints] class.
///
/// The [performLayout] function must take these [constraints] and create a
/// [SliverGeometry] object that it must then assign to the [geometry] property.
/// The different dimensions of the geometry that can be configured are
/// described in detail in the documentation for the [SliverGeometry] class.
///
/// ### Painting
///
/// In addition to implementing layout, a sliver must also implement painting.
/// This is achieved by overriding the [paint] method.
///
/// The [paint] method is called with an [Offset] from the [Canvas] origin to
/// the top-left corner of the sliver, _regardless of the axis direction_.
///
/// Subclasses should also override [applyPaintTransform] to provide the
/// [Matrix4] describing the position of each child relative to the sliver.
/// (This is used by, among other things, the accessibility layer, to determine
/// the bounds of the child.)
///
/// ### Hit testing
///
/// To implement hit testing, either override the [hitTestSelf] and
/// [hitTestChildren] methods, or, for more complex cases, instead override the
/// [hitTest] method directly.
///
/// To actually react to pointer events, the [handleEvent] method may be
/// implemented. By default it does nothing. (Typically gestures are handled by
/// widgets in the box protocol, not by slivers directly.)
///
/// ### Helper methods
///
/// There are a number of methods that a sliver should implement which will make
/// the other methods easier to implement. Each method listed below has detailed
/// documentation. In addition, the [RenderSliverHelpers] class can be used to
/// mix in some helpful methods.
///
/// #### childScrollOffset
///
/// If the subclass positions children anywhere other than at scroll offset
/// zero, it should override [childScrollOffset]. For example,
/// [RenderSliverList] and [RenderSliverGrid] override this method, but
/// [RenderSliverToBoxAdapter] does not.
///
/// This is used by, among other things, [Scrollable.ensureVisible].
///
/// #### childMainAxisPosition
///
/// Subclasses should implement [childMainAxisPosition] to describe where their
/// children are positioned.
///
/// #### childCrossAxisPosition
///
/// If the subclass positions children in the cross-axis at a position other
/// than zero, then it should override [childCrossAxisPosition]. For example
/// [RenderSliverGrid] overrides this method.
1127 1128 1129
abstract class RenderSliver extends RenderObject {
  // layout input
  @override
1130
  SliverConstraints get constraints => super.constraints as SliverConstraints;
1131

1132 1133 1134 1135 1136 1137 1138 1139
  /// The amount of space this sliver occupies.
  ///
  /// This value is stale whenever this object is marked as needing layout.
  /// During [performLayout], do not read the [geometry] of a child unless you
  /// pass true for parentUsesSize when calling the child's [layout] function.
  ///
  /// The geometry of a sliver should be set only during the sliver's
  /// [performLayout] or [performResize] functions. If you wish to change the
1140
  /// geometry of a sliver outside of those functions, call [markNeedsLayout]
1141
  /// instead to schedule a layout of the sliver.
1142 1143 1144
  SliverGeometry? get geometry => _geometry;
  SliverGeometry? _geometry;
  set geometry(SliverGeometry? value) {
1145 1146 1147 1148 1149 1150 1151
    assert(!(debugDoingThisResize && debugDoingThisLayout));
    assert(sizedByParent || !debugDoingThisResize);
    assert(() {
      if ((sizedByParent && debugDoingThisResize) ||
          (!sizedByParent && debugDoingThisLayout))
        return true;
      assert(!debugDoingThisResize);
1152
      DiagnosticsNode? contract, violation, hint;
1153 1154
      if (debugDoingThisLayout) {
        assert(sizedByParent);
1155
        violation = ErrorDescription('It appears that the geometry setter was called from performLayout().');
1156
      } else {
1157
        violation = ErrorDescription('The geometry setter was called from outside layout (neither performResize() nor performLayout() were being run for this object).');
1158
        if (owner != null && owner!.debugDoingLayout)
1159
          hint = ErrorDescription('Only the object itself can set its geometry. It is a contract violation for other objects to set it.');
1160 1161
      }
      if (sizedByParent)
1162
        contract = ErrorDescription('Because this RenderSliver has sizedByParent set to true, it must set its geometry in performResize().');
1163
      else
1164 1165 1166 1167
        contract = ErrorDescription('Because this RenderSliver has sizedByParent set to false, it must set its geometry in performLayout().');

      final List<DiagnosticsNode> information = <DiagnosticsNode>[
        ErrorSummary('RenderSliver geometry setter called incorrectly.'),
1168 1169 1170 1171
        violation,
        if (hint != null) hint,
        contract,
        describeForError('The RenderSliver in question is'),
1172 1173
      ];
      throw FlutterError.fromParts(information);
1174
    }());
1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185
    _geometry = value;
  }

  @override
  Rect get semanticBounds => paintBounds;

  @override
  Rect get paintBounds {
    assert(constraints.axis != null);
    switch (constraints.axis) {
      case Axis.horizontal:
1186
        return Rect.fromLTWH(
1187
          0.0, 0.0,
1188
          geometry!.paintExtent,
1189 1190 1191
          constraints.crossAxisExtent,
        );
      case Axis.vertical:
1192
        return Rect.fromLTWH(
1193
          0.0, 0.0,
1194
          constraints.crossAxisExtent,
1195
          geometry!.paintExtent,
1196 1197 1198 1199 1200 1201 1202 1203 1204
        );
    }
  }

  @override
  void debugResetSize() { }

  @override
  void debugAssertDoesMeetConstraints() {
1205
    assert(geometry!.debugAssertIsValid(
1206 1207
      informationCollector: () sync* {
        yield describeForError('The RenderSliver that returned the offending geometry was');
1208
      },
1209
    ));
1210
    assert(() {
1211
      if (geometry!.paintOrigin + geometry!.paintExtent > constraints.remainingPaintExtent) {
1212 1213
        throw FlutterError.fromParts(<DiagnosticsNode>[
          ErrorSummary('SliverGeometry has a paintOffset that exceeds the remainingPaintExtent from the constraints.'),
1214 1215
          describeForError('The render object whose geometry violates the constraints is the following'),
          ..._debugCompareFloats(
1216
            'remainingPaintExtent', constraints.remainingPaintExtent,
1217
            'paintOrigin + paintExtent', geometry!.paintOrigin + geometry!.paintExtent,
1218 1219
          ),
          ErrorDescription(
1220 1221
            'The paintOrigin and paintExtent must cause the child sliver to paint '
            'within the viewport, and so cannot exceed the remainingPaintExtent.',
1222 1223
          ),
        ]);
1224 1225
      }
      return true;
1226
    }());
1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237
  }

  @override
  void performResize() {
    assert(false);
  }

  /// For a center sliver, the distance before the absolute zero scroll offset
  /// that this sliver can cover.
  ///
  /// For example, if an [AxisDirection.down] viewport with an
Adam Barth's avatar
Adam Barth committed
1238
  /// [RenderViewport.anchor] of 0.5 has a single sliver with a height of 100.0
1239 1240 1241 1242
  /// and its [centerOffsetAdjustment] returns 50.0, then the sliver will be
  /// centered in the viewport when the scroll offset is 0.0.
  ///
  /// The distance here is in the opposite direction of the
Adam Barth's avatar
Adam Barth committed
1243
  /// [RenderViewport.axisDirection], so values will typically be positive.
1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264
  double get centerOffsetAdjustment => 0.0;

  /// Determines the set of render objects located at the given position.
  ///
  /// Returns true if the given point is contained in this render object or one
  /// of its descendants. Adds any render objects that contain the point to the
  /// given hit test result.
  ///
  /// The caller is responsible for providing the position in the local
  /// coordinate space of the callee. The callee is responsible for checking
  /// whether the given position is within its bounds.
  ///
  /// Hit testing requires layout to be up-to-date but does not require painting
  /// to be up-to-date. That means a render object can rely upon [performLayout]
  /// having been called in [hitTest] but cannot rely upon [paint] having been
  /// called. For example, a render object might be a child of a [RenderOpacity]
  /// object, which calls [hitTest] on its children when its opacity is zero
  /// even through it does not [paint] its children.
  ///
  /// ## Coordinates for RenderSliver objects
  ///
1265 1266 1267 1268 1269
  /// The `mainAxisPosition` is the distance in the [AxisDirection] (after
  /// applying the [GrowthDirection]) from the edge of the sliver's painted
  /// area. This can be an unusual direction, for example in the
  /// [AxisDirection.up] case this is a distance from the _bottom_ of the
  /// sliver's painted area.
1270 1271 1272 1273 1274 1275 1276 1277
  ///
  /// The `crossAxisPosition` is the distance in the other axis. If the cross
  /// axis is horizontal (i.e. the [SliverConstraints.axisDirection] is either
  /// [AxisDirection.down] or [AxisDirection.up]), then the `crossAxisPosition`
  /// is a distance from the left edge of the sliver. If the cross axis is
  /// vertical (i.e. the [SliverConstraints.axisDirection] is either
  /// [AxisDirection.right] or [AxisDirection.left]), then the
  /// `crossAxisPosition` is a distance from the top edge of the sliver.
1278 1279 1280 1281 1282 1283
  ///
  /// ## Implementing hit testing for slivers
  ///
  /// The most straight-forward way to implement hit testing for a new sliver
  /// render object is to override its [hitTestSelf] and [hitTestChildren]
  /// methods.
1284 1285
  bool hitTest(SliverHitTestResult result, { required double mainAxisPosition, required double crossAxisPosition }) {
    if (mainAxisPosition >= 0.0 && mainAxisPosition < geometry!.hitTestExtent &&
1286 1287 1288
        crossAxisPosition >= 0.0 && crossAxisPosition < constraints.crossAxisExtent) {
      if (hitTestChildren(result, mainAxisPosition: mainAxisPosition, crossAxisPosition: crossAxisPosition) ||
          hitTestSelf(mainAxisPosition: mainAxisPosition, crossAxisPosition: crossAxisPosition)) {
1289
        result.add(SliverHitTestEntry(
1290 1291
          this,
          mainAxisPosition: mainAxisPosition,
1292
          crossAxisPosition: crossAxisPosition,
1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307
        ));
        return true;
      }
    }
    return false;
  }

  /// Override this method if this render object can be hit even if its
  /// children were not hit.
  ///
  /// Used by [hitTest]. If you override [hitTest] and do not call this
  /// function, then you don't need to implement this function.
  ///
  /// For a discussion of the semantics of the arguments, see [hitTest].
  @protected
1308
  bool hitTestSelf({ required double mainAxisPosition, required double crossAxisPosition }) => false;
1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321

  /// Override this method to check whether any children are located at the
  /// given position.
  ///
  /// Typically children should be hit-tested in reverse paint order so that
  /// hit tests at locations where children overlap hit the child that is
  /// visually "on top" (i.e., paints later).
  ///
  /// Used by [hitTest]. If you override [hitTest] and do not call this
  /// function, then you don't need to implement this function.
  ///
  /// For a discussion of the semantics of the arguments, see [hitTest].
  @protected
1322
  bool hitTestChildren(SliverHitTestResult result, { required double mainAxisPosition, required double crossAxisPosition }) => false;
1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338

  /// Computes the portion of the region from `from` to `to` that is visible,
  /// assuming that only the region from the [SliverConstraints.scrollOffset]
  /// that is [SliverConstraints.remainingPaintExtent] high is visible, and that
  /// the relationship between scroll offsets and paint offsets is linear.
  ///
  /// For example, if the constraints have a scroll offset of 100 and a
  /// remaining paint extent of 100, and the arguments to this method describe
  /// the region 50..150, then the returned value would be 50 (from scroll
  /// offset 100 to scroll offset 150).
  ///
  /// This method is not useful if there is not a 1:1 relationship between
  /// consumed scroll offset and consumed paint extent. For example, if the
  /// sliver always paints the same amount but consumes a scroll offset extent
  /// that is proportional to the [SliverConstraints.scrollOffset], then this
  /// function's results will not be consistent.
1339 1340
  // This could be a static method but isn't, because it would be less convenient
  // to call it from subclasses if it was.
1341
  double calculatePaintOffset(SliverConstraints constraints, { required double from, required double to }) {
1342 1343 1344 1345
    assert(from <= to);
    final double a = constraints.scrollOffset;
    final double b = constraints.scrollOffset + constraints.remainingPaintExtent;
    // the clamp on the next line is to avoid floating point rounding errors
1346
    return (to.clamp(a, b) - from.clamp(a, b)).clamp(0.0, constraints.remainingPaintExtent);
1347 1348
  }

1349 1350 1351 1352 1353 1354 1355 1356
  /// Computes the portion of the region from `from` to `to` that is within
  /// the cache extent of the viewport, assuming that only the region from the
  /// [SliverConstraints.cacheOrigin] that is
  /// [SliverConstraints.remainingCacheExtent] high is visible, and that
  /// the relationship between scroll offsets and paint offsets is linear.
  ///
  /// This method is not useful if there is not a 1:1 relationship between
  /// consumed scroll offset and consumed cache extent.
1357
  double calculateCacheOffset(SliverConstraints constraints, { required double from, required double to }) {
1358 1359 1360 1361
    assert(from <= to);
    final double a = constraints.scrollOffset + constraints.cacheOrigin;
    final double b = constraints.scrollOffset + constraints.remainingCacheExtent;
    // the clamp on the next line is to avoid floating point rounding errors
1362
    return (to.clamp(a, b) - from.clamp(a, b)).clamp(0.0, constraints.remainingCacheExtent);
1363 1364
  }

1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375
  /// Returns the distance from the leading _visible_ edge of the sliver to the
  /// side of the given child closest to that edge.
  ///
  /// For example, if the [constraints] describe this sliver as having an axis
  /// direction of [AxisDirection.down], then this is the distance from the top
  /// of the visible portion of the sliver to the top of the child. On the other
  /// hand, if the [constraints] describe this sliver as having an axis
  /// direction of [AxisDirection.up], then this is the distance from the bottom
  /// of the visible portion of the sliver to the bottom of the child. In both
  /// cases, this is the direction of increasing
  /// [SliverConstraints.scrollOffset] and
1376
  /// [SliverLogicalParentData.layoutOffset].
1377 1378 1379 1380 1381 1382 1383 1384
  ///
  /// For children that are [RenderSliver]s, the leading edge of the _child_
  /// will be the leading _visible_ edge of the child, not the part of the child
  /// that would locally be a scroll offset 0.0. For children that are not
  /// [RenderSliver]s, for example a [RenderBox] child, it's the actual distance
  /// to the edge of the box, since those boxes do not know how to handle being
  /// scrolled.
  ///
1385 1386
  /// This method differs from [childScrollOffset] in that
  /// [childMainAxisPosition] gives the distance from the leading _visible_ edge
1387 1388 1389 1390
  /// of the sliver whereas [childScrollOffset] gives the distance from the
  /// sliver's zero scroll offset.
  ///
  /// Calling this for a child that is not visible is not valid.
1391
  @protected
1392
  double childMainAxisPosition(covariant RenderObject child) {
1393
    assert(() {
1394
      throw FlutterError('${objectRuntimeType(this, 'RenderSliver')} does not implement childPosition.');
1395
    }());
1396 1397 1398
    return 0.0;
  }

1399
  /// Returns the distance along the cross axis from the zero of the cross axis
1400 1401
  /// in this sliver's [paint] coordinate space to the nearest side of the given
  /// child.
1402 1403 1404 1405 1406
  ///
  /// For example, if the [constraints] describe this sliver as having an axis
  /// direction of [AxisDirection.down], then this is the distance from the left
  /// of the sliver to the left of the child. Similarly, if the [constraints]
  /// describe this sliver as having an axis direction of [AxisDirection.up],
1407 1408 1409
  /// then this is value is the same. If the axis direction is
  /// [AxisDirection.left] or [AxisDirection.right], then it is the distance
  /// from the top of the sliver to the top of the child.
1410 1411
  ///
  /// Calling this for a child that is not visible is not valid.
1412
  @protected
1413
  double childCrossAxisPosition(covariant RenderObject child) => 0.0;
1414

1415 1416 1417 1418 1419 1420 1421 1422
  /// Returns the scroll offset for the leading edge of the given child.
  ///
  /// The `child` must be a child of this sliver.
  ///
  /// This method differs from [childMainAxisPosition] in that
  /// [childMainAxisPosition] gives the distance from the leading _visible_ edge
  /// of the sliver whereas [childScrollOffset] gives the distance from sliver's
  /// zero scroll offset.
1423
  double? childScrollOffset(covariant RenderObject child) {
1424 1425 1426 1427
    assert(child.parent == this);
    return 0.0;
  }

1428 1429 1430
  @override
  void applyPaintTransform(RenderObject child, Matrix4 transform) {
    assert(() {
1431
      throw FlutterError('${objectRuntimeType(this, 'RenderSliver')} does not implement applyPaintTransform.');
1432
    }());
1433 1434
  }

Ian Hickson's avatar
Ian Hickson committed
1435 1436 1437
  /// This returns a [Size] with dimensions relative to the leading edge of the
  /// sliver, specifically the same offset that is given to the [paint] method.
  /// This means that the dimensions may be negative.
1438 1439
  ///
  /// This is only valid after [layout] has completed.
1440 1441 1442 1443
  ///
  /// See also:
  ///
  ///  * [getAbsoluteSize], which returns absolute size.
Ian Hickson's avatar
Ian Hickson committed
1444 1445 1446
  @protected
  Size getAbsoluteSizeRelativeToOrigin() {
    assert(geometry != null);
1447
    assert(!debugNeedsLayout);
Ian Hickson's avatar
Ian Hickson committed
1448 1449
    switch (applyGrowthDirectionToAxisDirection(constraints.axisDirection, constraints.growthDirection)) {
      case AxisDirection.up:
1450
        return Size(constraints.crossAxisExtent, -geometry!.paintExtent);
Ian Hickson's avatar
Ian Hickson committed
1451
      case AxisDirection.right:
1452
        return Size(geometry!.paintExtent, constraints.crossAxisExtent);
Ian Hickson's avatar
Ian Hickson committed
1453
      case AxisDirection.down:
1454
        return Size(constraints.crossAxisExtent, geometry!.paintExtent);
Ian Hickson's avatar
Ian Hickson committed
1455
      case AxisDirection.left:
1456
        return Size(-geometry!.paintExtent, constraints.crossAxisExtent);
Ian Hickson's avatar
Ian Hickson committed
1457 1458 1459
    }
  }

1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475
  /// This returns the absolute [Size] of the sliver.
  ///
  /// The dimensions are always positive and calling this is only valid after
  /// [layout] has completed.
  ///
  /// See also:
  ///
  ///  * [getAbsoluteSizeRelativeToOrigin], which returns the size relative to
  ///    the leading edge of the sliver.
  @protected
  Size getAbsoluteSize() {
    assert(geometry != null);
    assert(!debugNeedsLayout);
    switch (constraints.axisDirection) {
      case AxisDirection.up:
      case AxisDirection.down:
1476
        return Size(constraints.crossAxisExtent, geometry!.paintExtent);
1477 1478
      case AxisDirection.right:
      case AxisDirection.left:
1479
        return Size(geometry!.paintExtent, constraints.crossAxisExtent);
1480 1481 1482
    }
  }

1483
  void _debugDrawArrow(Canvas canvas, Paint paint, Offset p0, Offset p1, GrowthDirection direction) {
1484 1485
    assert(() {
      if (p0 == p1)
Ian Hickson's avatar
Ian Hickson committed
1486
        return true;
1487
      assert(p0.dx == p1.dx || p0.dy == p1.dy); // must be axis-aligned
1488
      final double d = (p1 - p0).distance * 0.2;
1489
      final Offset temp;
1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501
      double dx1, dx2, dy1, dy2;
      switch (direction) {
        case GrowthDirection.forward:
          dx1 = dx2 = dy1 = dy2 = d;
          break;
        case GrowthDirection.reverse:
          temp = p0;
          p0 = p1;
          p1 = temp;
          dx1 = dx2 = dy1 = dy2 = -d;
          break;
      }
1502
      if (p0.dx == p1.dx) {
1503 1504 1505 1506 1507
        dx2 = -dx2;
      } else {
        dy2 = -dy2;
      }
      canvas.drawPath(
1508
        Path()
1509 1510 1511 1512 1513
          ..moveTo(p0.dx, p0.dy)
          ..lineTo(p1.dx, p1.dy)
          ..moveTo(p1.dx - dx1, p1.dy - dy1)
          ..lineTo(p1.dx, p1.dy)
          ..lineTo(p1.dx - dx2, p1.dy - dy2),
1514
        paint,
1515
      );
Ian Hickson's avatar
Ian Hickson committed
1516
      return true;
1517
    }());
1518 1519 1520 1521 1522 1523
  }

  @override
  void debugPaint(PaintingContext context, Offset offset) {
    assert(() {
      if (debugPaintSizeEnabled) {
1524
        final double strokeWidth = math.min(4.0, geometry!.paintExtent / 30.0);
1525
        final Paint paint = Paint()
1526
          ..color = const Color(0xFF33CC33)
1527 1528
          ..strokeWidth = strokeWidth
          ..style = PaintingStyle.stroke
1529
          ..maskFilter = MaskFilter.blur(BlurStyle.solid, strokeWidth);
1530
        final double arrowExtent = geometry!.paintExtent;
1531 1532 1533
        final double padding = math.max(2.0, strokeWidth);
        final Canvas canvas = context.canvas;
        canvas.drawCircle(
1534
          offset.translate(padding, padding),
1535 1536 1537 1538 1539 1540
          padding * 0.5,
          paint,
        );
        switch (constraints.axis) {
          case Axis.vertical:
            canvas.drawLine(
1541 1542
              offset,
              offset.translate(constraints.crossAxisExtent, 0.0),
1543 1544 1545 1546 1547
              paint,
            );
            _debugDrawArrow(
              canvas,
              paint,
1548 1549
              offset.translate(constraints.crossAxisExtent * 1.0 / 4.0, padding),
              offset.translate(constraints.crossAxisExtent * 1.0 / 4.0, arrowExtent - padding),
1550 1551 1552 1553 1554
              constraints.normalizedGrowthDirection,
            );
            _debugDrawArrow(
              canvas,
              paint,
1555 1556
              offset.translate(constraints.crossAxisExtent * 3.0 / 4.0, padding),
              offset.translate(constraints.crossAxisExtent * 3.0 / 4.0, arrowExtent - padding),
1557 1558 1559 1560 1561
              constraints.normalizedGrowthDirection,
            );
            break;
          case Axis.horizontal:
            canvas.drawLine(
1562 1563
              offset,
              offset.translate(0.0, constraints.crossAxisExtent),
1564 1565 1566 1567 1568
              paint,
            );
            _debugDrawArrow(
              canvas,
              paint,
1569 1570
              offset.translate(padding, constraints.crossAxisExtent * 1.0 / 4.0),
              offset.translate(arrowExtent - padding, constraints.crossAxisExtent * 1.0 / 4.0),
1571 1572 1573 1574 1575
              constraints.normalizedGrowthDirection,
            );
            _debugDrawArrow(
              canvas,
              paint,
1576 1577
              offset.translate(padding, constraints.crossAxisExtent * 3.0 / 4.0),
              offset.translate(arrowExtent - padding, constraints.crossAxisExtent * 3.0 / 4.0),
1578 1579 1580 1581 1582 1583
              constraints.normalizedGrowthDirection,
            );
            break;
        }
      }
      return true;
1584
    }());
1585 1586
  }

1587
  // This override exists only to change the type of the second argument.
1588 1589 1590 1591
  @override
  void handleEvent(PointerEvent event, SliverHitTestEntry entry) { }

  @override
1592 1593
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
1594
    properties.add(DiagnosticsProperty<SliverGeometry>('geometry', geometry));
1595 1596 1597 1598
  }
}

/// Mixin for [RenderSliver] subclasses that provides some utility functions.
1599
mixin RenderSliverHelpers implements RenderSliver {
1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629
  bool _getRightWayUp(SliverConstraints constraints) {
    assert(constraints != null);
    assert(constraints.axisDirection != null);
    bool rightWayUp;
    switch (constraints.axisDirection) {
      case AxisDirection.up:
      case AxisDirection.left:
        rightWayUp = false;
        break;
      case AxisDirection.down:
      case AxisDirection.right:
        rightWayUp = true;
        break;
    }
    assert(constraints.growthDirection != null);
    switch (constraints.growthDirection) {
      case GrowthDirection.forward:
        break;
      case GrowthDirection.reverse:
        rightWayUp = !rightWayUp;
        break;
    }
    assert(rightWayUp != null);
    return rightWayUp;
  }

  /// Utility function for [hitTestChildren] for use when the children are
  /// [RenderBox] widgets.
  ///
  /// This function takes care of converting the position from the sliver
1630
  /// coordinate system to the Cartesian coordinate system used by [RenderBox].
1631
  ///
1632
  /// This function relies on [childMainAxisPosition] to determine the position of
1633 1634 1635 1636
  /// child in question.
  ///
  /// Calling this for a child that is not visible is not valid.
  @protected
1637
  bool hitTestBoxChild(BoxHitTestResult result, RenderBox child, { required double mainAxisPosition, required double crossAxisPosition }) {
1638
    final bool rightWayUp = _getRightWayUp(constraints);
1639 1640 1641 1642 1643
    double delta = childMainAxisPosition(child);
    final double crossAxisDelta = childCrossAxisPosition(child);
    double absolutePosition = mainAxisPosition - delta;
    final double absoluteCrossAxisPosition = crossAxisPosition - crossAxisDelta;
    Offset paintOffset, transformedPosition;
1644 1645 1646
    assert(constraints.axis != null);
    switch (constraints.axis) {
      case Axis.horizontal:
1647
        if (!rightWayUp) {
1648
          absolutePosition = child.size.width - absolutePosition;
1649
          delta = geometry!.paintExtent - child.size.width - delta;
1650 1651 1652 1653
        }
        paintOffset = Offset(delta, crossAxisDelta);
        transformedPosition = Offset(absolutePosition, absoluteCrossAxisPosition);
        break;
1654
      case Axis.vertical:
1655
        if (!rightWayUp) {
1656
          absolutePosition = child.size.height - absolutePosition;
1657
          delta = geometry!.paintExtent - child.size.height - delta;
1658 1659 1660 1661
        }
        paintOffset = Offset(crossAxisDelta, delta);
        transformedPosition = Offset(absoluteCrossAxisPosition, absolutePosition);
        break;
1662
    }
1663 1664
    assert(paintOffset != null);
    assert(transformedPosition != null);
1665 1666 1667
    return result.addWithOutOfBandPosition(
      paintOffset: paintOffset,
      hitTest: (BoxHitTestResult result) {
1668 1669 1670
        return child.hitTest(result, position: transformedPosition);
      },
    );
1671 1672 1673 1674 1675
  }

  /// Utility function for [applyPaintTransform] for use when the children are
  /// [RenderBox] widgets.
  ///
1676 1677 1678
  /// This function turns the value returned by [childMainAxisPosition] and
  /// [childCrossAxisPosition]for the child in question into a translation that
  /// it then applies to the given matrix.
1679 1680 1681 1682
  ///
  /// Calling this for a child that is not visible is not valid.
  @protected
  void applyPaintTransformForBoxChild(RenderBox child, Matrix4 transform) {
1683
    final bool rightWayUp = _getRightWayUp(constraints);
1684 1685
    double delta = childMainAxisPosition(child);
    final double crossAxisDelta = childCrossAxisPosition(child);
1686 1687 1688
    assert(constraints.axis != null);
    switch (constraints.axis) {
      case Axis.horizontal:
1689
        if (!rightWayUp)
1690
          delta = geometry!.paintExtent - child.size.width - delta;
1691
        transform.translate(delta, crossAxisDelta);
1692 1693
        break;
      case Axis.vertical:
1694
        if (!rightWayUp)
1695
          delta = geometry!.paintExtent - child.size.height - delta;
1696
        transform.translate(crossAxisDelta, delta);
1697 1698 1699 1700 1701 1702 1703 1704
        break;
    }
  }
}

// ADAPTER FOR RENDER BOXES INSIDE SLIVERS
// Transitions from the RenderSliver world to the RenderBox world.

1705
/// An abstract class for [RenderSliver]s that contains a single [RenderBox].
1706 1707 1708
///
/// See also:
///
1709 1710 1711 1712 1713 1714
///  * [RenderSliver], which explains more about the Sliver protocol.
///  * [RenderBox], which explains more about the Box protocol.
///  * [RenderSliverToBoxAdapter], which extends this class to size the child
///    according to its preferred size.
///  * [RenderSliverFillRemaining], which extends this class to size the child
///    to fill the remaining space in the viewport.
1715
abstract class RenderSliverSingleBoxAdapter extends RenderSliver with RenderObjectWithChildMixin<RenderBox>, RenderSliverHelpers {
1716
  /// Creates a [RenderSliver] that wraps a [RenderBox].
1717
  RenderSliverSingleBoxAdapter({
1718
    RenderBox? child,
1719 1720 1721 1722 1723 1724 1725
  }) {
    this.child = child;
  }

  @override
  void setupParentData(RenderObject child) {
    if (child.parentData is! SliverPhysicalParentData)
1726
      child.parentData = SliverPhysicalParentData();
1727 1728
  }

1729 1730 1731 1732
  /// Sets the [SliverPhysicalParentData.paintOffset] for the given child
  /// according to the [SliverConstraints.axisDirection] and
  /// [SliverConstraints.growthDirection] and the given geometry.
  @protected
1733
  void setChildParentData(RenderObject child, SliverConstraints constraints, SliverGeometry geometry) {
1734
    final SliverPhysicalParentData childParentData = child.parentData! as SliverPhysicalParentData;
1735 1736 1737 1738
    assert(constraints.axisDirection != null);
    assert(constraints.growthDirection != null);
    switch (applyGrowthDirectionToAxisDirection(constraints.axisDirection, constraints.growthDirection)) {
      case AxisDirection.up:
1739
        childParentData.paintOffset = Offset(0.0, -(geometry.scrollExtent - (geometry.paintExtent + constraints.scrollOffset)));
1740 1741
        break;
      case AxisDirection.right:
1742
        childParentData.paintOffset = Offset(-constraints.scrollOffset, 0.0);
1743 1744
        break;
      case AxisDirection.down:
1745
        childParentData.paintOffset = Offset(0.0, -constraints.scrollOffset);
1746 1747
        break;
      case AxisDirection.left:
1748
        childParentData.paintOffset = Offset(-(geometry.scrollExtent - (geometry.paintExtent + constraints.scrollOffset)), 0.0);
1749 1750 1751 1752 1753 1754
        break;
    }
    assert(childParentData.paintOffset != null);
  }

  @override
1755 1756
  bool hitTestChildren(SliverHitTestResult result, { required double mainAxisPosition, required double crossAxisPosition }) {
    assert(geometry!.hitTestExtent > 0.0);
1757
    if (child != null)
1758
      return hitTestBoxChild(BoxHitTestResult.wrap(result), child!, mainAxisPosition: mainAxisPosition, crossAxisPosition: crossAxisPosition);
1759 1760 1761 1762
    return false;
  }

  @override
1763
  double childMainAxisPosition(RenderBox child) {
1764 1765 1766 1767 1768 1769 1770
    return -constraints.scrollOffset;
  }

  @override
  void applyPaintTransform(RenderObject child, Matrix4 transform) {
    assert(child != null);
    assert(child == this.child);
1771
    final SliverPhysicalParentData childParentData = child.parentData! as SliverPhysicalParentData;
1772 1773 1774 1775 1776
    childParentData.applyPaintTransform(transform);
  }

  @override
  void paint(PaintingContext context, Offset offset) {
1777
    if (child != null && geometry!.visible) {
1778
      final SliverPhysicalParentData childParentData = child!.parentData! as SliverPhysicalParentData;
1779
      context.paintChild(child!, offset + childParentData.paintOffset);
1780 1781 1782
    }
  }
}
1783 1784 1785 1786 1787 1788 1789 1790 1791

/// A [RenderSliver] that contains a single [RenderBox].
///
/// The child will not be laid out if it is not visible. It is sized according
/// to the child's preferences in the main axis, and with a tight constraint
/// forcing it to the dimensions of the viewport in the cross axis.
///
/// See also:
///
1792 1793 1794 1795
///  * [RenderSliver], which explains more about the Sliver protocol.
///  * [RenderBox], which explains more about the Box protocol.
///  * [RenderViewport], which allows [RenderSliver] objects to be placed inside
///    a [RenderBox] (the opposite of this class).
1796 1797 1798
class RenderSliverToBoxAdapter extends RenderSliverSingleBoxAdapter {
  /// Creates a [RenderSliver] that wraps a [RenderBox].
  RenderSliverToBoxAdapter({
1799
    RenderBox? child,
1800 1801 1802 1803 1804 1805 1806 1807
  }) : super(child: child);

  @override
  void performLayout() {
    if (child == null) {
      geometry = SliverGeometry.zero;
      return;
    }
1808
    final SliverConstraints constraints = this.constraints;
1809
    child!.layout(constraints.asBoxConstraints(), parentUsesSize: true);
1810
    final double childExtent;
1811 1812
    switch (constraints.axis) {
      case Axis.horizontal:
1813
        childExtent = child!.size.width;
1814 1815
        break;
      case Axis.vertical:
1816
        childExtent = child!.size.height;
1817 1818 1819 1820
        break;
    }
    assert(childExtent != null);
    final double paintedChildSize = calculatePaintOffset(constraints, from: 0.0, to: childExtent);
1821 1822
    final double cacheExtent = calculateCacheOffset(constraints, from: 0.0, to: childExtent);

1823 1824
    assert(paintedChildSize.isFinite);
    assert(paintedChildSize >= 0.0);
1825
    geometry = SliverGeometry(
1826 1827
      scrollExtent: childExtent,
      paintExtent: paintedChildSize,
1828
      cacheExtent: cacheExtent,
1829 1830 1831 1832
      maxPaintExtent: childExtent,
      hitTestExtent: paintedChildSize,
      hasVisualOverflow: childExtent > constraints.remainingPaintExtent || constraints.scrollOffset > 0.0,
    );
1833
    setChildParentData(child!, constraints, geometry!);
1834 1835
  }
}