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);
}