a11y: implement new SemanticsAction "showOnScreen" (v2)

This action is triggered when the user swipes (in accessibility mode) to the last visible item of a scrollable list to bring that item fully on screen.

This requires engine rolled to flutter/engine#3856.

I am in the process of adding tests, but I'd like to get early feedback to see if this approach is OK.

Author: goderbauer

packages/flutter/lib/src/rendering/object.dart

@@ -739,7 +739,8 @@ class _RootSemanticsFragment extends _InterestingSemanticsFragment {
     assert(parentSemantics == null);
     renderObjectOwner._semantics ??= new SemanticsNode.root(
       handler: renderObjectOwner is SemanticsActionHandler ? renderObjectOwner as dynamic : null,
-      owner: renderObjectOwner.owner.semanticsOwner
+      owner: renderObjectOwner.owner.semanticsOwner,
+      showOnScreen: renderObjectOwner.showOnScreen,
     );
     final SemanticsNode node = renderObjectOwner._semantics;
     assert(MatrixUtils.matrixEquals(node.transform, new Matrix4.identity()));
@@ -768,7 +769,8 @@ class _ConcreteSemanticsFragment extends _InterestingSemanticsFragment {
   @override
   SemanticsNode establishSemanticsNode(_SemanticsGeometry geometry, SemanticsNode currentSemantics, SemanticsNode parentSemantics) {
     renderObjectOwner._semantics ??= new SemanticsNode(
-      handler: renderObjectOwner is SemanticsActionHandler ? renderObjectOwner as dynamic : null
+      handler: renderObjectOwner is SemanticsActionHandler ? renderObjectOwner as dynamic : null,
+      showOnScreen: renderObjectOwner.showOnScreen,
     );
     final SemanticsNode node = renderObjectOwner._semantics;
     if (geometry != null) {
@@ -812,7 +814,8 @@ class _ImplicitSemanticsFragment extends _InterestingSemanticsFragment {
     _haveConcreteNode = currentSemantics == null && annotator != null;
     if (haveConcreteNode) {
       renderObjectOwner._semantics ??= new SemanticsNode(
-        handler: renderObjectOwner is SemanticsActionHandler ? renderObjectOwner as dynamic : null
+        handler: renderObjectOwner is SemanticsActionHandler ? renderObjectOwner as dynamic : null,
+        showOnScreen: renderObjectOwner.showOnScreen,
       );
       node = renderObjectOwner._semantics;
     } else {
@@ -2777,6 +2780,17 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   @protected
   String debugDescribeChildren(String prefix) => '';
 
+
+  /// Attempt to make this or a descendant RenderObject visible on screen.
+  ///
+  /// If [child] is provided, that RenderObject is made visible. If [child] is
+  /// omitted, this RenderObject is made visible.
+  void showOnScreen([RenderObject child]) {
+    if (parent is RenderObject) {
+      final RenderObject renderParent = parent;
+      renderParent.showOnScreen(child ?? this);
+    }
+  }
 }
 
 /// Generic mixin for render objects with one child.

packages/flutter/lib/src/rendering/semantics.dart

@@ -143,17 +143,21 @@ class SemanticsNode extends AbstractNode {
   /// Each semantic node has a unique identifier that is assigned when the node
   /// is created.
   SemanticsNode({
-    SemanticsActionHandler handler
+    SemanticsActionHandler handler,
+    VoidCallback showOnScreen,
   }) : id = _generateNewId(),
+       _showOnScreen = showOnScreen,
        _actionHandler = handler;
 
   /// Creates a semantic node to represent the root of the semantics tree.
   ///
   /// The root node is assigned an identifier of zero.
   SemanticsNode.root({
     SemanticsActionHandler handler,
-    SemanticsOwner owner
+    VoidCallback showOnScreen,
+    SemanticsOwner owner,
   }) : id = 0,
+        _showOnScreen = showOnScreen,
        _actionHandler = handler {
     attach(owner);
   }
@@ -171,6 +175,7 @@ class SemanticsNode extends AbstractNode {
   final int id;
 
   final SemanticsActionHandler _actionHandler;
+  final VoidCallback _showOnScreen;
 
   // GEOMETRY
   // These are automatically handled by RenderObject's own logic
@@ -735,6 +740,11 @@ class SemanticsOwner extends ChangeNotifier {
     assert(action != null);
     final SemanticsActionHandler handler = _getSemanticsActionHandlerForId(id, action);
     handler?.performAction(action);
+
+    // Default actions if no [handler] was provided.
+    if (handler == null && action == SemanticsAction.showOnScreen && _nodes[id]._showOnScreen != null) {
+      _nodes[id]._showOnScreen();
+    }
   }
 
   SemanticsActionHandler _getSemanticsActionHandlerForPosition(SemanticsNode node, Offset position, SemanticsAction action) {

packages/flutter/lib/src/rendering/viewport.dart

@@ -591,6 +591,22 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
   /// This should be the reverse order of [childrenInPaintOrder].
   @protected
   Iterable<RenderSliver> get childrenInHitTestOrder;
+
+  @override
+  void showOnScreen([RenderObject child]) {
+    // Move viewport the smallest distance to bring [child] on screen.
+    final double leadingEdgeOffset = getOffsetToReveal(child, 0.0);
+    final double trailingEdgeOffset = getOffsetToReveal(child, 1.0);
+    final double currentOffset = offset.pixels;
+    if ((currentOffset - leadingEdgeOffset).abs() < (currentOffset - trailingEdgeOffset).abs()) {
+      offset.jumpTo(leadingEdgeOffset);
+    } else {
+      offset.jumpTo(trailingEdgeOffset);
+    }
+
+    // Make sure the viewport itself is on screen.
+    super.showOnScreen();
+  }
 }
 
 /// A render object that is bigger on the inside.

packages/flutter/lib/src/rendering/viewport_offset.dart

@@ -152,6 +152,10 @@ abstract class ViewportOffset extends ChangeNotifier {
   /// being called again, though this should be very rare.
   void correctBy(double correction);
 
+  /// Jumps the scroll position from its current value to the given value,
+  /// without animation, and without checking if the new value is in range.
+  void jumpTo(double pixels);
+
   /// The direction in which the user is trying to change [pixels], relative to
   /// the viewport's [RenderViewport.axisDirection].
   ///
@@ -208,6 +212,11 @@ class _FixedViewportOffset extends ViewportOffset {
     _pixels += correction;
   }
 
+  @override
+  void jumpTo(double pixels) {
+    _pixels = pixels;
+  }
+
   @override
   ScrollDirection get userScrollDirection => ScrollDirection.idle;
 }

packages/flutter/lib/src/widgets/scroll_position.dart

@@ -510,6 +510,7 @@ abstract class ScrollPosition extends ViewportOffset with ScrollMetrics {
   /// If this method changes the scroll position, a sequence of start/update/end
   /// scroll notifications will be dispatched. No overscroll notifications can
   /// be generated by this method.
+  @override
   void jumpTo(double value);
 
   /// Deprecated. Use [jumpTo] or a custom [ScrollPosition] instead.

packages/flutter/lib/src/widgets/single_child_scroll_view.dart

@@ -418,4 +418,20 @@ class _RenderSingleChildViewport extends RenderBox with RenderObjectWithChildMix
 
     return leadingScrollOffset - (mainAxisExtent - targetMainAxisExtent) * alignment;
   }
+
+  @override
+  void showOnScreen([RenderObject child]) {
+    // Move viewport the smallest distance to bring [child] on screen.
+    final double leadingEdgeOffset = getOffsetToReveal(child, 0.0);
+    final double trailingEdgeOffset = getOffsetToReveal(child, 1.0);
+    final double currentOffset = offset.pixels;
+    if ((currentOffset - leadingEdgeOffset).abs() < (currentOffset - trailingEdgeOffset).abs()) {
+      offset.jumpTo(leadingEdgeOffset);
+    } else {
+      offset.jumpTo(trailingEdgeOffset);
+    }
+
+    // Make sure the viewport itself is on screen.
+    super.showOnScreen();
+  }
 }