// Copyright 2014 The Flutter Authors. All rights reserved. // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. import 'dart:math' as math; import 'package:flutter/foundation.dart'; import 'package:flutter/gestures.dart'; import 'package:flutter/rendering.dart'; import 'package:flutter/scheduler.dart'; import 'basic.dart'; import 'framework.dart'; import 'primary_scroll_controller.dart'; import 'scroll_activity.dart'; import 'scroll_configuration.dart'; import 'scroll_context.dart'; import 'scroll_controller.dart'; import 'scroll_metrics.dart'; import 'scroll_physics.dart'; import 'scroll_position.dart'; import 'scroll_view.dart'; import 'sliver_fill.dart'; import 'viewport.dart'; /// Signature used by [NestedScrollView] for building its header. /// /// The `innerBoxIsScrolled` argument is typically used to control the /// [SliverAppBar.forceElevated] property to ensure that the app bar shows a /// shadow, since it would otherwise not necessarily be aware that it had /// content ostensibly below it. typedef NestedScrollViewHeaderSliversBuilder = List<Widget> Function(BuildContext context, bool innerBoxIsScrolled); /// A scrolling view inside of which can be nested other scrolling views, with /// their scroll positions being intrinsically linked. /// /// The most common use case for this widget is a scrollable view with a /// flexible [SliverAppBar] containing a [TabBar] in the header (built by /// [headerSliverBuilder], and with a [TabBarView] in the [body], such that the /// scrollable view's contents vary based on which tab is visible. /// /// ## Motivation /// /// In a normal [ScrollView], there is one set of slivers (the components of the /// scrolling view). If one of those slivers hosted a [TabBarView] which scrolls /// in the opposite direction (e.g. allowing the user to swipe horizontally /// between the pages represented by the tabs, while the list scrolls /// vertically), then any list inside that [TabBarView] would not interact with /// the outer [ScrollView]. For example, flinging the inner list to scroll to /// the top would not cause a collapsed [SliverAppBar] in the outer [ScrollView] /// to expand. /// /// [NestedScrollView] solves this problem by providing custom /// [ScrollController]s for the outer [ScrollView] and the inner [ScrollView]s /// (those inside the [TabBarView], hooking them together so that they appear, /// to the user, as one coherent scroll view. /// /// {@tool dartpad} /// This example shows a [NestedScrollView] whose header is the combination of a /// [TabBar] in a [SliverAppBar] and whose body is a [TabBarView]. It uses a /// [SliverOverlapAbsorber]/[SliverOverlapInjector] pair to make the inner lists /// align correctly, and it uses [SafeArea] to avoid any horizontal disturbances /// (e.g. the "notch" on iOS when the phone is horizontal). In addition, /// [PageStorageKey]s are used to remember the scroll position of each tab's /// list. /// /// ** See code in examples/api/lib/widgets/nested_scroll_view/nested_scroll_view.0.dart ** /// {@end-tool} /// /// ## [SliverAppBar]s with [NestedScrollView]s /// /// Using a [SliverAppBar] in the outer scroll view, or [headerSliverBuilder], /// of a [NestedScrollView] may require special configurations in order to work /// as it would if the outer and inner were one single scroll view, like a /// [CustomScrollView]. /// /// ### Pinned [SliverAppBar]s /// /// A pinned [SliverAppBar] works in a [NestedScrollView] exactly as it would in /// another scroll view, like [CustomScrollView]. When using /// [SliverAppBar.pinned], the app bar remains visible at the top of the scroll /// view. The app bar can still expand and contract as the user scrolls, but it /// will remain visible rather than being scrolled out of view. /// /// This works naturally in a [NestedScrollView], as the pinned [SliverAppBar] /// is not expected to move in or out of the visible portion of the viewport. /// As the inner or outer [Scrollable]s are moved, the app bar persists as /// expected. /// /// If the app bar is floating, pinned, and using an expanded height, follow the /// floating convention laid out below. /// /// ### Floating [SliverAppBar]s /// /// When placed in the outer scrollable, or the [headerSliverBuilder], /// a [SliverAppBar] that floats, using [SliverAppBar.floating] will not be /// triggered to float over the inner scroll view, or [body], automatically. /// /// This is because a floating app bar uses the scroll offset of its own /// [Scrollable] to dictate the floating action. Being two separate inner and /// outer [Scrollable]s, a [SliverAppBar] in the outer header is not aware of /// changes in the scroll offset of the inner body. /// /// In order to float the outer, use [NestedScrollView.floatHeaderSlivers]. When /// set to true, the nested scrolling coordinator will prioritize floating in /// the header slivers before applying the remaining drag to the body. /// /// Furthermore, the `floatHeaderSlivers` flag should also be used when using an /// app bar that is floating, pinned, and has an expanded height. In this /// configuration, the flexible space of the app bar will open and collapse, /// while the primary portion of the app bar remains pinned. /// /// {@tool dartpad} /// This simple example shows a [NestedScrollView] whose header contains a /// floating [SliverAppBar]. By using the [floatHeaderSlivers] property, the /// floating behavior is coordinated between the outer and inner [Scrollable]s, /// so it behaves as it would in a single scrollable. /// /// ** See code in examples/api/lib/widgets/nested_scroll_view/nested_scroll_view.1.dart ** /// {@end-tool} /// /// ### Snapping [SliverAppBar]s /// /// Floating [SliverAppBar]s also have the option to perform a snapping animation. /// If [SliverAppBar.snap] is true, then a scroll that exposes the floating app /// bar will trigger an animation that slides the entire app bar into view. /// Similarly if a scroll dismisses the app bar, the animation will slide the /// app bar completely out of view. /// /// It is possible with a [NestedScrollView] to perform just the snapping /// animation without floating the app bar in and out. By not using the /// [NestedScrollView.floatHeaderSlivers], the app bar will snap in and out /// without floating. /// /// The [SliverAppBar.snap] animation should be used in conjunction with the /// [SliverOverlapAbsorber] and [SliverOverlapInjector] widgets when /// implemented in a [NestedScrollView]. These widgets take any overlapping /// behavior of the [SliverAppBar] in the header and redirect it to the /// [SliverOverlapInjector] in the body. If it is missing, then it is possible /// for the nested "inner" scroll view below to end up under the [SliverAppBar] /// even when the inner scroll view thinks it has not been scrolled. /// /// {@tool dartpad} /// This simple example shows a [NestedScrollView] whose header contains a /// snapping, floating [SliverAppBar]. _Without_ setting any additional flags, /// e.g [NestedScrollView.floatHeaderSlivers], the [SliverAppBar] will animate /// in and out without floating. The [SliverOverlapAbsorber] and /// [SliverOverlapInjector] maintain the proper alignment between the two /// separate scroll views. /// /// ** See code in examples/api/lib/widgets/nested_scroll_view/nested_scroll_view.2.dart ** /// {@end-tool} /// /// ### Snapping and Floating [SliverAppBar]s /// // See https://github.com/flutter/flutter/issues/59189 /// Currently, [NestedScrollView] does not support simultaneously floating and /// snapping the outer scrollable, e.g. when using [SliverAppBar.floating] & /// [SliverAppBar.snap] at the same time. /// /// ### Stretching [SliverAppBar]s /// // See https://github.com/flutter/flutter/issues/54059 /// Currently, [NestedScrollView] does not support stretching the outer /// scrollable, e.g. when using [SliverAppBar.stretch]. /// /// See also: /// /// * [SliverAppBar], for examples on different configurations like floating, /// pinned and snap behaviors. /// * [SliverOverlapAbsorber], a sliver that wraps another, forcing its layout /// extent to be treated as overlap. /// * [SliverOverlapInjector], a sliver that has a sliver geometry based on /// the values stored in a [SliverOverlapAbsorberHandle]. class NestedScrollView extends StatefulWidget { /// Creates a nested scroll view. /// /// The [reverse], [headerSliverBuilder], and [body] arguments must not be /// null. const NestedScrollView({ super.key, this.controller, this.scrollDirection = Axis.vertical, this.reverse = false, this.physics, required this.headerSliverBuilder, required this.body, this.dragStartBehavior = DragStartBehavior.start, this.floatHeaderSlivers = false, this.clipBehavior = Clip.hardEdge, this.restorationId, this.scrollBehavior, }) : assert(scrollDirection != null), assert(reverse != null), assert(headerSliverBuilder != null), assert(body != null), assert(floatHeaderSlivers != null), assert(clipBehavior != null); /// An object that can be used to control the position to which the outer /// scroll view is scrolled. final ScrollController? controller; /// The axis along which the scroll view scrolls. /// /// Defaults to [Axis.vertical]. final Axis scrollDirection; /// Whether the scroll view scrolls in the reading direction. /// /// For example, if the reading direction is left-to-right and /// [scrollDirection] is [Axis.horizontal], then the scroll view scrolls from /// left to right when [reverse] is false and from right to left when /// [reverse] is true. /// /// Similarly, if [scrollDirection] is [Axis.vertical], then the scroll view /// scrolls from top to bottom when [reverse] is false and from bottom to top /// when [reverse] is true. /// /// Defaults to false. final bool reverse; /// How the scroll view should respond to user input. /// /// For example, determines how the scroll view continues to animate after the /// user stops dragging the scroll view (providing a custom implementation of /// [ScrollPhysics.createBallisticSimulation] allows this particular aspect of /// the physics to be overridden). /// /// If an explicit [ScrollBehavior] is provided to [scrollBehavior], the /// [ScrollPhysics] provided by that behavior will take precedence after /// [physics]. /// /// Defaults to matching platform conventions. /// /// The [ScrollPhysics.applyBoundaryConditions] implementation of the provided /// object should not allow scrolling outside the scroll extent range /// described by the [ScrollMetrics.minScrollExtent] and /// [ScrollMetrics.maxScrollExtent] properties passed to that method. If that /// invariant is not maintained, the nested scroll view may respond to user /// scrolling erratically. final ScrollPhysics? physics; /// A builder for any widgets that are to precede the inner scroll views (as /// given by [body]). /// /// Typically this is used to create a [SliverAppBar] with a [TabBar]. final NestedScrollViewHeaderSliversBuilder headerSliverBuilder; /// The widget to show inside the [NestedScrollView]. /// /// Typically this will be [TabBarView]. /// /// The [body] is built in a context that provides a [PrimaryScrollController] /// that interacts with the [NestedScrollView]'s scroll controller. Any /// [ListView] or other [Scrollable]-based widget inside the [body] that is /// intended to scroll with the [NestedScrollView] should therefore not be /// given an explicit [ScrollController], instead allowing it to default to /// the [PrimaryScrollController] provided by the [NestedScrollView]. final Widget body; /// {@macro flutter.widgets.scrollable.dragStartBehavior} final DragStartBehavior dragStartBehavior; /// Whether or not the [NestedScrollView]'s coordinator should prioritize the /// outer scrollable over the inner when scrolling back. /// /// This is useful for an outer scrollable containing a [SliverAppBar] that /// is expected to float. This cannot be null. final bool floatHeaderSlivers; /// {@macro flutter.material.Material.clipBehavior} /// /// Defaults to [Clip.hardEdge]. final Clip clipBehavior; /// {@macro flutter.widgets.scrollable.restorationId} final String? restorationId; /// {@macro flutter.widgets.shadow.scrollBehavior} /// /// [ScrollBehavior]s also provide [ScrollPhysics]. If an explicit /// [ScrollPhysics] is provided in [physics], it will take precedence, /// followed by [scrollBehavior], and then the inherited ancestor /// [ScrollBehavior]. /// /// The [ScrollBehavior] of the inherited [ScrollConfiguration] will be /// modified by default to not apply a [Scrollbar]. This is because the /// NestedScrollView cannot assume the configuration of the outer and inner /// [Scrollable] widgets, particularly whether to treat them as one scrollable, /// or separate and desirous of unique behaviors. final ScrollBehavior? scrollBehavior; /// Returns the [SliverOverlapAbsorberHandle] of the nearest ancestor /// [NestedScrollView]. /// /// This is necessary to configure the [SliverOverlapAbsorber] and /// [SliverOverlapInjector] widgets. /// /// For sample code showing how to use this method, see the [NestedScrollView] /// documentation. static SliverOverlapAbsorberHandle sliverOverlapAbsorberHandleFor(BuildContext context) { final _InheritedNestedScrollView? target = context.dependOnInheritedWidgetOfExactType<_InheritedNestedScrollView>(); assert( target != null, 'NestedScrollView.sliverOverlapAbsorberHandleFor must be called with a context that contains a NestedScrollView.', ); return target!.state._absorberHandle; } List<Widget> _buildSlivers(BuildContext context, ScrollController innerController, bool bodyIsScrolled) { return <Widget>[ ...headerSliverBuilder(context, bodyIsScrolled), SliverFillRemaining( // The inner (body) scroll view must use this scroll controller so that // the independent scroll positions can be kept in sync. child: PrimaryScrollController( // The inner scroll view should always inherit this // PrimaryScrollController, on every platform. automaticallyInheritForPlatforms: TargetPlatform.values.toSet(), // `PrimaryScrollController.scrollDirection` is not set, and so it is // restricted to the default Axis.vertical. // Ideally the inner and outer views would have the same // scroll direction, and so we could assume // `NestedScrollView.scrollDirection` for the PrimaryScrollController, // but use cases already exist where the axes are mismatched. // https://github.com/flutter/flutter/issues/102001 controller: innerController, child: body, ), ), ]; } @override NestedScrollViewState createState() => NestedScrollViewState(); } /// The [State] for a [NestedScrollView]. /// /// The [ScrollController]s, [innerController] and [outerController], of the /// [NestedScrollView]'s children may be accessed through its state. This is /// useful for obtaining respective scroll positions in the [NestedScrollView]. /// /// If you want to access the inner or outer scroll controller of a /// [NestedScrollView], you can get its [NestedScrollViewState] by supplying a /// `GlobalKey<NestedScrollViewState>` to the [NestedScrollView.key] parameter). /// /// {@tool dartpad} /// [NestedScrollViewState] can be obtained using a [GlobalKey]. /// Using the following setup, you can access the inner scroll controller /// using `globalKey.currentState.innerController`. /// /// ** See code in examples/api/lib/widgets/nested_scroll_view/nested_scroll_view_state.0.dart ** /// {@end-tool} class NestedScrollViewState extends State<NestedScrollView> { final SliverOverlapAbsorberHandle _absorberHandle = SliverOverlapAbsorberHandle(); /// The [ScrollController] provided to the [ScrollView] in /// [NestedScrollView.body]. /// /// Manipulating the [ScrollPosition] of this controller pushes the outer /// header sliver(s) up and out of view. The position of the [outerController] /// will be set to [ScrollPosition.maxScrollExtent], unless you use /// [ScrollPosition.setPixels]. /// /// See also: /// /// * [outerController], which exposes the [ScrollController] used by the /// sliver(s) contained in [NestedScrollView.headerSliverBuilder]. ScrollController get innerController => _coordinator!._innerController; /// The [ScrollController] provided to the [ScrollView] in /// [NestedScrollView.headerSliverBuilder]. /// /// This is equivalent to [NestedScrollView.controller], if provided. /// /// Manipulating the [ScrollPosition] of this controller pushes the inner body /// sliver(s) down. The position of the [innerController] will be set to /// [ScrollPosition.minScrollExtent], unless you use /// [ScrollPosition.setPixels]. Visually, the inner body will be scrolled to /// its beginning. /// /// See also: /// /// * [innerController], which exposes the [ScrollController] used by the /// [ScrollView] contained in [NestedScrollView.body]. ScrollController get outerController => _coordinator!._outerController; _NestedScrollCoordinator? _coordinator; @override void initState() { super.initState(); _coordinator = _NestedScrollCoordinator( this, widget.controller, _handleHasScrolledBodyChanged, widget.floatHeaderSlivers, ); } @override void didChangeDependencies() { super.didChangeDependencies(); _coordinator!.setParent(widget.controller); } @override void didUpdateWidget(NestedScrollView oldWidget) { super.didUpdateWidget(oldWidget); if (oldWidget.controller != widget.controller) { _coordinator!.setParent(widget.controller); } } @override void dispose() { _coordinator!.dispose(); _coordinator = null; super.dispose(); } bool? _lastHasScrolledBody; void _handleHasScrolledBodyChanged() { if (!mounted) { return; } final bool newHasScrolledBody = _coordinator!.hasScrolledBody; if (_lastHasScrolledBody != newHasScrolledBody) { setState(() { // _coordinator.hasScrolledBody changed (we use it in the build method) // (We record _lastHasScrolledBody in the build() method, rather than in // this setState call, because the build() method may be called more // often than just from here, and we want to only call setState when the // new value is different than the last built value.) }); } } @override Widget build(BuildContext context) { final ScrollPhysics scrollPhysics = widget.physics?.applyTo(const ClampingScrollPhysics()) ?? widget.scrollBehavior?.getScrollPhysics(context).applyTo(const ClampingScrollPhysics()) ?? const ClampingScrollPhysics(); return _InheritedNestedScrollView( state: this, child: Builder( builder: (BuildContext context) { _lastHasScrolledBody = _coordinator!.hasScrolledBody; return _NestedScrollViewCustomScrollView( dragStartBehavior: widget.dragStartBehavior, scrollDirection: widget.scrollDirection, reverse: widget.reverse, physics: scrollPhysics, scrollBehavior: widget.scrollBehavior ?? ScrollConfiguration.of(context).copyWith(scrollbars: false), controller: _coordinator!._outerController, slivers: widget._buildSlivers( context, _coordinator!._innerController, _lastHasScrolledBody!, ), handle: _absorberHandle, clipBehavior: widget.clipBehavior, restorationId: widget.restorationId, ); }, ), ); } } class _NestedScrollViewCustomScrollView extends CustomScrollView { const _NestedScrollViewCustomScrollView({ required super.scrollDirection, required super.reverse, required ScrollPhysics super.physics, required ScrollBehavior super.scrollBehavior, required ScrollController super.controller, required super.slivers, required this.handle, required super.clipBehavior, super.dragStartBehavior, super.restorationId, }); final SliverOverlapAbsorberHandle handle; @override Widget buildViewport( BuildContext context, ViewportOffset offset, AxisDirection axisDirection, List<Widget> slivers, ) { assert(!shrinkWrap); return NestedScrollViewViewport( axisDirection: axisDirection, offset: offset, slivers: slivers, handle: handle, clipBehavior: clipBehavior, ); } } class _InheritedNestedScrollView extends InheritedWidget { const _InheritedNestedScrollView({ required this.state, required super.child, }) : assert(state != null), assert(child != null); final NestedScrollViewState state; @override bool updateShouldNotify(_InheritedNestedScrollView old) => state != old.state; } class _NestedScrollMetrics extends FixedScrollMetrics { _NestedScrollMetrics({ required super.minScrollExtent, required super.maxScrollExtent, required super.pixels, required super.viewportDimension, required super.axisDirection, required this.minRange, required this.maxRange, required this.correctionOffset, }); @override _NestedScrollMetrics copyWith({ double? minScrollExtent, double? maxScrollExtent, double? pixels, double? viewportDimension, AxisDirection? axisDirection, double? minRange, double? maxRange, double? correctionOffset, }) { return _NestedScrollMetrics( minScrollExtent: minScrollExtent ?? (hasContentDimensions ? this.minScrollExtent : null), maxScrollExtent: maxScrollExtent ?? (hasContentDimensions ? this.maxScrollExtent : null), pixels: pixels ?? (hasPixels ? this.pixels : null), viewportDimension: viewportDimension ?? (hasViewportDimension ? this.viewportDimension : null), axisDirection: axisDirection ?? this.axisDirection, minRange: minRange ?? this.minRange, maxRange: maxRange ?? this.maxRange, correctionOffset: correctionOffset ?? this.correctionOffset, ); } final double minRange; final double maxRange; final double correctionOffset; } typedef _NestedScrollActivityGetter = ScrollActivity Function(_NestedScrollPosition position); class _NestedScrollCoordinator implements ScrollActivityDelegate, ScrollHoldController { _NestedScrollCoordinator( this._state, this._parent, this._onHasScrolledBodyChanged, this._floatHeaderSlivers, ) { final double initialScrollOffset = _parent?.initialScrollOffset ?? 0.0; _outerController = _NestedScrollController( this, initialScrollOffset: initialScrollOffset, debugLabel: 'outer', ); _innerController = _NestedScrollController( this, debugLabel: 'inner', ); } final NestedScrollViewState _state; ScrollController? _parent; final VoidCallback _onHasScrolledBodyChanged; final bool _floatHeaderSlivers; late _NestedScrollController _outerController; late _NestedScrollController _innerController; _NestedScrollPosition? get _outerPosition { if (!_outerController.hasClients) { return null; } return _outerController.nestedPositions.single; } Iterable<_NestedScrollPosition> get _innerPositions { return _innerController.nestedPositions; } bool get canScrollBody { final _NestedScrollPosition? outer = _outerPosition; if (outer == null) { return true; } return outer.haveDimensions && outer.extentAfter == 0.0; } bool get hasScrolledBody { for (final _NestedScrollPosition position in _innerPositions) { if (!position.hasContentDimensions || !position.hasPixels) { // It's possible that NestedScrollView built twice before layout phase // in the same frame. This can happen when the FocusManager schedules a microTask // that marks NestedScrollView dirty during the warm up frame. // https://github.com/flutter/flutter/pull/75308 continue; } else if (position.pixels > position.minScrollExtent) { return true; } } return false; } void updateShadow() { _onHasScrolledBodyChanged(); } ScrollDirection get userScrollDirection => _userScrollDirection; ScrollDirection _userScrollDirection = ScrollDirection.idle; void updateUserScrollDirection(ScrollDirection value) { assert(value != null); if (userScrollDirection == value) { return; } _userScrollDirection = value; _outerPosition!.didUpdateScrollDirection(value); for (final _NestedScrollPosition position in _innerPositions) { position.didUpdateScrollDirection(value); } } ScrollDragController? _currentDrag; void beginActivity(ScrollActivity newOuterActivity, _NestedScrollActivityGetter innerActivityGetter) { _outerPosition!.beginActivity(newOuterActivity); bool scrolling = newOuterActivity.isScrolling; for (final _NestedScrollPosition position in _innerPositions) { final ScrollActivity newInnerActivity = innerActivityGetter(position); position.beginActivity(newInnerActivity); scrolling = scrolling && newInnerActivity.isScrolling; } _currentDrag?.dispose(); _currentDrag = null; if (!scrolling) { updateUserScrollDirection(ScrollDirection.idle); } } @override AxisDirection get axisDirection => _outerPosition!.axisDirection; static IdleScrollActivity _createIdleScrollActivity(_NestedScrollPosition position) { return IdleScrollActivity(position); } @override void goIdle() { beginActivity( _createIdleScrollActivity(_outerPosition!), _createIdleScrollActivity, ); } @override void goBallistic(double velocity) { beginActivity( createOuterBallisticScrollActivity(velocity), (_NestedScrollPosition position) { return createInnerBallisticScrollActivity( position, velocity, ); }, ); } // TODO(Piinks): https://github.com/flutter/flutter/issues/100748 @override Simulation? updateBallisticAnimation(double initVelocity, double initPosition) { return null; } ScrollActivity createOuterBallisticScrollActivity(double velocity) { // This function creates a ballistic scroll for the outer scrollable. // // It assumes that the outer scrollable can't be overscrolled, and sets up a // ballistic scroll over the combined space of the innerPositions and the // outerPosition. // First we must pick a representative inner position that we will care // about. This is somewhat arbitrary. Ideally we'd pick the one that is "in // the center" but there isn't currently a good way to do that so we // arbitrarily pick the one that is the furthest away from the infinity we // are heading towards. _NestedScrollPosition? innerPosition; if (velocity != 0.0) { for (final _NestedScrollPosition position in _innerPositions) { if (innerPosition != null) { if (velocity > 0.0) { if (innerPosition.pixels < position.pixels) { continue; } } else { assert(velocity < 0.0); if (innerPosition.pixels > position.pixels) { continue; } } } innerPosition = position; } } if (innerPosition == null) { // It's either just us or a velocity=0 situation. return _outerPosition!.createBallisticScrollActivity( _outerPosition!.physics.createBallisticSimulation( _outerPosition!, velocity, ), mode: _NestedBallisticScrollActivityMode.independent, ); } final _NestedScrollMetrics metrics = _getMetrics(innerPosition, velocity); return _outerPosition!.createBallisticScrollActivity( _outerPosition!.physics.createBallisticSimulation(metrics, velocity), mode: _NestedBallisticScrollActivityMode.outer, metrics: metrics, ); } @protected ScrollActivity createInnerBallisticScrollActivity(_NestedScrollPosition position, double velocity) { return position.createBallisticScrollActivity( position.physics.createBallisticSimulation( _getMetrics(position, velocity), velocity, ), mode: _NestedBallisticScrollActivityMode.inner, ); } _NestedScrollMetrics _getMetrics(_NestedScrollPosition innerPosition, double velocity) { assert(innerPosition != null); double pixels, minRange, maxRange, correctionOffset; double extra = 0.0; if (innerPosition.pixels == innerPosition.minScrollExtent) { pixels = clampDouble(_outerPosition!.pixels, _outerPosition!.minScrollExtent, _outerPosition!.maxScrollExtent, ); // TODO(ianh): gracefully handle out-of-range outer positions minRange = _outerPosition!.minScrollExtent; maxRange = _outerPosition!.maxScrollExtent; assert(minRange <= maxRange); correctionOffset = 0.0; } else { assert(innerPosition.pixels != innerPosition.minScrollExtent); if (innerPosition.pixels < innerPosition.minScrollExtent) { pixels = innerPosition.pixels - innerPosition.minScrollExtent + _outerPosition!.minScrollExtent; } else { assert(innerPosition.pixels > innerPosition.minScrollExtent); pixels = innerPosition.pixels - innerPosition.minScrollExtent + _outerPosition!.maxScrollExtent; } if ((velocity > 0.0) && (innerPosition.pixels > innerPosition.minScrollExtent)) { // This handles going forward (fling up) and inner list is scrolled past // zero. We want to grab the extra pixels immediately to shrink. extra = _outerPosition!.maxScrollExtent - _outerPosition!.pixels; assert(extra >= 0.0); minRange = pixels; maxRange = pixels + extra; assert(minRange <= maxRange); correctionOffset = _outerPosition!.pixels - pixels; } else if ((velocity < 0.0) && (innerPosition.pixels < innerPosition.minScrollExtent)) { // This handles going backward (fling down) and inner list is // underscrolled. We want to grab the extra pixels immediately to grow. extra = _outerPosition!.pixels - _outerPosition!.minScrollExtent; assert(extra >= 0.0); minRange = pixels - extra; maxRange = pixels; assert(minRange <= maxRange); correctionOffset = _outerPosition!.pixels - pixels; } else { // This handles going forward (fling up) and inner list is // underscrolled, OR, going backward (fling down) and inner list is // scrolled past zero. We want to skip the pixels we don't need to grow // or shrink over. if (velocity > 0.0) { // shrinking extra = _outerPosition!.minScrollExtent - _outerPosition!.pixels; } else if (velocity < 0.0) { // growing extra = _outerPosition!.pixels - (_outerPosition!.maxScrollExtent - _outerPosition!.minScrollExtent); } assert(extra <= 0.0); minRange = _outerPosition!.minScrollExtent; maxRange = _outerPosition!.maxScrollExtent + extra; assert(minRange <= maxRange); correctionOffset = 0.0; } } return _NestedScrollMetrics( minScrollExtent: _outerPosition!.minScrollExtent, maxScrollExtent: _outerPosition!.maxScrollExtent + innerPosition.maxScrollExtent - innerPosition.minScrollExtent + extra, pixels: pixels, viewportDimension: _outerPosition!.viewportDimension, axisDirection: _outerPosition!.axisDirection, minRange: minRange, maxRange: maxRange, correctionOffset: correctionOffset, ); } double unnestOffset(double value, _NestedScrollPosition source) { if (source == _outerPosition) { return clampDouble(value, _outerPosition!.minScrollExtent, _outerPosition!.maxScrollExtent, ); } if (value < source.minScrollExtent) { return value - source.minScrollExtent + _outerPosition!.minScrollExtent; } return value - source.minScrollExtent + _outerPosition!.maxScrollExtent; } double nestOffset(double value, _NestedScrollPosition target) { if (target == _outerPosition) { return clampDouble(value, _outerPosition!.minScrollExtent, _outerPosition!.maxScrollExtent, ); } if (value < _outerPosition!.minScrollExtent) { return value - _outerPosition!.minScrollExtent + target.minScrollExtent; } if (value > _outerPosition!.maxScrollExtent) { return value - _outerPosition!.maxScrollExtent + target.minScrollExtent; } return target.minScrollExtent; } void updateCanDrag() { if (!_outerPosition!.haveDimensions) { return; } double maxInnerExtent = 0.0; for (final _NestedScrollPosition position in _innerPositions) { if (!position.haveDimensions) { return; } maxInnerExtent = math.max( maxInnerExtent, position.maxScrollExtent - position.minScrollExtent, ); } _outerPosition!.updateCanDrag(maxInnerExtent); } Future<void> animateTo( double to, { required Duration duration, required Curve curve, }) async { final DrivenScrollActivity outerActivity = _outerPosition!.createDrivenScrollActivity( nestOffset(to, _outerPosition!), duration, curve, ); final List<Future<void>> resultFutures = <Future<void>>[outerActivity.done]; beginActivity( outerActivity, (_NestedScrollPosition position) { final DrivenScrollActivity innerActivity = position.createDrivenScrollActivity( nestOffset(to, position), duration, curve, ); resultFutures.add(innerActivity.done); return innerActivity; }, ); await Future.wait<void>(resultFutures); } void jumpTo(double to) { goIdle(); _outerPosition!.localJumpTo(nestOffset(to, _outerPosition!)); for (final _NestedScrollPosition position in _innerPositions) { position.localJumpTo(nestOffset(to, position)); } goBallistic(0.0); } void pointerScroll(double delta) { // If an update is made to pointer scrolling here, consider if the same // (or similar) change should be made in // ScrollPositionWithSingleContext.pointerScroll. assert(delta != 0.0); goIdle(); updateUserScrollDirection( delta < 0.0 ? ScrollDirection.forward : ScrollDirection.reverse, ); // Handle notifications. Even if only one position actually receives // the delta, the NestedScrollView's intention is to treat multiple // ScrollPositions as one. _outerPosition!.isScrollingNotifier.value = true; _outerPosition!.didStartScroll(); for (final _NestedScrollPosition position in _innerPositions) { position.isScrollingNotifier.value = true; position.didStartScroll(); } if (_innerPositions.isEmpty) { // Does not enter overscroll. _outerPosition!.applyClampedPointerSignalUpdate(delta); } else if (delta > 0.0) { // Dragging "up" - delta is positive // Prioritize getting rid of any inner overscroll, and then the outer // view, so that the app bar will scroll out of the way asap. double outerDelta = delta; for (final _NestedScrollPosition position in _innerPositions) { if (position.pixels < 0.0) { // This inner position is in overscroll. final double potentialOuterDelta = position.applyClampedPointerSignalUpdate(delta); // In case there are multiple positions in varying states of // overscroll, the first to 'reach' the outer view above takes // precedence. outerDelta = math.max(outerDelta, potentialOuterDelta); } } if (outerDelta != 0.0) { final double innerDelta = _outerPosition!.applyClampedPointerSignalUpdate( outerDelta, ); if (innerDelta != 0.0) { for (final _NestedScrollPosition position in _innerPositions) { position.applyClampedPointerSignalUpdate(innerDelta); } } } } else { // Dragging "down" - delta is negative double innerDelta = delta; // Apply delta to the outer header first if it is configured to float. if (_floatHeaderSlivers) { innerDelta = _outerPosition!.applyClampedPointerSignalUpdate(delta); } if (innerDelta != 0.0) { // Apply the innerDelta, if we have not floated in the outer scrollable, // any leftover delta after this will be passed on to the outer // scrollable by the outerDelta. double outerDelta = 0.0; // it will go negative if it changes for (final _NestedScrollPosition position in _innerPositions) { final double overscroll = position.applyClampedPointerSignalUpdate(innerDelta); outerDelta = math.min(outerDelta, overscroll); } if (outerDelta != 0.0) { _outerPosition!.applyClampedPointerSignalUpdate(outerDelta); } } } _outerPosition!.didEndScroll(); for (final _NestedScrollPosition position in _innerPositions) { position.didEndScroll(); } goBallistic(0.0); } @override double setPixels(double newPixels) { assert(false); return 0.0; } ScrollHoldController hold(VoidCallback holdCancelCallback) { beginActivity( HoldScrollActivity( delegate: _outerPosition!, onHoldCanceled: holdCancelCallback, ), (_NestedScrollPosition position) => HoldScrollActivity(delegate: position), ); return this; } @override void cancel() { goBallistic(0.0); } Drag drag(DragStartDetails details, VoidCallback dragCancelCallback) { final ScrollDragController drag = ScrollDragController( delegate: this, details: details, onDragCanceled: dragCancelCallback, ); beginActivity( DragScrollActivity(_outerPosition!, drag), (_NestedScrollPosition position) => DragScrollActivity(position, drag), ); assert(_currentDrag == null); _currentDrag = drag; return drag; } @override void applyUserOffset(double delta) { updateUserScrollDirection( delta > 0.0 ? ScrollDirection.forward : ScrollDirection.reverse, ); assert(delta != 0.0); if (_innerPositions.isEmpty) { _outerPosition!.applyFullDragUpdate(delta); } else if (delta < 0.0) { // Dragging "up" // Prioritize getting rid of any inner overscroll, and then the outer // view, so that the app bar will scroll out of the way asap. double outerDelta = delta; for (final _NestedScrollPosition position in _innerPositions) { if (position.pixels < 0.0) { // This inner position is in overscroll. final double potentialOuterDelta = position.applyClampedDragUpdate(delta); // In case there are multiple positions in varying states of // overscroll, the first to 'reach' the outer view above takes // precedence. outerDelta = math.max(outerDelta, potentialOuterDelta); } } if (outerDelta != 0.0) { final double innerDelta = _outerPosition!.applyClampedDragUpdate( outerDelta, ); if (innerDelta != 0.0) { for (final _NestedScrollPosition position in _innerPositions) { position.applyFullDragUpdate(innerDelta); } } } } else { // Dragging "down" - delta is positive double innerDelta = delta; // Apply delta to the outer header first if it is configured to float. if (_floatHeaderSlivers) { innerDelta = _outerPosition!.applyClampedDragUpdate(delta); } if (innerDelta != 0.0) { // Apply the innerDelta, if we have not floated in the outer scrollable, // any leftover delta after this will be passed on to the outer // scrollable by the outerDelta. double outerDelta = 0.0; // it will go positive if it changes final List<double> overscrolls = <double>[]; final List<_NestedScrollPosition> innerPositions = _innerPositions.toList(); for (final _NestedScrollPosition position in innerPositions) { final double overscroll = position.applyClampedDragUpdate(innerDelta); outerDelta = math.max(outerDelta, overscroll); overscrolls.add(overscroll); } if (outerDelta != 0.0) { outerDelta -= _outerPosition!.applyClampedDragUpdate(outerDelta); } // Now deal with any overscroll for (int i = 0; i < innerPositions.length; ++i) { final double remainingDelta = overscrolls[i] - outerDelta; if (remainingDelta > 0.0) { innerPositions[i].applyFullDragUpdate(remainingDelta); } } } } } void setParent(ScrollController? value) { _parent = value; updateParent(); } void updateParent() { _outerPosition?.setParent( _parent ?? PrimaryScrollController.of(_state.context), ); } @mustCallSuper void dispose() { _currentDrag?.dispose(); _currentDrag = null; _outerController.dispose(); _innerController.dispose(); } @override String toString() => '${objectRuntimeType(this, '_NestedScrollCoordinator')}(outer=$_outerController; inner=$_innerController)'; } class _NestedScrollController extends ScrollController { _NestedScrollController( this.coordinator, { super.initialScrollOffset, super.debugLabel, }); final _NestedScrollCoordinator coordinator; @override ScrollPosition createScrollPosition( ScrollPhysics physics, ScrollContext context, ScrollPosition? oldPosition, ) { return _NestedScrollPosition( coordinator: coordinator, physics: physics, context: context, initialPixels: initialScrollOffset, oldPosition: oldPosition, debugLabel: debugLabel, ); } @override void attach(ScrollPosition position) { assert(position is _NestedScrollPosition); super.attach(position); coordinator.updateParent(); coordinator.updateCanDrag(); position.addListener(_scheduleUpdateShadow); _scheduleUpdateShadow(); } @override void detach(ScrollPosition position) { assert(position is _NestedScrollPosition); (position as _NestedScrollPosition).setParent(null); position.removeListener(_scheduleUpdateShadow); super.detach(position); _scheduleUpdateShadow(); } void _scheduleUpdateShadow() { // We do this asynchronously for attach() so that the new position has had // time to be initialized, and we do it asynchronously for detach() and from // the position change notifications because those happen synchronously // during a frame, at a time where it's too late to call setState. Since the // result is usually animated, the lag incurred is no big deal. SchedulerBinding.instance.addPostFrameCallback( (Duration timeStamp) { coordinator.updateShadow(); }, ); } Iterable<_NestedScrollPosition> get nestedPositions { // TODO(vegorov): use instance method version of castFrom when it is available. return Iterable.castFrom<ScrollPosition, _NestedScrollPosition>(positions); } } // The _NestedScrollPosition is used by both the inner and outer viewports of a // NestedScrollView. It tracks the offset to use for those viewports, and knows // about the _NestedScrollCoordinator, so that when activities are triggered on // this class, they can defer, or be influenced by, the coordinator. class _NestedScrollPosition extends ScrollPosition implements ScrollActivityDelegate { _NestedScrollPosition({ required super.physics, required super.context, double initialPixels = 0.0, super.oldPosition, super.debugLabel, required this.coordinator, }) { if (!hasPixels && initialPixels != null) { correctPixels(initialPixels); } if (activity == null) { goIdle(); } assert(activity != null); saveScrollOffset(); // in case we didn't restore but could, so that we don't restore it later } final _NestedScrollCoordinator coordinator; TickerProvider get vsync => context.vsync; ScrollController? _parent; void setParent(ScrollController? value) { _parent?.detach(this); _parent = value; _parent?.attach(this); } @override AxisDirection get axisDirection => context.axisDirection; @override void absorb(ScrollPosition other) { super.absorb(other); activity!.updateDelegate(this); } @override void restoreScrollOffset() { if (coordinator.canScrollBody) { super.restoreScrollOffset(); } } // Returns the amount of delta that was not used. // // Positive delta means going down (exposing stuff above), negative delta // going up (exposing stuff below). double applyClampedDragUpdate(double delta) { assert(delta != 0.0); // If we are going towards the maxScrollExtent (negative scroll offset), // then the furthest we can be in the minScrollExtent direction is negative // infinity. For example, if we are already overscrolled, then scrolling to // reduce the overscroll should not disallow the overscroll. // // If we are going towards the minScrollExtent (positive scroll offset), // then the furthest we can be in the minScrollExtent direction is wherever // we are now, if we are already overscrolled (in which case pixels is less // than the minScrollExtent), or the minScrollExtent if we are not. // // In other words, we cannot, via applyClampedDragUpdate, _enter_ an // overscroll situation. // // An overscroll situation might be nonetheless entered via several means. // One is if the physics allow it, via applyFullDragUpdate (see below). An // overscroll situation can also be forced, e.g. if the scroll position is // artificially set using the scroll controller. final double min = delta < 0.0 ? -double.infinity : math.min(minScrollExtent, pixels); // The logic for max is equivalent but on the other side. final double max = delta > 0.0 ? double.infinity // If pixels < 0.0, then we are currently in overscroll. The max should be // 0.0, representing the end of the overscrolled portion. : pixels < 0.0 ? 0.0 : math.max(maxScrollExtent, pixels); final double oldPixels = pixels; final double newPixels = clampDouble(pixels - delta, min, max); final double clampedDelta = newPixels - pixels; if (clampedDelta == 0.0) { return delta; } final double overscroll = physics.applyBoundaryConditions(this, newPixels); final double actualNewPixels = newPixels - overscroll; final double offset = actualNewPixels - oldPixels; if (offset != 0.0) { forcePixels(actualNewPixels); didUpdateScrollPositionBy(offset); } return delta + offset; } // Returns the overscroll. double applyFullDragUpdate(double delta) { assert(delta != 0.0); final double oldPixels = pixels; // Apply friction: final double newPixels = pixels - physics.applyPhysicsToUserOffset( this, delta, ); if (oldPixels == newPixels) { // Delta must have been so small we dropped it during floating point addition. return 0.0; } // Check for overscroll: final double overscroll = physics.applyBoundaryConditions(this, newPixels); final double actualNewPixels = newPixels - overscroll; if (actualNewPixels != oldPixels) { forcePixels(actualNewPixels); didUpdateScrollPositionBy(actualNewPixels - oldPixels); } if (overscroll != 0.0) { didOverscrollBy(overscroll); return overscroll; } return 0.0; } // Returns the amount of delta that was not used. // // Negative delta represents a forward ScrollDirection, while the positive // would be a reverse ScrollDirection. // // The method doesn't take into account the effects of [ScrollPhysics]. double applyClampedPointerSignalUpdate(double delta) { assert(delta != 0.0); final double min = delta > 0.0 ? -double.infinity : math.min(minScrollExtent, pixels); // The logic for max is equivalent but on the other side. final double max = delta < 0.0 ? double.infinity : math.max(maxScrollExtent, pixels); final double newPixels = clampDouble(pixels + delta, min, max); final double clampedDelta = newPixels - pixels; if (clampedDelta == 0.0) { return delta; } forcePixels(newPixels); didUpdateScrollPositionBy(clampedDelta); return delta - clampedDelta; } @override ScrollDirection get userScrollDirection => coordinator.userScrollDirection; DrivenScrollActivity createDrivenScrollActivity(double to, Duration duration, Curve curve) { return DrivenScrollActivity( this, from: pixels, to: to, duration: duration, curve: curve, vsync: vsync, ); } @override double applyUserOffset(double delta) { assert(false); return 0.0; } // This is called by activities when they finish their work. @override void goIdle() { beginActivity(IdleScrollActivity(this)); coordinator.updateUserScrollDirection(ScrollDirection.idle); } // This is called by activities when they finish their work and want to go // ballistic. @override void goBallistic(double velocity) { Simulation? simulation; if (velocity != 0.0 || outOfRange) { simulation = physics.createBallisticSimulation(this, velocity); } beginActivity(createBallisticScrollActivity( simulation, mode: _NestedBallisticScrollActivityMode.independent, )); } // TODO(Piinks): see https://github.com/flutter/flutter/issues/100748 @override Simulation? updateBallisticAnimation(double initVelocity, double initPosition) { return null; } ScrollActivity createBallisticScrollActivity( Simulation? simulation, { required _NestedBallisticScrollActivityMode mode, _NestedScrollMetrics? metrics, }) { if (simulation == null) { return IdleScrollActivity(this); } assert(mode != null); switch (mode) { case _NestedBallisticScrollActivityMode.outer: assert(metrics != null); if (metrics!.minRange == metrics.maxRange) { return IdleScrollActivity(this); } return _NestedOuterBallisticScrollActivity( coordinator, this, metrics, simulation, context.vsync, activity?.shouldIgnorePointer ?? true, ); case _NestedBallisticScrollActivityMode.inner: return _NestedInnerBallisticScrollActivity( coordinator, this, simulation, context.vsync, activity?.shouldIgnorePointer ?? true, ); case _NestedBallisticScrollActivityMode.independent: return BallisticScrollActivity(this, simulation, context.vsync, activity?.shouldIgnorePointer ?? true); } } @override Future<void> animateTo( double to, { required Duration duration, required Curve curve, }) { return coordinator.animateTo( coordinator.unnestOffset(to, this), duration: duration, curve: curve, ); } @override void jumpTo(double value) { return coordinator.jumpTo(coordinator.unnestOffset(value, this)); } @override void pointerScroll(double delta) { return coordinator.pointerScroll(delta); } @override void jumpToWithoutSettling(double value) { assert(false); } void localJumpTo(double value) { if (pixels != value) { final double oldPixels = pixels; forcePixels(value); didStartScroll(); didUpdateScrollPositionBy(pixels - oldPixels); didEndScroll(); } } @override void applyNewDimensions() { super.applyNewDimensions(); coordinator.updateCanDrag(); } void updateCanDrag(double totalExtent) { context.setCanDrag(totalExtent > (viewportDimension - maxScrollExtent) || minScrollExtent != maxScrollExtent); } @override ScrollHoldController hold(VoidCallback holdCancelCallback) { return coordinator.hold(holdCancelCallback); } @override Drag drag(DragStartDetails details, VoidCallback dragCancelCallback) { return coordinator.drag(details, dragCancelCallback); } } enum _NestedBallisticScrollActivityMode { outer, inner, independent } class _NestedInnerBallisticScrollActivity extends BallisticScrollActivity { _NestedInnerBallisticScrollActivity( this.coordinator, _NestedScrollPosition position, Simulation simulation, TickerProvider vsync, bool shouldIgnorePointer, ) : super(position, simulation, vsync, shouldIgnorePointer); final _NestedScrollCoordinator coordinator; @override _NestedScrollPosition get delegate => super.delegate as _NestedScrollPosition; @override void resetActivity() { delegate.beginActivity(coordinator.createInnerBallisticScrollActivity( delegate, velocity, )); } @override void applyNewDimensions() { delegate.beginActivity(coordinator.createInnerBallisticScrollActivity( delegate, velocity, )); } @override bool applyMoveTo(double value) { return super.applyMoveTo(coordinator.nestOffset(value, delegate)); } } class _NestedOuterBallisticScrollActivity extends BallisticScrollActivity { _NestedOuterBallisticScrollActivity( this.coordinator, _NestedScrollPosition position, this.metrics, Simulation simulation, TickerProvider vsync, bool shouldIgnorePointer, ) : assert(metrics.minRange != metrics.maxRange), assert(metrics.maxRange > metrics.minRange), super(position, simulation, vsync, shouldIgnorePointer); final _NestedScrollCoordinator coordinator; final _NestedScrollMetrics metrics; @override _NestedScrollPosition get delegate => super.delegate as _NestedScrollPosition; @override void resetActivity() { delegate.beginActivity( coordinator.createOuterBallisticScrollActivity(velocity), ); } @override void applyNewDimensions() { delegate.beginActivity( coordinator.createOuterBallisticScrollActivity(velocity), ); } @override bool applyMoveTo(double value) { bool done = false; if (velocity > 0.0) { if (value < metrics.minRange) { return true; } if (value > metrics.maxRange) { value = metrics.maxRange; done = true; } } else if (velocity < 0.0) { if (value > metrics.maxRange) { return true; } if (value < metrics.minRange) { value = metrics.minRange; done = true; } } else { value = clampDouble(value, metrics.minRange, metrics.maxRange); done = true; } final bool result = super.applyMoveTo(value + metrics.correctionOffset); assert(result); // since we tried to pass an in-range value, it shouldn't ever overflow return !done; } @override String toString() { return '${objectRuntimeType(this, '_NestedOuterBallisticScrollActivity')}(${metrics.minRange} .. ${metrics.maxRange}; correcting by ${metrics.correctionOffset})'; } } /// Handle to provide to a [SliverOverlapAbsorber], a [SliverOverlapInjector], /// and an [NestedScrollViewViewport], to shift overlap in a [NestedScrollView]. /// /// A particular [SliverOverlapAbsorberHandle] can only be assigned to a single /// [SliverOverlapAbsorber] at a time. It can also be (and normally is) assigned /// to one or more [SliverOverlapInjector]s, which must be later descendants of /// the same [NestedScrollViewViewport] as the [SliverOverlapAbsorber]. The /// [SliverOverlapAbsorber] must be a direct descendant of the /// [NestedScrollViewViewport], taking part in the same sliver layout. (The /// [SliverOverlapInjector] can be a descendant that takes part in a nested /// scroll view's sliver layout.) /// /// Whenever the [NestedScrollViewViewport] is marked dirty for layout, it will /// cause its assigned [SliverOverlapAbsorberHandle] to fire notifications. It /// is the responsibility of the [SliverOverlapInjector]s (and any other /// clients) to mark themselves dirty when this happens, in case the geometry /// subsequently changes during layout. /// /// See also: /// /// * [NestedScrollView], which uses a [NestedScrollViewViewport] and a /// [SliverOverlapAbsorber] to align its children, and which shows sample /// usage for this class. class SliverOverlapAbsorberHandle extends ChangeNotifier { // Incremented when a RenderSliverOverlapAbsorber takes ownership of this // object, decremented when it releases it. This allows us to find cases where // the same handle is being passed to two render objects. int _writers = 0; /// The current amount of overlap being absorbed by the /// [SliverOverlapAbsorber]. /// /// This corresponds to the [SliverGeometry.layoutExtent] of the child of the /// [SliverOverlapAbsorber]. /// /// This is updated during the layout of the [SliverOverlapAbsorber]. It /// should not change at any other time. No notifications are sent when it /// changes; clients (e.g. [SliverOverlapInjector]s) are responsible for /// marking themselves dirty whenever this object sends notifications, which /// happens any time the [SliverOverlapAbsorber] might subsequently change the /// value during that layout. double? get layoutExtent => _layoutExtent; double? _layoutExtent; /// The total scroll extent of the gap being absorbed by the /// [SliverOverlapAbsorber]. /// /// This corresponds to the [SliverGeometry.scrollExtent] of the child of the /// [SliverOverlapAbsorber]. /// /// This is updated during the layout of the [SliverOverlapAbsorber]. It /// should not change at any other time. No notifications are sent when it /// changes; clients (e.g. [SliverOverlapInjector]s) are responsible for /// marking themselves dirty whenever this object sends notifications, which /// happens any time the [SliverOverlapAbsorber] might subsequently change the /// value during that layout. double? get scrollExtent => _scrollExtent; double? _scrollExtent; void _setExtents(double? layoutValue, double? scrollValue) { assert( _writers == 1, 'Multiple RenderSliverOverlapAbsorbers have been provided the same SliverOverlapAbsorberHandle.', ); _layoutExtent = layoutValue; _scrollExtent = scrollValue; } void _markNeedsLayout() => notifyListeners(); @override String toString() { String? extra; switch (_writers) { case 0: extra = ', orphan'; break; case 1: // normal case break; default: extra = ', $_writers WRITERS ASSIGNED'; break; } return '${objectRuntimeType(this, 'SliverOverlapAbsorberHandle')}($layoutExtent$extra)'; } } /// A sliver that wraps another, forcing its layout extent to be treated as /// overlap. /// /// The difference between the overlap requested by the child `sliver` and the /// overlap reported by this widget, called the _absorbed overlap_, is reported /// to the [SliverOverlapAbsorberHandle], which is typically passed to a /// [SliverOverlapInjector]. /// /// See also: /// /// * [NestedScrollView], whose documentation has sample code showing how to /// use this widget. class SliverOverlapAbsorber extends SingleChildRenderObjectWidget { /// Creates a sliver that absorbs overlap and reports it to a /// [SliverOverlapAbsorberHandle]. /// /// The [handle] must not be null. const SliverOverlapAbsorber({ super.key, required this.handle, Widget? sliver, }) : assert(handle != null), super(child: sliver); /// The object in which the absorbed overlap is recorded. /// /// A particular [SliverOverlapAbsorberHandle] can only be assigned to a /// single [SliverOverlapAbsorber] at a time. final SliverOverlapAbsorberHandle handle; @override RenderSliverOverlapAbsorber createRenderObject(BuildContext context) { return RenderSliverOverlapAbsorber( handle: handle, ); } @override void updateRenderObject(BuildContext context, RenderSliverOverlapAbsorber renderObject) { renderObject.handle = handle; } @override void debugFillProperties(DiagnosticPropertiesBuilder properties) { super.debugFillProperties(properties); properties.add(DiagnosticsProperty<SliverOverlapAbsorberHandle>('handle', handle)); } } /// A sliver that wraps another, forcing its layout extent to be treated as /// overlap. /// /// The difference between the overlap requested by the child `sliver` and the /// overlap reported by this widget, called the _absorbed overlap_, is reported /// to the [SliverOverlapAbsorberHandle], which is typically passed to a /// [RenderSliverOverlapInjector]. class RenderSliverOverlapAbsorber extends RenderSliver with RenderObjectWithChildMixin<RenderSliver> { /// Create a sliver that absorbs overlap and reports it to a /// [SliverOverlapAbsorberHandle]. /// /// The [handle] must not be null. /// /// The [sliver] must be a [RenderSliver]. RenderSliverOverlapAbsorber({ required SliverOverlapAbsorberHandle handle, RenderSliver? sliver, }) : assert(handle != null), _handle = handle { child = sliver; } /// The object in which the absorbed overlap is recorded. /// /// A particular [SliverOverlapAbsorberHandle] can only be assigned to a /// single [RenderSliverOverlapAbsorber] at a time. SliverOverlapAbsorberHandle get handle => _handle; SliverOverlapAbsorberHandle _handle; set handle(SliverOverlapAbsorberHandle value) { assert(value != null); if (handle == value) { return; } if (attached) { handle._writers -= 1; value._writers += 1; value._setExtents(handle.layoutExtent, handle.scrollExtent); } _handle = value; } @override void attach(PipelineOwner owner) { super.attach(owner); handle._writers += 1; } @override void detach() { handle._writers -= 1; super.detach(); } @override void performLayout() { assert( handle._writers == 1, 'A SliverOverlapAbsorberHandle cannot be passed to multiple RenderSliverOverlapAbsorber objects at the same time.', ); if (child == null) { geometry = SliverGeometry.zero; return; } child!.layout(constraints, parentUsesSize: true); final SliverGeometry childLayoutGeometry = child!.geometry!; geometry = SliverGeometry( scrollExtent: childLayoutGeometry.scrollExtent - childLayoutGeometry.maxScrollObstructionExtent, paintExtent: childLayoutGeometry.paintExtent, paintOrigin: childLayoutGeometry.paintOrigin, layoutExtent: math.max(0, childLayoutGeometry.paintExtent - childLayoutGeometry.maxScrollObstructionExtent), maxPaintExtent: childLayoutGeometry.maxPaintExtent, maxScrollObstructionExtent: childLayoutGeometry.maxScrollObstructionExtent, hitTestExtent: childLayoutGeometry.hitTestExtent, visible: childLayoutGeometry.visible, hasVisualOverflow: childLayoutGeometry.hasVisualOverflow, scrollOffsetCorrection: childLayoutGeometry.scrollOffsetCorrection, ); handle._setExtents( childLayoutGeometry.maxScrollObstructionExtent, childLayoutGeometry.maxScrollObstructionExtent, ); } @override void applyPaintTransform(RenderObject child, Matrix4 transform) { // child is always at our origin } @override bool hitTestChildren(SliverHitTestResult result, { required double mainAxisPosition, required double crossAxisPosition }) { if (child != null) { return child!.hitTest( result, mainAxisPosition: mainAxisPosition, crossAxisPosition: crossAxisPosition, ); } return false; } @override void paint(PaintingContext context, Offset offset) { if (child != null) { context.paintChild(child!, offset); } } @override void debugFillProperties(DiagnosticPropertiesBuilder properties) { super.debugFillProperties(properties); properties.add(DiagnosticsProperty<SliverOverlapAbsorberHandle>('handle', handle)); } } /// A sliver that has a sliver geometry based on the values stored in a /// [SliverOverlapAbsorberHandle]. /// /// The [SliverOverlapAbsorber] must be an earlier descendant of a common /// ancestor [Viewport], so that it will always be laid out before the /// [SliverOverlapInjector] during a particular frame. /// /// See also: /// /// * [NestedScrollView], which uses a [SliverOverlapAbsorber] to align its /// children, and which shows sample usage for this class. class SliverOverlapInjector extends SingleChildRenderObjectWidget { /// Creates a sliver that is as tall as the value of the given [handle]'s /// layout extent. /// /// The [handle] must not be null. const SliverOverlapInjector({ super.key, required this.handle, Widget? sliver, }) : assert(handle != null), super(child: sliver); /// The handle to the [SliverOverlapAbsorber] that is feeding this injector. /// /// This should be a handle owned by a [SliverOverlapAbsorber] and a /// [NestedScrollViewViewport]. final SliverOverlapAbsorberHandle handle; @override RenderSliverOverlapInjector createRenderObject(BuildContext context) { return RenderSliverOverlapInjector( handle: handle, ); } @override void updateRenderObject(BuildContext context, RenderSliverOverlapInjector renderObject) { renderObject.handle = handle; } @override void debugFillProperties(DiagnosticPropertiesBuilder properties) { super.debugFillProperties(properties); properties.add(DiagnosticsProperty<SliverOverlapAbsorberHandle>('handle', handle)); } } /// A sliver that has a sliver geometry based on the values stored in a /// [SliverOverlapAbsorberHandle]. /// /// The [RenderSliverOverlapAbsorber] must be an earlier descendant of a common /// ancestor [RenderViewport] (probably a [RenderNestedScrollViewViewport]), so /// that it will always be laid out before the [RenderSliverOverlapInjector] /// during a particular frame. class RenderSliverOverlapInjector extends RenderSliver { /// Creates a sliver that is as tall as the value of the given [handle]'s extent. /// /// The [handle] must not be null. RenderSliverOverlapInjector({ required SliverOverlapAbsorberHandle handle, }) : assert(handle != null), _handle = handle; double? _currentLayoutExtent; double? _currentMaxExtent; /// The object that specifies how wide to make the gap injected by this render /// object. /// /// This should be a handle owned by a [RenderSliverOverlapAbsorber] and a /// [RenderNestedScrollViewViewport]. SliverOverlapAbsorberHandle get handle => _handle; SliverOverlapAbsorberHandle _handle; set handle(SliverOverlapAbsorberHandle value) { assert(value != null); if (handle == value) { return; } if (attached) { handle.removeListener(markNeedsLayout); } _handle = value; if (attached) { handle.addListener(markNeedsLayout); if (handle.layoutExtent != _currentLayoutExtent || handle.scrollExtent != _currentMaxExtent) { markNeedsLayout(); } } } @override void attach(PipelineOwner owner) { super.attach(owner); handle.addListener(markNeedsLayout); if (handle.layoutExtent != _currentLayoutExtent || handle.scrollExtent != _currentMaxExtent) { markNeedsLayout(); } } @override void detach() { handle.removeListener(markNeedsLayout); super.detach(); } @override void performLayout() { _currentLayoutExtent = handle.layoutExtent; _currentMaxExtent = handle.layoutExtent; final double clampedLayoutExtent = math.min( _currentLayoutExtent! - constraints.scrollOffset, constraints.remainingPaintExtent, ); geometry = SliverGeometry( scrollExtent: _currentLayoutExtent!, paintExtent: math.max(0.0, clampedLayoutExtent), maxPaintExtent: _currentMaxExtent!, ); } @override void debugPaint(PaintingContext context, Offset offset) { assert(() { if (debugPaintSizeEnabled) { final Paint paint = Paint() ..color = const Color(0xFFCC9933) ..strokeWidth = 3.0 ..style = PaintingStyle.stroke; Offset start, end, delta; switch (constraints.axis) { case Axis.vertical: final double x = offset.dx + constraints.crossAxisExtent / 2.0; start = Offset(x, offset.dy); end = Offset(x, offset.dy + geometry!.paintExtent); delta = Offset(constraints.crossAxisExtent / 5.0, 0.0); break; case Axis.horizontal: final double y = offset.dy + constraints.crossAxisExtent / 2.0; start = Offset(offset.dx, y); end = Offset(offset.dy + geometry!.paintExtent, y); delta = Offset(0.0, constraints.crossAxisExtent / 5.0); break; } for (int index = -2; index <= 2; index += 1) { paintZigZag( context.canvas, paint, start - delta * index.toDouble(), end - delta * index.toDouble(), 10, 10.0, ); } } return true; }()); } @override void debugFillProperties(DiagnosticPropertiesBuilder properties) { super.debugFillProperties(properties); properties.add(DiagnosticsProperty<SliverOverlapAbsorberHandle>('handle', handle)); } } /// The [Viewport] variant used by [NestedScrollView]. /// /// This viewport takes a [SliverOverlapAbsorberHandle] and notifies it any time /// the viewport needs to recompute its layout (e.g. when it is scrolled). class NestedScrollViewViewport extends Viewport { /// Creates a variant of [Viewport] that has a [SliverOverlapAbsorberHandle]. /// /// The [handle] must not be null. NestedScrollViewViewport({ super.key, super.axisDirection, super.crossAxisDirection, super.anchor, required super.offset, super.center, super.slivers, required this.handle, super.clipBehavior, }) : assert(handle != null); /// The handle to the [SliverOverlapAbsorber] that is feeding this injector. final SliverOverlapAbsorberHandle handle; @override RenderNestedScrollViewViewport createRenderObject(BuildContext context) { return RenderNestedScrollViewViewport( axisDirection: axisDirection, crossAxisDirection: crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection( context, axisDirection, ), anchor: anchor, offset: offset, handle: handle, clipBehavior: clipBehavior, ); } @override void updateRenderObject(BuildContext context, RenderNestedScrollViewViewport renderObject) { renderObject ..axisDirection = axisDirection ..crossAxisDirection = crossAxisDirection ?? Viewport.getDefaultCrossAxisDirection( context, axisDirection, ) ..anchor = anchor ..offset = offset ..handle = handle ..clipBehavior = clipBehavior; } @override void debugFillProperties(DiagnosticPropertiesBuilder properties) { super.debugFillProperties(properties); properties.add(DiagnosticsProperty<SliverOverlapAbsorberHandle>('handle', handle)); } } /// The [RenderViewport] variant used by [NestedScrollView]. /// /// This viewport takes a [SliverOverlapAbsorberHandle] and notifies it any time /// the viewport needs to recompute its layout (e.g. when it is scrolled). class RenderNestedScrollViewViewport extends RenderViewport { /// Create a variant of [RenderViewport] that has a /// [SliverOverlapAbsorberHandle]. /// /// The [handle] must not be null. RenderNestedScrollViewViewport({ super.axisDirection, required super.crossAxisDirection, required super.offset, super.anchor, super.children, super.center, required SliverOverlapAbsorberHandle handle, super.clipBehavior, }) : assert(handle != null), _handle = handle; /// The object to notify when [markNeedsLayout] is called. SliverOverlapAbsorberHandle get handle => _handle; SliverOverlapAbsorberHandle _handle; /// Setting this will trigger notifications on the new object. set handle(SliverOverlapAbsorberHandle value) { assert(value != null); if (handle == value) { return; } _handle = value; handle._markNeedsLayout(); } @override void markNeedsLayout() { handle._markNeedsLayout(); super.markNeedsLayout(); } @override void debugFillProperties(DiagnosticPropertiesBuilder properties) { super.debugFillProperties(properties); properties.add(DiagnosticsProperty<SliverOverlapAbsorberHandle>('handle', handle)); } }