Add option for custom actions to Semantics widget (#12695)

* Add option for custom actions to Semantics widget

* review comments

* review comment

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

@@ -4456,6 +4456,14 @@ class Semantics extends SingleChildRenderObjectWidget {
     this.value,
     this.hint,
     this.textDirection,
+    this.onTap,
+    this.onLongPress,
+    this.onScrollLeft,
+    this.onScrollRight,
+    this.onScrollUp,
+    this.onScrollDown,
+    this.onIncrease,
+    this.onDecrease,
   }) : assert(container != null),
        super(key: key, child: child);
 
@@ -4540,6 +4548,98 @@ class Semantics extends SingleChildRenderObjectWidget {
     return textDirection ?? (label != null || value != null || hint != null ? Directionality.of(context) : null);
   }
 
+  /// The handler for [SemanticsAction.tap].
+  ///
+  /// This is the semantic equivalent of a user briefly tapping the screen with
+  /// the finger without moving it. For example, a button should implement this
+  /// action.
+  ///
+  /// VoiceOver users on iOS and TalkBack users on Android can trigger this
+  /// action by double-tapping the screen while an element is focused.
+  final VoidCallback onTap;
+
+  /// The handler for [SemanticsAction.longPress].
+  ///
+  /// This is the semantic equivalent of a user pressing and holding the screen
+  /// with the finger for a few seconds without moving it.
+  ///
+  /// VoiceOver users on iOS and TalkBack users on Android can trigger this
+  /// action by double-tapping the screen without lifting the finger after the
+  /// second tap.
+  final VoidCallback onLongPress;
+
+  /// The handler for [SemanticsAction.scrollLeft].
+  ///
+  /// This is the semantic equivalent of a user moving their finger across the
+  /// screen from right to left. It should be recognized by controls that are
+  /// horizontally scrollable.
+  ///
+  /// VoiceOver users on iOS can trigger this action by swiping left with three
+  /// fingers. TalkBack users on Android can trigger this action by swiping
+  /// right and then left in one motion path. On Android, [onScrollUp] and
+  /// [onScrollLeft] share the same gesture. Therefore, only on of them should
+  /// be provided.
+  final VoidCallback onScrollLeft;
+
+  /// The handler for [SemanticsAction.scrollRight].
+  ///
+  /// This is the semantic equivalent of a user moving their finger across the
+  /// screen from left to right. It should be recognized by controls that are
+  /// horizontally scrollable.
+  ///
+  /// VoiceOver users on iOS can trigger this action by swiping right with three
+  /// fingers. TalkBack users on Android can trigger this action by swiping
+  /// left and then right in one motion path.  On Android, [onScrollDown] and
+  /// [onScrollRight] share the same gesture. Therefore, only on of them should
+  /// be provided.
+  final VoidCallback onScrollRight;
+
+  /// The handler for [SemanticsAction.scrollUp].
+  ///
+  /// This is the semantic equivalent of a user moving their finger across the
+  /// screen from bottom to top. It should be recognized by controls that are
+  /// vertically scrollable.
+  ///
+  /// VoiceOver users on iOS can trigger this action by swiping up with three
+  /// fingers. TalkBack users on Android can trigger this action by swiping
+  /// right and then left in one motion path. On Android, [onScrollUp] and
+  /// [onScrollLeft] share the same gesture. Therefore, only on of them should
+  /// be provided.
+  final VoidCallback onScrollUp;
+
+  /// The handler for [SemanticsAction.scrollDown].
+  ///
+  /// This is the semantic equivalent of a user moving their finger across the
+  /// screen from top to bottom. It should be recognized by controls that are
+  /// vertically scrollable.
+  ///
+  /// VoiceOver users on iOS can trigger this action by swiping down with three
+  /// fingers. TalkBack users on Android can trigger this action by swiping
+  /// left and then right in one motion path. On Android, [onScrollDown] and
+  /// [onScrollRight] share the same gesture. Therefore, only on of them should
+  /// be provided.
+  final VoidCallback onScrollDown;
+
+  /// The handler for [SemanticsAction.increase].
+  ///
+  /// This is a request to increase the value represented by the widget. For
+  /// example, this action might be recognized by a slider control.
+  ///
+  /// VoiceOver users on iOS can trigger this action by swiping up with one
+  /// finger. TalkBack users on Android can trigger this action by pressing the
+  /// volume up button.
+  final VoidCallback onIncrease;
+
+  /// The handler for [SemanticsAction.decrease].
+  ///
+  /// This is a request to decrease the value represented by the widget. For
+  /// example, this action might be recognized by a slider control.
+  ///
+  /// VoiceOver users on iOS can trigger this action by swiping down with one
+  /// finger. TalkBack users on Android can trigger this action by pressing the
+  /// volume down button.
+  final VoidCallback onDecrease;
+
   @override
   RenderSemanticsAnnotations createRenderObject(BuildContext context) {
     return new RenderSemanticsAnnotations(
@@ -4552,6 +4652,14 @@ class Semantics extends SingleChildRenderObjectWidget {
       value: value,
       hint: hint,
       textDirection: _getTextDirection(context),
+      onTap: onTap,
+      onLongPress: onLongPress,
+      onScrollLeft: onScrollLeft,
+      onScrollRight: onScrollRight,
+      onScrollUp: onScrollUp,
+      onScrollDown: onScrollDown,
+      onIncrease: onIncrease,
+      onDecrease: onDecrease,
     );
   }
 
@@ -4565,7 +4673,15 @@ class Semantics extends SingleChildRenderObjectWidget {
       ..label = label
       ..value = value
       ..hint = hint
-      ..textDirection = _getTextDirection(context);
+      ..textDirection = _getTextDirection(context)
+      ..onTap = onTap
+      ..onLongPress = onLongPress
+      ..onScrollLeft = onScrollLeft
+      ..onScrollRight = onScrollRight
+      ..onScrollUp = onScrollUp
+      ..onScrollDown = onScrollDown
+      ..onIncrease = onIncrease
+      ..onDecrease = onDecrease;
   }
 
   @override

packages/flutter/test/widgets/semantics_test.dart

@@ -370,4 +370,147 @@ void main() {
 
     expect(semantics, hasSemantics(expectedSemantics, ignoreTransform: true, ignoreRect: true, ignoreId: true));
   });
+
+  testWidgets('Semantics widget supports all actions', (WidgetTester tester) async {
+    final SemanticsTester semantics = new SemanticsTester(tester);
+
+    final List<SemanticsAction> performedActions = <SemanticsAction>[];
+
+    await tester.pumpWidget(
+      new Semantics(
+        container: true,
+        onTap: () => performedActions.add(SemanticsAction.tap),
+        onLongPress: () => performedActions.add(SemanticsAction.longPress),
+        onScrollLeft: () => performedActions.add(SemanticsAction.scrollLeft),
+        onScrollRight: () => performedActions.add(SemanticsAction.scrollRight),
+        onScrollUp: () => performedActions.add(SemanticsAction.scrollUp),
+        onScrollDown: () => performedActions.add(SemanticsAction.scrollDown),
+        onIncrease: () => performedActions.add(SemanticsAction.increase),
+        onDecrease: () => performedActions.add(SemanticsAction.decrease),
+      )
+    );
+
+    final Set<SemanticsAction> allActions = SemanticsAction.values.values.toSet()
+      ..remove(SemanticsAction.showOnScreen); // showOnScreen is non user-exposed.
+
+    final int expectedId = 32;
+    final TestSemantics expectedSemantics = new TestSemantics.root(
+      children: <TestSemantics>[
+        new TestSemantics.rootChild(
+          id: expectedId,
+          rect: TestSemantics.fullScreen,
+          actions: allActions.fold(0, (int previous, SemanticsAction action) => previous | action.index)
+        ),
+      ],
+    );
+    expect(semantics, hasSemantics(expectedSemantics));
+
+    // Do the actions work?
+    final SemanticsOwner semanticsOwner = tester.binding.pipelineOwner.semanticsOwner;
+    int expectedLength = 1;
+    for (SemanticsAction action in allActions) {
+      semanticsOwner.performAction(expectedId, action);
+      expect(performedActions.length, expectedLength);
+      expect(performedActions.last, action);
+      expectedLength += 1;
+    }
+
+    semantics.dispose();
+  });
+
+  testWidgets('Actions can be replaced without triggering semantics update', (WidgetTester tester) async {
+    final SemanticsTester semantics = new SemanticsTester(tester);
+    int semanticsUpdateCount = 0;
+    tester.binding.pipelineOwner.ensureSemantics(
+      listener: () {
+        semanticsUpdateCount += 1;
+      }
+    );
+
+    final List<String> performedActions = <String>[];
+
+    await tester.pumpWidget(
+      new Semantics(
+        container: true,
+        onTap: () => performedActions.add('first'),
+      ),
+    );
+
+    final int expectedId = 35;
+    final TestSemantics expectedSemantics = new TestSemantics.root(
+      children: <TestSemantics>[
+        new TestSemantics.rootChild(
+          id: expectedId,
+          rect: TestSemantics.fullScreen,
+          actions: SemanticsAction.tap.index,
+        ),
+      ],
+    );
+
+    final SemanticsOwner semanticsOwner = tester.binding.pipelineOwner.semanticsOwner;
+
+    expect(semantics, hasSemantics(expectedSemantics));
+    semanticsOwner.performAction(expectedId, SemanticsAction.tap);
+    expect(semanticsUpdateCount, 1);
+    expect(performedActions, <String>['first']);
+
+    semanticsUpdateCount = 0;
+    performedActions.clear();
+
+    // Updating existing handler should not trigger semantics update
+    await tester.pumpWidget(
+      new Semantics(
+        container: true,
+        onTap: () => performedActions.add('second'),
+      ),
+    );
+
+    expect(semantics, hasSemantics(expectedSemantics));
+    semanticsOwner.performAction(expectedId, SemanticsAction.tap);
+    expect(semanticsUpdateCount, 0);
+    expect(performedActions, <String>['second']);
+
+    semanticsUpdateCount = 0;
+    performedActions.clear();
+
+    // Adding a handler works
+    await tester.pumpWidget(
+      new Semantics(
+        container: true,
+        onTap: () => performedActions.add('second'),
+        onLongPress: () => performedActions.add('longPress'),
+      ),
+    );
+
+    final TestSemantics expectedSemanticsWithLongPress = new TestSemantics.root(
+      children: <TestSemantics>[
+        new TestSemantics.rootChild(
+          id: expectedId,
+          rect: TestSemantics.fullScreen,
+          actions: SemanticsAction.tap.index | SemanticsAction.longPress.index,
+        ),
+      ],
+    );
+
+    expect(semantics, hasSemantics(expectedSemanticsWithLongPress));
+    semanticsOwner.performAction(expectedId, SemanticsAction.longPress);
+    expect(semanticsUpdateCount, 1);
+    expect(performedActions, <String>['longPress']);
+
+    semanticsUpdateCount = 0;
+    performedActions.clear();
+
+    // Removing a handler works
+    await tester.pumpWidget(
+      new Semantics(
+        container: true,
+        onTap: () => performedActions.add('second'),
+      ),
+    );
+
+    expect(semantics, hasSemantics(expectedSemantics));
+    expect(semanticsUpdateCount, 1);
+
+    semantics.dispose();
+  });
 }