tapOnText method

Future<void> tapOnText(
  1. FinderBase<TextRangeContext> textRangeFinder, {
  2. int? pointer,
  3. int buttons = kPrimaryButton,
})

Dispatch a pointer down / pointer up sequence at a hit-testable InlineSpan (typically a TextSpan) within the given text range.

This method performs a more spatially precise tap action on a piece of static text, than the widget-based tap method.

The given Finder must find one and only one matching substring, and the substring must be hit-testable (meaning, it must not be off-screen, or be obscured by other widgets, or in a disabled widget). Otherwise this method throws a FlutterError.

If the target substring contains more than one hit-testable InlineSpans, tapOnText taps on one of them, but does not guarantee which.

The pointer and button arguments specify PointerEvent.pointer and PointerEvent.buttons of the tap event.

Implementation

Future<void> tapOnText(finders.FinderBase<finders.TextRangeContext> textRangeFinder, {int? pointer, int buttons = kPrimaryButton }) {
  final Iterable<finders.TextRangeContext> ranges = textRangeFinder.evaluate();
  if (ranges.isEmpty) {
    throw FlutterError(textRangeFinder.toString());
  }
  if (ranges.length > 1) {
    throw FlutterError(
      '$textRangeFinder. The "tapOnText" method needs a single non-empty TextRange.',
    );
  }
  final Offset? tapLocation = _findHitTestableOffsetIn(ranges.single);
  if (tapLocation == null) {
    final finders.TextRangeContext found = textRangeFinder.evaluate().single;
    throw FlutterError.fromParts(<DiagnosticsNode>[
        ErrorSummary('Finder specifies a TextRange that can not receive pointer events.'),
        ErrorDescription('The finder used was: ${textRangeFinder.toString(describeSelf: true)}'),
        ErrorDescription('Found a matching substring in a static text widget, within ${found.textRange}.'),
        ErrorDescription('But the "tapOnText" method could not find a hit-testable Offset with in that text range.'),
        found.renderObject.toDiagnosticsNode(name: 'The RenderBox of that static text widget was', style: DiagnosticsTreeStyle.shallow),
      ]
    );
  }
  return tapAt(tapLocation, pointer: pointer, buttons: buttons);
}