[scrollable_positioned_list] Scroll offset controller (#474)

* Start scroll offset controller

* Add scroll offset controller test

* Add tests for stop scroll part way

* Add tests for stop offset scroll part way

* Clean up test and docs, add to examples

* Fix analysis errors

* Fix formatting

* Fix formatting

* Fix formatting

Author: tarobins

packages/scrollable_positioned_list/README.md

@@ -15,13 +15,15 @@ A `ScrollablePositionedList` can be created with:
 
 ```dart
 final ItemScrollController itemScrollController = ItemScrollController();
+final ScrollOffsetController scrollOffsetController = ScrollOffsetController();
 final ItemPositionsListener itemPositionsListener = ItemPositionsListener.create();
 final ScrollOffsetListener scrollOffsetListener = ScrollOffsetListener.create()
 
 ScrollablePositionedList.builder(
   itemCount: 500,
   itemBuilder: (context, index) => Text('Item $index'),
   itemScrollController: itemScrollController,
+  scrollOffsetController: scrollOffsetController,
   itemPositionsListener: itemPositionsListener,
   scrollOffsetListener: scrollOffsetListener,
 );
@@ -48,6 +50,8 @@ One can monitor what items are visible on screen with:
 itemPositionsListener.itemPositions.addListener(() => ...);
 ```
 
+### Experimental APIs (subject to bugs and changes)
+
 Changes in scroll position can be monitored with:
 
 ```dart
@@ -57,6 +61,12 @@ scrollOffsetListener.changes.listen((event) => ...)
 see `ScrollSum` in [this test](test/scroll_offset_listener_test.dart) for an example of how the current offset can be 
 calculated from the stream of scroll change deltas.  This feature is new and experimental.
 
+Changes in scroll position in pixels, relative to the current scroll position, can be made with:
+
+```dart
+scrollOffsetController.animateScroll(offset: 100, duration: Duration(seconds: 1));
+```
+
 A full example can be found in the example folder.
 
 --------------------------------------------------------------------------------

packages/scrollable_positioned_list/example/lib/main.dart

@@ -55,6 +55,11 @@ class _ScrollablePositionedListPageState
   /// Controller to scroll or jump to a particular item.
   final ItemScrollController itemScrollController = ItemScrollController();
 
+  /// Controller to scroll a certain number of pixels relative to the current
+  /// scroll offset.
+  final ScrollOffsetController scrollOffsetController =
+      ScrollOffsetController();
+
   /// Listener that reports the position of items when the list is scrolled.
   final ItemPositionsListener itemPositionsListener =
       ItemPositionsListener.create();
@@ -89,10 +94,12 @@ class _ScrollablePositionedListPageState
               ),
               positionsView,
               Row(
+                mainAxisSize: MainAxisSize.min,
                 children: <Widget>[
                   Column(
                     children: <Widget>[
                       scrollControlButtons,
+                      scrollOffsetControlButtons,
                       const SizedBox(height: 10),
                       jumpControlButtons,
                       alignmentControl,
@@ -130,6 +137,7 @@ class _ScrollablePositionedListPageState
         itemBuilder: (context, index) => item(index, orientation),
         itemScrollController: itemScrollController,
         itemPositionsListener: itemPositionsListener,
+        scrollOffsetController: scrollOffsetController,
         reverse: reversed,
         scrollDirection: orientation == Orientation.portrait
             ? Axis.vertical
@@ -181,12 +189,24 @@ class _ScrollablePositionedListPageState
   Widget get scrollControlButtons => Row(
         children: <Widget>[
           const Text('scroll to'),
-          scrollButton(0),
-          scrollButton(5),
-          scrollButton(10),
-          scrollButton(100),
-          scrollButton(1000),
-          scrollButton(5000),
+          scrollItemButton(0),
+          scrollItemButton(5),
+          scrollItemButton(10),
+          scrollItemButton(100),
+          scrollItemButton(1000),
+          scrollItemButton(5000),
+        ],
+      );
+
+  Widget get scrollOffsetControlButtons => Row(
+        children: <Widget>[
+          const Text('scroll by'),
+          scrollOffsetButton(-1000),
+          scrollOffsetButton(-100),
+          scrollOffsetButton(-10),
+          scrollOffsetButton(10),
+          scrollOffsetButton(100),
+          scrollOffsetButton(1000),
         ],
       );
 
@@ -202,26 +222,41 @@ class _ScrollablePositionedListPageState
         ],
       );
 
-  final _scrollButtonStyle = ButtonStyle(
-    padding: MaterialStateProperty.all(
-      const EdgeInsets.symmetric(horizontal: 20, vertical: 0),
-    ),
-    minimumSize: MaterialStateProperty.all(Size.zero),
-    tapTargetSize: MaterialTapTargetSize.shrinkWrap,
-  );
+  ButtonStyle _scrollButtonStyle({required double horizonalPadding}) =>
+      ButtonStyle(
+        padding: MaterialStateProperty.all(
+          EdgeInsets.symmetric(horizontal: horizonalPadding, vertical: 0),
+        ),
+        minimumSize: MaterialStateProperty.all(Size.zero),
+        tapTargetSize: MaterialTapTargetSize.shrinkWrap,
+      );
 
-  Widget scrollButton(int value) => TextButton(
+  Widget scrollItemButton(int value) => TextButton(
         key: ValueKey<String>('Scroll$value'),
         onPressed: () => scrollTo(value),
         child: Text('$value'),
-        style: _scrollButtonStyle,
+        style: _scrollButtonStyle(horizonalPadding: 20),
+      );
+
+  Widget scrollOffsetButton(int value) => TextButton(
+        key: ValueKey<String>('Scroll$value'),
+        onPressed: () => scrollBy(value.toDouble()),
+        child: Text('$value'),
+        style: _scrollButtonStyle(horizonalPadding: 10),
+      );
+
+  Widget scrollPixelButton(int value) => TextButton(
+        key: ValueKey<String>('Scroll$value'),
+        onPressed: () => scrollTo(value),
+        child: Text('$value'),
+        style: _scrollButtonStyle(horizonalPadding: 20),
       );
 
   Widget jumpButton(int value) => TextButton(
         key: ValueKey<String>('Jump$value'),
         onPressed: () => jumpTo(value),
         child: Text('$value'),
-        style: _scrollButtonStyle,
+        style: _scrollButtonStyle(horizonalPadding: 20),
       );
 
   void scrollTo(int index) => itemScrollController.scrollTo(
@@ -230,6 +265,9 @@ class _ScrollablePositionedListPageState
       curve: Curves.easeInOutCubic,
       alignment: alignment);
 
+  void scrollBy(double offset) => scrollOffsetController.animateScroll(
+      offset: offset, duration: scrollDuration, curve: Curves.easeInOutCubic);
+
   void jumpTo(int index) =>
       itemScrollController.jumpTo(index: index, alignment: alignment);
 

packages/scrollable_positioned_list/lib/src/scroll_offset_listener.dart

@@ -3,6 +3,9 @@ import 'dart:async';
 import 'scroll_offset_notifier.dart';
 
 /// Provides an affordance for listening to scroll offset changes.
+///
+/// This is an experimental API and is subject to change.
+/// Behavior may be ill-defined in some cases.  Please file bugs.
 abstract class ScrollOffsetListener {
   /// Stream of scroll offset deltas.
   Stream<double> get changes;

packages/scrollable_positioned_list/lib/src/scrollable_positioned_list.dart

@@ -8,12 +8,11 @@ import 'dart:math';
 import 'package:collection/collection.dart' show IterableExtension;
 import 'package:flutter/scheduler.dart';
 import 'package:flutter/widgets.dart';
+import 'package:scrollable_positioned_list/scrollable_positioned_list.dart';
 
-import 'item_positions_listener.dart';
 import 'item_positions_notifier.dart';
 import 'positioned_list.dart';
 import 'post_mount_callback.dart';
-import 'scroll_offset_listener.dart';
 import 'scroll_offset_notifier.dart';
 
 /// Number of screens to scroll when scrolling a long distance.
@@ -45,6 +44,7 @@ class ScrollablePositionedList extends StatefulWidget {
     this.itemScrollController,
     this.shrinkWrap = false,
     ItemPositionsListener? itemPositionsListener,
+    this.scrollOffsetController,
     ScrollOffsetListener? scrollOffsetListener,
     this.initialScrollIndex = 0,
     this.initialAlignment = 0,
@@ -74,6 +74,7 @@ class ScrollablePositionedList extends StatefulWidget {
     this.shrinkWrap = false,
     this.itemScrollController,
     ItemPositionsListener? itemPositionsListener,
+    this.scrollOffsetController,
     ScrollOffsetListener? scrollOffsetListener,
     this.initialScrollIndex = 0,
     this.initialAlignment = 0,
@@ -110,6 +111,8 @@ class ScrollablePositionedList extends StatefulWidget {
   /// Notifier that reports the items laid out in the list after each frame.
   final ItemPositionsNotifier? itemPositionsNotifier;
 
+  final ScrollOffsetController? scrollOffsetController;
+
   /// Notifier that reports the changes to the scroll offset.
   final ScrollOffsetNotifier? scrollOffsetNotifier;
 
@@ -267,6 +270,41 @@ class ItemScrollController {
   }
 }
 
+/// Controller to scroll a certain number of pixels relative to the current
+/// scroll offset.
+///
+/// Scrolls [offset] pixels relative to the current scroll offset. [offset] can
+/// be positive or negative.
+///
+/// This is an experimental API and is subject to change.
+/// Behavior may be ill-defined in some cases.  Please file bugs.
+class ScrollOffsetController {
+  Future<void> animateScroll(
+      {required double offset,
+      required Duration duration,
+      Curve curve = Curves.linear}) async {
+    final currentPosition =
+        _scrollableListState!.primary.scrollController.offset;
+    final newPosition = currentPosition + offset;
+    await _scrollableListState!.primary.scrollController.animateTo(
+      newPosition,
+      duration: duration,
+      curve: curve,
+    );
+  }
+
+  _ScrollablePositionedListState? _scrollableListState;
+
+  void _attach(_ScrollablePositionedListState scrollableListState) {
+    assert(_scrollableListState == null);
+    _scrollableListState = scrollableListState;
+  }
+
+  void _detach() {
+    _scrollableListState = null;
+  }
+}
+
 class _ScrollablePositionedListState extends State<ScrollablePositionedList>
     with TickerProviderStateMixin {
   /// Details for the primary (active) [ListView].
@@ -297,6 +335,7 @@ class _ScrollablePositionedListState extends State<ScrollablePositionedList>
       primary.target = widget.itemCount - 1;
     }
     widget.itemScrollController?._attach(this);
+    widget.scrollOffsetController?._attach(this);
     primary.itemPositionsNotifier.itemPositions.addListener(_updatePositions);
     secondary.itemPositionsNotifier.itemPositions.addListener(_updatePositions);
     primary.scrollController.addListener(() {
@@ -310,9 +349,17 @@ class _ScrollablePositionedListState extends State<ScrollablePositionedList>
     });
   }
 
+  @override
+  void activate() {
+    super.activate();
+    widget.itemScrollController?._attach(this);
+    widget.scrollOffsetController?._attach(this);
+  }
+
   @override
   void deactivate() {
     widget.itemScrollController?._detach();
+    widget.scrollOffsetController?._detach();
     super.deactivate();
   }