library;

import 'dart:async';

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 'package:flutter/services.dart';

import 'basic.dart';

import 'framework.dart';

import 'gesture_detector.dart';

import 'media_query.dart';

import 'notification_listener.dart';

import 'restoration.dart';

import 'restoration_properties.dart';

import 'scroll_activity.dart';

import 'scroll_configuration.dart';

import 'scroll_context.dart';

import 'scroll_controller.dart';

import 'scroll_physics.dart';

import 'scroll_position.dart';

import 'scrollable_helpers.dart';

import 'selectable_region.dart';

import 'selection_container.dart';

import 'ticker_provider.dart';

import 'view.dart';

import 'viewport.dart';

export 'package:flutter/physics.dart' show Tolerance;

typedef ViewportBuilder = Widget Function(BuildContext context, ViewportOffset position);

typedef TwoDimensionalViewportBuilder = Widget Function(

BuildContext context,

ViewportOffset verticalPosition,

ViewportOffset horizontalPosition,

);

typedef _EnsureVisibleResults = (List<Future<void>>, ScrollableState);

class Scrollable extends StatefulWidget {

/// Creates a widget that scrolls.

const Scrollable({

super.key,

this.axisDirection = AxisDirection.down,

this.controller,

this.physics,

required this.viewportBuilder,

this.incrementCalculator,

this.excludeFromSemantics = false,

this.semanticChildCount,

this.dragStartBehavior = DragStartBehavior.start,

this.restorationId,

this.scrollBehavior,

this.clipBehavior = Clip.hardEdge,

this.hitTestBehavior = HitTestBehavior.opaque,

}) : assert(semanticChildCount == null || semanticChildCount >= 0);

/// {@template flutter.widgets.Scrollable.axisDirection}

final AxisDirection axisDirection;

/// {@template flutter.widgets.Scrollable.controller}

final ScrollController? controller;

/// {@template flutter.widgets.Scrollable.physics}

final ScrollPhysics? physics;

/// Builds the viewport through which the scrollable content is displayed.

final ViewportBuilder viewportBuilder;

/// {@template flutter.widgets.Scrollable.incrementCalculator}

final ScrollIncrementCalculator? incrementCalculator;

/// {@template flutter.widgets.scrollable.excludeFromSemantics}

final bool excludeFromSemantics;

/// {@template flutter.widgets.scrollable.hitTestBehavior}

final HitTestBehavior hitTestBehavior;

/// The number of children that will contribute semantic information.

final int? semanticChildCount;

// TODO(jslavitz): Set the DragStartBehavior default to be start across all widgets.

/// {@template flutter.widgets.scrollable.dragStartBehavior}

final DragStartBehavior dragStartBehavior;

/// {@template flutter.widgets.scrollable.restorationId}

final String? restorationId;

/// {@template flutter.widgets.scrollable.scrollBehavior}

final ScrollBehavior? scrollBehavior;

/// {@macro flutter.material.Material.clipBehavior}

final Clip clipBehavior;

/// The axis along which the scroll view scrolls.

Axis get axis => axisDirectionToAxis(axisDirection);

@override

ScrollableState createState() => ScrollableState();

@override

void debugFillProperties(DiagnosticPropertiesBuilder properties) {

super.debugFillProperties(properties);

properties.add(EnumProperty<AxisDirection>('axisDirection', axisDirection));

properties.add(DiagnosticsProperty<ScrollPhysics>('physics', physics));

properties.add(StringProperty('restorationId', restorationId));

}

/// The state from the closest instance of this class that encloses the given

static ScrollableState? maybeOf(BuildContext context, {Axis? axis}) {

// This is the context that will need to establish the dependency.

final originalContext = context;

InheritedElement? element = context.getElementForInheritedWidgetOfExactType<_ScrollableScope>();

while (element != null) {

final ScrollableState scrollable = (element.widget as _ScrollableScope).scrollable;

if (axis == null || axisDirectionToAxis(scrollable.axisDirection) == axis) {

// Establish the dependency on the correct context.

originalContext.dependOnInheritedElement(element);

return scrollable;

}

context = scrollable.context;

element = context.getElementForInheritedWidgetOfExactType<_ScrollableScope>();

}

return null;

}

/// The state from the closest instance of this class that encloses the given

static ScrollableState of(BuildContext context, {Axis? axis}) {

final ScrollableState? scrollableState = maybeOf(context, axis: axis);

assert(() {

if (scrollableState == null) {

throw FlutterError.fromParts(<DiagnosticsNode>[

ErrorSummary(

'Scrollable.of() was called with a context that does not contain a '

'Scrollable widget.',

),

ErrorDescription(

'No Scrollable widget ancestor could be found '

'${axis == null ? '' : 'for the provided Axis: $axis '}'

'starting from the context that was passed to Scrollable.of(). This '

'can happen because you are using a widget that looks for a Scrollable '

'ancestor, but no such ancestor exists.\n'

'The context used was:\n'

' $context',

),

if (axis != null)

ErrorHint(

'When specifying an axis, this method will only look for a Scrollable '

'that matches the given Axis.',

),

]);

}

return true;

}());

return scrollableState!;

}

/// Provides a heuristic to determine if expensive frame-bound tasks should be

static bool recommendDeferredLoadingForContext(BuildContext context, {Axis? axis}) {

_ScrollableScope? widget = context.getInheritedWidgetOfExactType<_ScrollableScope>();

while (widget != null) {

if (axis == null || axisDirectionToAxis(widget.scrollable.axisDirection) == axis) {

return widget.position.recommendDeferredLoading(context);

}

context = widget.scrollable.context;

widget = context.getInheritedWidgetOfExactType<_ScrollableScope>();

}

return false;

}

/// Scrolls all scrollables that enclose the given context so as to make the

@awaitNotRequired

static Future<void> ensureVisible(

BuildContext context, {

double alignment = 0.0,

Duration duration = Duration.zero,

Curve curve = Curves.ease,

ScrollPositionAlignmentPolicy alignmentPolicy = ScrollPositionAlignmentPolicy.explicit,

}) {

final futures = <Future<void>>[];

// The targetRenderObject is used to record the first target renderObject.

// If there are multiple scrollable widgets nested, the targetRenderObject

// is made to be as visible as possible to improve the user experience. If

// the targetRenderObject is already visible, then let the outer

// renderObject be as visible as possible.

//

// Also see https://github.com/flutter/flutter/issues/65100

RenderObject? targetRenderObject;

ScrollableState? scrollable = Scrollable.maybeOf(context);

while (scrollable != null) {

final List<Future<void>> newFutures;

(newFutures, scrollable) = scrollable._performEnsureVisible(

context.findRenderObject()!,

alignment: alignment,

duration: duration,

curve: curve,

alignmentPolicy: alignmentPolicy,

targetRenderObject: targetRenderObject,

);

futures.addAll(newFutures);

targetRenderObject ??= context.findRenderObject();

context = scrollable.context;

scrollable = Scrollable.maybeOf(context);

}

if (futures.isEmpty || duration == Duration.zero) {

return Future<void>.value();

}

if (futures.length == 1) {

return futures.single;

}

return Future.wait<void>(futures).then<void>((List<void> _) => null);

}

}

class _ScrollableScope extends InheritedWidget {

const _ScrollableScope({required this.scrollable, required this.position, required super.child});

final ScrollableState scrollable;

final ScrollPosition position;

@override

bool updateShouldNotify(_ScrollableScope old) {

return position != old.position;

}

}

class ScrollableState extends State<Scrollable>

with TickerProviderStateMixin, RestorationMixin

implements ScrollContext {

// GETTERS

/// The manager for this [Scrollable] widget's viewport position.

ScrollPosition get position => _position!;

ScrollPosition? _position;

/// The resolved [ScrollPhysics] of the [ScrollableState].

ScrollPhysics? get resolvedPhysics => _physics;

ScrollPhysics? _physics;

/// An [Offset] that represents the absolute distance from the origin, or 0,

Offset get deltaToScrollOrigin => switch (axisDirection) {

AxisDirection.up => Offset(0, -position.pixels),

AxisDirection.down => Offset(0, position.pixels),

AxisDirection.left => Offset(-position.pixels, 0),

AxisDirection.right => Offset(position.pixels, 0),

};

ScrollController get _effectiveScrollController =>

widget.controller ?? _fallbackScrollController!;

@override

AxisDirection get axisDirection => widget.axisDirection;

@override

TickerProvider get vsync => this;

@override

double get devicePixelRatio => _devicePixelRatio;

late double _devicePixelRatio;

@override

BuildContext? get notificationContext => _gestureDetectorKey.currentContext;

@override

BuildContext get storageContext => context;

@override

String? get restorationId => widget.restorationId;

final _RestorableScrollOffset _persistedScrollOffset = _RestorableScrollOffset();

late ScrollBehavior _configuration;

ScrollController? _fallbackScrollController;

DeviceGestureSettings? _mediaQueryGestureSettings;

// Only call this from places that will definitely trigger a rebuild.

void _updatePosition() {

_configuration = widget.scrollBehavior ?? ScrollConfiguration.of(context);

final ScrollPhysics? physicsFromWidget =

widget.physics ?? widget.scrollBehavior?.getScrollPhysics(context);

_physics = _configuration.getScrollPhysics(context);

_physics = physicsFromWidget?.applyTo(_physics) ?? _physics;

final ScrollPosition? oldPosition = _position;

if (oldPosition != null) {

_effectiveScrollController.detach(oldPosition);

// It's important that we not dispose the old position until after the

// viewport has had a chance to unregister its listeners from the old

// position. So, schedule a microtask to do it.

scheduleMicrotask(oldPosition.dispose);

}

_position = _effectiveScrollController.createScrollPosition(_physics!, this, oldPosition);

assert(_position != null);

_effectiveScrollController.attach(position);

}

@protected

@override

void restoreState(RestorationBucket? oldBucket, bool initialRestore) {

registerForRestoration(_persistedScrollOffset, 'offset');

assert(_position != null);

if (_persistedScrollOffset.value != null) {

position.restoreOffset(_persistedScrollOffset.value!, initialRestore: initialRestore);

}

}

@protected

@override

void saveOffset(double offset) {

assert(debugIsSerializableForRestoration(offset));

_persistedScrollOffset.value = offset;

// [saveOffset] is called after a scrolling ends and it is usually not

// followed by a frame. Therefore, manually flush restoration data.

ServicesBinding.instance.restorationManager.flushData();

}

@protected

@override

void initState() {

if (widget.controller == null) {

_fallbackScrollController = ScrollController();

}

super.initState();

}

@protected

@override

void didChangeDependencies() {

_mediaQueryGestureSettings = MediaQuery.maybeGestureSettingsOf(context);

_devicePixelRatio =

MediaQuery.maybeDevicePixelRatioOf(context) ?? View.of(context).devicePixelRatio;

_updatePosition();

super.didChangeDependencies();

}

bool _shouldUpdatePosition(Scrollable oldWidget) {

if ((widget.scrollBehavior == null) != (oldWidget.scrollBehavior == null)) {

return true;

}

if (widget.scrollBehavior != null &&

oldWidget.scrollBehavior != null &&

widget.scrollBehavior!.shouldNotify(oldWidget.scrollBehavior!)) {

return true;

}

final ScrollPhysics? newPhysics =

widget.physics ?? widget.scrollBehavior?.getScrollPhysics(context);

final ScrollPhysics? oldPhysics =

oldWidget.physics ?? oldWidget.scrollBehavior?.getScrollPhysics(context);

if (newPhysics?.runtimeType != oldPhysics?.runtimeType) {

return true;

}

if (newPhysics != null && oldPhysics != null && newPhysics.shouldUpdate(oldPhysics)) {

return true;

}

return widget.controller?.runtimeType != oldWidget.controller?.runtimeType;

}

@protected

@override

void didUpdateWidget(Scrollable oldWidget) {

super.didUpdateWidget(oldWidget);

if (widget.controller != oldWidget.controller) {

if (oldWidget.controller == null) {

// The old controller was null, meaning the fallback cannot be null.

// Dispose of the fallback.

assert(_fallbackScrollController != null);

assert(widget.controller != null);

_fallbackScrollController!.detach(position);

_fallbackScrollController!.dispose();

_fallbackScrollController = null;

} else {

// The old controller was not null, detach.

oldWidget.controller?.detach(position);

if (widget.controller == null) {

// If the new controller is null, we need to set up the fallback

// ScrollController.

_fallbackScrollController = ScrollController();

}

}

// Attach the updated effective scroll controller.

_effectiveScrollController.attach(position);

}

if (_shouldUpdatePosition(oldWidget)) {

_updatePosition();

}

}

@protected

@override

void dispose() {

if (widget.controller != null) {

widget.controller!.detach(position);

} else {

_fallbackScrollController?.detach(position);

_fallbackScrollController?.dispose();

}

position.dispose();

_persistedScrollOffset.dispose();

super.dispose();

}

// SEMANTICS

final GlobalKey _scrollSemanticsKey = GlobalKey();

@override

@protected

void setSemanticsActions(Set<SemanticsAction> actions) {

if (_gestureDetectorKey.currentState != null) {

_gestureDetectorKey.currentState!.replaceSemanticsActions(actions);

}

}

// GESTURE RECOGNITION AND POINTER IGNORING

final GlobalKey<RawGestureDetectorState> _gestureDetectorKey =

GlobalKey<RawGestureDetectorState>();

final GlobalKey _ignorePointerKey = GlobalKey();

// This field is set during layout, and then reused until the next time it is set.

Map<Type, GestureRecognizerFactory> _gestureRecognizers =

const <Type, GestureRecognizerFactory>{};

bool _shouldIgnorePointer = false;

bool? _lastCanDrag;

Axis? _lastAxisDirection;

@override

@protected

void setCanDrag(bool value) {

if (value == _lastCanDrag && (!value || widget.axis == _lastAxisDirection)) {

return;

}

if (!value) {

_gestureRecognizers = const <Type, GestureRecognizerFactory>{};

// Cancel the active hold/drag (if any) because the gesture recognizers

// will soon be disposed by our RawGestureDetector, and we won't be

// receiving pointer up events to cancel the hold/drag.

_handleDragCancel();

} else {

switch (widget.axis) {

case Axis.vertical:

_gestureRecognizers = <Type, GestureRecognizerFactory>{

VerticalDragGestureRecognizer:

GestureRecognizerFactoryWithHandlers<VerticalDragGestureRecognizer>(

() => VerticalDragGestureRecognizer(supportedDevices: _configuration.dragDevices),

(VerticalDragGestureRecognizer instance) {

instance

..onDown = _handleDragDown

..onStart = _handleDragStart

..onUpdate = _handleDragUpdate

..onEnd = _handleDragEnd

..onCancel = _handleDragCancel

..minFlingDistance = _physics?.minFlingDistance

..minFlingVelocity = _physics?.minFlingVelocity

..maxFlingVelocity = _physics?.maxFlingVelocity

..velocityTrackerBuilder = _configuration.velocityTrackerBuilder(context)

..dragStartBehavior = widget.dragStartBehavior

..multitouchDragStrategy = _configuration.getMultitouchDragStrategy(context)

..gestureSettings = _mediaQueryGestureSettings

..supportedDevices = _configuration.dragDevices;

},

),

};

case Axis.horizontal:

_gestureRecognizers = <Type, GestureRecognizerFactory>{

HorizontalDragGestureRecognizer:

GestureRecognizerFactoryWithHandlers<HorizontalDragGestureRecognizer>(

() =>

HorizontalDragGestureRecognizer(supportedDevices: _configuration.dragDevices),

(HorizontalDragGestureRecognizer instance) {

instance

..onDown = _handleDragDown

..onStart = _handleDragStart

..onUpdate = _handleDragUpdate

..onEnd = _handleDragEnd

..onCancel = _handleDragCancel

..minFlingDistance = _physics?.minFlingDistance

..minFlingVelocity = _physics?.minFlingVelocity

..maxFlingVelocity = _physics?.maxFlingVelocity

..velocityTrackerBuilder = _configuration.velocityTrackerBuilder(context)

..dragStartBehavior = widget.dragStartBehavior

..multitouchDragStrategy = _configuration.getMultitouchDragStrategy(context)

..gestureSettings = _mediaQueryGestureSettings

..supportedDevices = _configuration.dragDevices;

},

),

};

}

}

_lastCanDrag = value;

_lastAxisDirection = widget.axis;

if (_gestureDetectorKey.currentState != null) {

_gestureDetectorKey.currentState!.replaceGestureRecognizers(_gestureRecognizers);

}

}

@override

@protected

void setIgnorePointer(bool value) {

if (_shouldIgnorePointer == value) {

return;

}

_shouldIgnorePointer = value;

if (_ignorePointerKey.currentContext != null) {

final renderBox =

_ignorePointerKey.currentContext!.findRenderObject()! as RenderIgnorePointer;

renderBox.ignoring = _shouldIgnorePointer;

}

}

// TOUCH HANDLERS

Drag? _drag;

ScrollHoldController? _hold;

void _handleDragDown(DragDownDetails details) {

assert(_drag == null);

assert(_hold == null);

_hold = position.hold(_disposeHold);

}

void _handleDragStart(DragStartDetails details) {

// It's possible for _hold to become null between _handleDragDown and

// _handleDragStart, for example if some user code calls jumpTo or otherwise

// triggers a new activity to begin.

assert(_drag == null);

_drag = position.drag(details, _disposeDrag);

assert(_drag != null);

// _hold might be non-null if the scroll position is currently animating.

if (_hold != null) {

_disposeHold();

}

}

void _handleDragUpdate(DragUpdateDetails details) {

// _drag might be null if the drag activity ended and called _disposeDrag.

assert(_hold == null || _drag == null);

_drag?.update(details);

}

void _handleDragEnd(DragEndDetails details) {

// _drag might be null if the drag activity ended and called _disposeDrag.

assert(_hold == null || _drag == null);

_drag?.end(details);

assert(_drag == null);

}

void _handleDragCancel() {

if (_gestureDetectorKey.currentContext == null) {

// The cancel was caused by the GestureDetector getting disposed, which

// means we will get disposed momentarily as well and shouldn't do

// any work.

return;

}

// _hold might be null if the drag started.

// _drag might be null if the drag activity ended and called _disposeDrag.

assert(_hold == null || _drag == null);

_hold?.cancel();

_drag?.cancel();

assert(_hold == null);

assert(_drag == null);

}

void _disposeHold() {

_hold = null;

}

void _disposeDrag() {

_drag = null;

}

// SCROLL WHEEL

// Returns the offset that should result from applying [event] to the current

// position, taking min/max scroll extent into account.

double _targetScrollOffsetForPointerScroll(double delta) {

return math.min(

math.max(position.pixels + delta, position.minScrollExtent),

position.maxScrollExtent,

);

}

// Returns the delta that should result from applying [event] with axis,

// direction, and any modifiers specified by the ScrollBehavior taken into

// account.

double _pointerSignalEventDelta(PointerScrollEvent event) {

final Set<LogicalKeyboardKey> pressed = HardwareKeyboard.instance.logicalKeysPressed;

final bool flipAxes =

pressed.any(_configuration.pointerAxisModifiers.contains) &&

// Axes are only flipped for physical mouse wheel input.

// On some platforms, like web, trackpad input is handled through pointer

// signals, but should not be included in this axis modifying behavior.

// This is because on a trackpad, all directional axes are available to

// the user, while mouse scroll wheels typically are restricted to one

// axis.

event.kind == PointerDeviceKind.mouse;

final Axis axis = flipAxes ? flipAxis(widget.axis) : widget.axis;

final double delta = switch (axis) {

Axis.horizontal => event.scrollDelta.dx,

Axis.vertical => event.scrollDelta.dy,

};

return axisDirectionIsReversed(widget.axisDirection) ? -delta : delta;

}

void _receivedPointerSignal(PointerSignalEvent event) {

if (event is PointerScrollEvent && _position != null) {

if (_physics != null && !_physics!.shouldAcceptUserOffset(position)) {

return;

}

final double delta = _pointerSignalEventDelta(event);

final double targetScrollOffset = _targetScrollOffsetForPointerScroll(delta);

// Only express interest in the event if it would actually result in a scroll.

if (delta != 0.0 && targetScrollOffset != position.pixels) {

GestureBinding.instance.pointerSignalResolver.register(event, _handlePointerScroll);

return;

}

} else if (event is PointerScrollInertiaCancelEvent) {

position.pointerScroll(0);

// Don't use the pointer signal resolver, all hit-tested scrollables should stop.

}

}

void _handlePointerScroll(PointerEvent event) {

assert(event is PointerScrollEvent);

final scrollEvent = event as PointerScrollEvent;

final double delta = _pointerSignalEventDelta(scrollEvent);

final double targetScrollOffset = _targetScrollOffsetForPointerScroll(delta);

if (delta != 0.0 && targetScrollOffset != position.pixels) {

position.pointerScroll(delta);

// Tell engine this scrollable handled the event.

// This prevents parent page from scrolling when nested scrollables exist.

scrollEvent.respond(allowPlatformDefault: false);

}

}

bool _handleScrollMetricsNotification(ScrollMetricsNotification notification) {

if (notification.depth == 0) {

final RenderObject? scrollSemanticsRenderObject = _scrollSemanticsKey.currentContext

?.findRenderObject();

if (scrollSemanticsRenderObject != null) {

scrollSemanticsRenderObject.markNeedsSemanticsUpdate();

}

}

return false;

}

Widget _buildChrome(BuildContext context, Widget child) {

final details = ScrollableDetails(

direction: widget.axisDirection,

controller: _effectiveScrollController,