custom_text

Gestures are not available on the coloured strings in this example.

CustomText(
  'URL: https://example.com/\n'
  'Email: foo@example.com',
  definitions: const [
    TextDefinition(matcher: UrlMatcher()),
    TextDefinition(matcher: EmailMatcher()),
  ],
  matchStyle: const TextStyle(color: Colors.lightBlue),
)

Preset matchers

The matchers listed below are for general use. If a stricter pattern is necessary, overwrite the preset pattern or create a custom matcher.

• UrlMatcher for URLs
• UrlLikeMatcher for URL-like strings
• EmailMatcher for email addresses
• TelMatcher for phone numbers
• LinkMatcher for Markdown-style links or for other strings to be handled by SelectiveDefinition

All the three are styled, but only phone numbers among them are styled differently with the unique matchStyle and tapStyle.

CustomText(
  'URL: https://example.com/\n'
  'Email: foo@example.com\n'
  'Tel: +1-012-3456-7890',
  definitions: [
    const TextDefinition(matcher: UrlMatcher()),
    const TextDefinition(matcher: EmailMatcher()),
    TextDefinition(
      matcher: const TelMatcher(),
      // Styles and handlers specified in a definition take
      // precedence over the equivalent arguments of CustomText.
      matchStyle: const TextStyle(
        color: Colors.green,
        decoration: TextDecoration.underline,
      ),
      tapStyle: const TextStyle(color: Colors.orange),
      onTap: (details) => print(details.actionText),
      onLongPress: (details) => print('[Long press] ${details.actionText}'),
    ),
  ],
  matchStyle: const TextStyle(
    color: Colors.lightBlue,
    decoration: TextDecoration.underline,
  ),
  tapStyle: const TextStyle(color: Colors.indigo),
  onTap: (details) => print(details.actionText),
  onLongPress: (details) => print('[Long press] ${details.actionText}'),
)

[!TIP] To open a browser or another app when a string is tapped or long-pressed, use the url_launcher package or equivalent in the onTap and/or onLongPress handlers.

The new pattern here regards only the {3 digits}-{4 digits}-{4 digits} format as a phone number.

CustomText(
  'Tel: +1-012-3456-7890',
  definitions: const [
    TextDefinition(matcher: TelMatcher(r'\d{3}-\d{4}-\d{4}')),
  ],
  matchStyle: const TextStyle(color: Colors.lightBlue),
  onTap: (details) => print(details.actionText),
)

A hashtag has a wide variety of definitions, but here as an example, it is defined as a string that starts with "#" followed by an alphabet and then alphanumerics, and is enclosed with white spaces.

TextDefinition(
  matcher: PatternMatcher(r'(?<=\s|^)\#[a-zA-Z][a-zA-Z0-9]{1,}(?=\s|$)'),
),

Alternatively, you can define a matcher by extending TextMatcher. This allows you to distinguish the custom matcher from others by its unique type.

class HashTagMatcher extends TextMatcher {
  const HashTagMatcher()
      : super(r'(?<=\s|^)\#[a-zA-Z][a-zA-Z0-9]{1,}(?=\s|$)');
}

CustomText(
  'Hello world! #CustomText',
  definitions: const [
    TextDefinition(matcher: HashTagMatcher()),
  ],
  matchStyle: const TextStyle(color: Colors.lightBlue),
  onTap: (details) {
    if (details.element.matcherType == HashTagMatcher) {
      ...; 
    }
  },
)

SelectiveDefinition allows to select the string to display and the string to be passed to gesture callbacks individually.

The shownText and actionText functions receive a TextElement object containing various pieces of information provided by the parser. For its details, see the document of the text_parser package used internally in this package.

CustomText(
  'Tap [here](Tapped!)',
  definitions: [
    SelectiveDefinition(
      matcher: const LinkMatcher(),
      // `shownText` is used to choose the string to display.
      shownText: (element) => element.groups[0]!,
      // `actionText` is used to choose the string to be passed
      // to the `onTap`, `onLongPress` and `onGesture` handlers.
      actionText: (element) => element.groups[1]!,
    ),
  ],
  matchStyle: TextStyle(color: Colors.blue),
  hoverStyle: TextStyle(color: Colors.blue, decoration: TextDecoration.underline),
  onTap: (details) => print(details.actionText),
)

LinkMatcher is handy if used together with SelectiveDefinition, not only for making a text link but also for just decorating the bracketed strings (without showing the bracket symbols), in which case [strings]() is used as a marker to indicate which strings to be decorated.

// "def" and "jkl" are displayed in red.
CustomText(
  'abc[def]()ghi[jkl]()',
  definitions: [
    SelectiveDefinition(
      matcher: const LinkMatcher(),
      shownText: (element) => element.groups[0]!,
    ),
  ],
  matchStyle: const TextStyle(color: Colors.red),
)

SpanDefinition enables a certain portion of text to be replaced with an arbitrary InlineSpan. The builder function receives a TextElement object containing various pieces of information provided by the parser so that you can use it to flexibly build an InlineSpan.

Text styles, gesture handlers and the mouse cursor type are applied to the entire InlineSpan returned by the builder function. In this example, hovering is detected on all the children specified in the second SpanDefinition, i.e. the text in a TextSpan is decorated based on hoverStyle while the mouse pointer is hovering over the logo as well as over the text.

CustomText(
  'Hover and click  >>  [logo]Flutter',
  definitions: [
    SpanDefinition(
      matcher: const PatternMatcher('>>'),
      builder: (element) => const WidgetSpan(
        child: Icon(Icons.keyboard_double_arrow_right, ...),
      ),
    ),
    SpanDefinition(
      matcher: const PatternMatcher(r'\[logo\](\w+)'),
      builder: (element) => TextSpan(
        children: [
          const WidgetSpan(child: FlutterLogo()),
          const WidgetSpan(child: SizedBox(width: 2.0)),
          TextSpan(text: element.groups.first),
        ],
      ),
      matchStyle: TextStyle(color: Colors.blue),
      hoverStyle: TextStyle(color: Colors.blue, decoration: TextDecoration.underline),
      onTap: (details) => print(details.element.groups.first!),
    ),
  ],
)

CustomText(
  'Please visit [pub.dev](https://pub.dev/packages/custom_text) and ...',
  definitions: [
    SpanDefinition(
      matcher: const LinkMatcher(),
      builder: (element) {
        return WidgetSpan(
          baseline: TextBaseline.alphabetic,
          alignment: PlaceholderAlignment.baseline,
          child: Link(
            uri: Uri.parse(element.groups[1]!),
            target: LinkTarget.blank,
            builder: (context, openLink) {
              return GestureDetector(
                onTap: openLink,
                child: Text(element.groups[0]!),
              );
            },
          ),
        );
      },
      matchStyle: const TextStyle(color: Colors.blue),
      hoverStyle: const TextStyle(color: Colors.blue, decoration: TextDecoration.underline),
      mouseCursor: SystemMouseCursors.click,
    ),
  ],
)

This is easily possible by just passing your desired type to mouseCursor.

If a tap handler (onTap or onLongPress) is specified and mouseCursor is not, SystemMouseCursors.click is automatically used for the tappable region.

A different text style can also be applied on hover using hoverStyle either in CustomText or in a definition.

CustomText(
  'URL: https://example.com/\n'
  'Email: foo@example.com',
  definitions: [
    const TextDefinition(
      matcher: UrlMatcher(),
      matchStyle: TextStyle(
        color: Colors.grey,
        decoration: TextDecoration.lineThrough,
      ),
      // `SystemMouseCursors.forbidden` is used for URLs.
      mouseCursor: SystemMouseCursors.forbidden,
    ),
    TextDefinition(
      matcher: const EmailMatcher(),
      matchStyle: const TextStyle(
        color: Colors.lightBlue,
        decoration: TextDecoration.underline,
      ),
      tapStyle: const TextStyle(color: Colors.green),
      // Text is shadowed while the mouse pointer hovers over it.
      hoverStyle: TextStyle(
        color: Colors.lightBlue,
        shadows: ...,
      ),
      // `SystemMouseCursors.click` is automatically used for
      // tappable elements even if `mouseCursor` is not specified.
      onTap: (details) => print(details.actionText),
    ),
  ],
)

[!TIP] Use hoverStyle and omit tapStyle if you want the same style for tap and hover.

The onGesture handler is called on an event of a non-primary button or mouse gesture.

You can check the event type with gestureKind contained in the GestureDetails object which is passed to the handler function. The object also has the global and local positions where an event happened.

[!NOTE]

• onGesture does not handle events of the primary button. Use onTap and/or onLongPress instead.
• Unlike onTap and onLongPress, whether onGesture is specified does not affect text styling.
• The handler function is called one microsecond or more after the actual occurrence of an event.
  • This is due to a workaround for preventing the function from being called more times than expected by updates of the text span.

This constructor is useful if you already have styled spans and want to decorate them additionally.

In this example, the match pattern matches the range containing multiple InlineSpans including a WidgetSpan, and the specified styles and gestures are applied to that range.

CustomText.spans(
  style: const TextStyle(fontSize: 40.0),
  definitions: [
    TextDefinition(
      // WidgetSpan is matched by `\uFFFC` or `.` in a match pattern.
      matcher: const PatternMatcher('Flutter devs\uFFFC'),
      matchStyle: const TextStyle(color: Colors.blue),
      hoverStyle: TextStyle(color: Colors.blue.shade300),
      mouseCursor: SystemMouseCursors.forbidden,
      onGesture: (details) => output(details.gestureKind.name),
    ),
  ],
  spans: [
    const TextSpan(text: 'Hi, '),
    const TextSpan(
      text: 'Flutter',
      style: TextStyle(
        fontWeight: FontWeight.bold,
        shadows: [Shadow(blurRadius: 4.0, color: Colors.cyan)],
      ),
    ),
    const TextSpan(text: ' devs'),
    WidgetSpan(
      alignment: PlaceholderAlignment.middle,
      child: Builder(
        builder: (context) {
          // Text style is available also in WidgetSpan via DefaultTextStyle.
          final style = DefaultTextStyle.of(context).style;
          return Icon(
            Icons.flutter_dash,
            size: style.fontSize,
            color: style.color,
          );
        },
      ),
    ),
  ],
)

[!NOTE]

• Arguments other than text and style in the spans passed to spans are not used even if specified.

It has similar use cases to CustomText.spans, but is more helpful when it is not easy to compose complex spans manually.

The example below makes "KISS" and "Keep It Simple, Stupid!" bold, and then applies a colour to capital letters contained in them.

CustomText(
  'KISS is an acronym for "Keep It Simple, Stupid!".',
  definitions: const [
    TextDefinition(
      // This pattern is used for parsing the TextSpan built
      // by preBuilder, not for the original text.
      matcher: PatternMatcher('[A-Z]'),
      matchStyle: TextStyle(color: Colors.red),
    ),
  ],
  preBuilder: CustomSpanBuilder(
    definitions: [
      const TextDefinition(
        // This pattern is used for parsing the original text.
        matcher: PatternMatcher('KISS|Keep.+Stupid!'),
        matchStyle: TextStyle(fontWeight: FontWeight.bold),
      ),
    ],
  ),
)

[!NOTE]

• Parsing is performed first in the builder and then in CustomText itself. It is important to understand that the match patterns in the builder are used for the original text and the patterns in CustomText are used for the TextSpan built by the builder.
• Parsing and building of spans are avoided if not necessary, but still happen in two steps as written above when unavoidable. Be careful how much it affects the performance of your app.
• Gesture callbacks and mouseCursor in the builder are not used even if specified.

final controller = CustomTextEditingController(
  text: 'abcde foo@example.com\nhttps://example.com/ #hashtag',
  definitions: [
    const TextDefinition(
      matcher: HashTagMatcher(),
      matchStyle: TextStyle(color: Colors.orange),
      hoverStyle: TextStyle(color: Colors.red),
    ),
    ...
  ],
);

@override
Widget build(BuildContext context) {
  return TextField(
    controller: controller,
    ...,
  );
}

[!NOTE]

• CustomTextEditingController does not support SelectiveDefinition and SpanDefinition.
• An error is raised on iOS simulators (not on real devices) if the initial text and onTap, onLongPress or onGesture are specified.
  • See https://github.com/flutter/flutter/issues/97433.
• Debouncing of text parsing is available as an experimental feature for getting slightly better performance in handling long text.
  • Pass some duration to debounceDuration to enable the feature.
  • Use it at your own risk.
  • Text input will be still slow even with debouncing because Flutter itself has performance issues in editable text.

ParserOptions.external helps you when a different parser you already have does a better job or can do what is difficult with the default parser.

// These empty matchers are used to distinguish the matcher types of
// text elements parsed by an external parser.
// Each of the elements created by the parser needs to have the type
// of one of these matchers or `TextMatcher`. 
class KeywordMatcher extends TextMatcher {
  const KeywordMatcher() : super('');
}

class StringMatcher extends TextMatcher {
  const StringMatcher() : super('');
}

CustomText(
  sourceCode,
  parserOptions: ParserOptions.external(
    (text) => parseLanguage(text, language: 'dart'),
  ),
  definitions: [
    const TextDefinition(
      matcher: KeywordMatcher(),
      matchStyle: TextStyle(color: Colors.orange),
    ),
    const TextDefinition(
      matcher: StringMatcher(),
      matchStyle: TextStyle(color: Colors.teal),
    ),
    ...
  ],
);

[!NOTE]

• The external parser must generate a list of TextElements.
• If an existing external parser creates hierarchical nodes, they need to be flattened as this package only supports a flat list.
• If a custom parser is used with CustomTextEditingController, the TextElements generated by the parser must all together constitute the original text. Otherwise, it will cause unexpected behaviours.
  • This does not apply to CustomText.