packages/flutter/lib/src/painting/text_span.dart - external/github.com/flutter/flutter - Git at Google

 // Copyright 2014 The Flutter Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 import 'dart:ui' as ui show ParagraphBuilder, Locale, StringAttribute, LocaleStringAttribute, SpellOutStringAttribute;

 import 'package:flutter/foundation.dart';
 import 'package:flutter/gestures.dart';
 import 'package:flutter/services.dart';

 import 'basic_types.dart';
 import 'inline_span.dart';
 import 'text_painter.dart';
 import 'text_style.dart';

 /// An immutable span of text.
 ///
 /// A [TextSpan] object can be styled using its [style] property. The style will
 /// be applied to the [text] and the [children].
 ///
 /// A [TextSpan] object can just have plain text, or it can have children
 /// [TextSpan] objects with their own styles that (possibly only partially)
 /// override the [style] of this object. If a [TextSpan] has both [text] and
 /// [children], then the [text] is treated as if it was an un-styled [TextSpan]
 /// at the start of the [children] list. Leaving the [TextSpan.text] field null
 /// results in the [TextSpan] acting as an empty node in the [InlineSpan] tree
 /// with a list of children.
 ///
 /// To paint a [TextSpan] on a [Canvas], use a [TextPainter]. To display a text
 /// span in a widget, use a [RichText]. For text with a single style, consider
 /// using the [Text] widget.
 ///
 /// {@tool snippet}
 ///
 /// The text "Hello world!", in black:
 ///
 /// ```dart
 /// const TextSpan(
 ///   text: 'Hello world!',
 ///   style: TextStyle(color: Colors.black),
 /// )
 /// ```
 /// {@end-tool}
 ///
 /// _There is some more detailed sample code in the documentation for the
 /// [recognizer] property._
 ///
 /// The [TextSpan.text] will be used as the semantics label unless overridden
 /// by the [TextSpan.semanticsLabel] property. Any [PlaceholderSpan]s in the
 /// [TextSpan.children] list will separate the text before and after it into two
 /// semantics nodes.
 ///
 /// See also:
 ///
 ///  * [WidgetSpan], a leaf node that represents an embedded inline widget in an
 ///    [InlineSpan] tree. Specify a widget within the [children] list by
 ///    wrapping the widget with a [WidgetSpan]. The widget will be laid out
 ///    inline within the paragraph.
 ///  * [Text], a widget for showing uniformly-styled text.
 ///  * [RichText], a widget for finer control of text rendering.
 ///  * [TextPainter], a class for painting [TextSpan] objects on a [Canvas].
 @immutable
 class TextSpan extends InlineSpan implements HitTestTarget, MouseTrackerAnnotation {
   /// Creates a [TextSpan] with the given values.
   ///
   /// For the object to be useful, at least one of [text] or
   /// [children] should be set.
   const TextSpan({
     this.text,
     this.children,
     TextStyle? style,
     this.recognizer,
     MouseCursor? mouseCursor,
     this.onEnter,
     this.onExit,
     this.semanticsLabel,
     this.locale,
     this.spellOut,
   }) : mouseCursor = mouseCursor ??
          (recognizer == null ? MouseCursor.defer : SystemMouseCursors.click),
        assert(!(text == null && semanticsLabel != null)),
        super(style: style);

   /// The text contained in this span.
   ///
   /// If both [text] and [children] are non-null, the text will precede the
   /// children.
   ///
   /// This getter does not include the contents of its children.
   final String? text;

   /// Additional spans to include as children.
   ///
   /// If both [text] and [children] are non-null, the text will precede the
   /// children.
   ///
   /// Modifying the list after the [TextSpan] has been created is not supported
   /// and may have unexpected results.
   ///
   /// The list must not contain any nulls.
   final List<InlineSpan>? children;

   /// A gesture recognizer that will receive events that hit this span.
   ///
   /// [InlineSpan] itself does not implement hit testing or event dispatch. The
   /// object that manages the [InlineSpan] painting is also responsible for
   /// dispatching events. In the rendering library, that is the
   /// [RenderParagraph] object, which corresponds to the [RichText] widget in
   /// the widgets layer; these objects do not bubble events in [InlineSpan]s,
   /// so a [recognizer] is only effective for events that directly hit the
   /// [text] of that [InlineSpan], not any of its [children].
   ///
   /// [InlineSpan] also does not manage the lifetime of the gesture recognizer.
   /// The code that owns the [GestureRecognizer] object must call
   /// [GestureRecognizer.dispose] when the [InlineSpan] object is no longer
   /// used.
   ///
   /// {@tool snippet}
   ///
   /// This example shows how to manage the lifetime of a gesture recognizer
   /// provided to an [InlineSpan] object. It defines a `BuzzingText` widget
   /// which uses the [HapticFeedback] class to vibrate the device when the user
   /// long-presses the "find the" span, which is underlined in wavy green. The
   /// hit-testing is handled by the [RichText] widget. It also changes the
   /// hovering mouse cursor to `precise`.
   ///
   /// ```dart
   /// class BuzzingText extends StatefulWidget {
   ///   const BuzzingText({Key? key}) : super(key: key);
   ///
   ///   @override
   ///   State<BuzzingText> createState() => _BuzzingTextState();
   /// }
   ///
   /// class _BuzzingTextState extends State<BuzzingText> {
   ///   late LongPressGestureRecognizer _longPressRecognizer;
   ///
   ///   @override
   ///   void initState() {
   ///     super.initState();
   ///     _longPressRecognizer = LongPressGestureRecognizer()
   ///       ..onLongPress = _handlePress;
   ///   }
   ///
   ///   @override
   ///   void dispose() {
   ///     _longPressRecognizer.dispose();
   ///     super.dispose();
   ///   }
   ///
   ///   void _handlePress() {
   ///     HapticFeedback.vibrate();
   ///   }
   ///
   ///   @override
   ///   Widget build(BuildContext context) {
   ///     return Text.rich(
   ///       TextSpan(
   ///         text: 'Can you ',
   ///         style: const TextStyle(color: Colors.black),
   ///         children: <InlineSpan>[
   ///           TextSpan(
   ///             text: 'find the',
   ///             style: const TextStyle(
   ///               color: Colors.green,
   ///               decoration: TextDecoration.underline,
   ///               decorationStyle: TextDecorationStyle.wavy,
   ///             ),
   ///             recognizer: _longPressRecognizer,
   ///             mouseCursor: SystemMouseCursors.precise,
   ///           ),
   ///           const TextSpan(
   ///             text: ' secret?',
   ///           ),
   ///         ],
   ///       ),
   ///     );
   ///   }
   /// }
   /// ```
   /// {@end-tool}
   final GestureRecognizer? recognizer;

   /// Mouse cursor when the mouse hovers over this span.
   ///
   /// The default value is [SystemMouseCursors.click] if [recognizer] is not
   /// null, or [MouseCursor.defer] otherwise.
   ///
   /// [TextSpan] itself does not implement hit testing or cursor changing.
   /// The object that manages the [TextSpan] painting is responsible
   /// to return the [TextSpan] in its hit test, as well as providing the
   /// correct mouse cursor when the [TextSpan]'s mouse cursor is
   /// [MouseCursor.defer].
   final MouseCursor mouseCursor;

   @override
   final PointerEnterEventListener? onEnter;

   @override
   final PointerExitEventListener? onExit;

   /// Returns the value of [mouseCursor].
   ///
   /// This field, required by [MouseTrackerAnnotation], is hidden publicly to
   /// avoid the confusion as a text cursor.
   @protected
   @override
   MouseCursor get cursor => mouseCursor;

   /// An alternative semantics label for this [TextSpan].
   ///
   /// If present, the semantics of this span will contain this value instead
   /// of the actual text.
   ///
   /// This is useful for replacing abbreviations or shorthands with the full
   /// text value:
   ///
   /// ```dart
   /// TextSpan(text: r'$$', semanticsLabel: 'Double dollars')
   /// ```
   final String? semanticsLabel;

   /// The language of the text in this span and its span children.
   ///
   /// Setting the locale of this text span affects the way that assistive
   /// technologies, such as VoiceOver or TalkBack, pronounce the text.
   ///
   /// If this span contains other text span children, they also inherit the
   /// locale from this span unless explicitly set to different locales.
   final ui.Locale? locale;

   /// Whether the assistive technologies should spell out this text character
   /// by character.
   ///
   /// If the text is 'hello world', setting this to true causes the assistive
   /// technologies, such as VoiceOver or TalkBack, to pronounce
   /// 'h-e-l-l-o-space-w-o-r-l-d' instead of complete words. This is useful for
   /// texts, such as passwords or verification codes.
   ///
   /// If this span contains other text span children, they also inherit the
   /// property from this span unless explicitly set.
   ///
   /// If the property is not set, this text span inherits the spell out setting
   /// from its parent. If this text span does not have a parent or the parent
   /// does not have a spell out setting, this text span does not spell out the
   /// text by default.
   final bool? spellOut;

   @override
   bool get validForMouseTracker => true;

   @override
   void handleEvent(PointerEvent event, HitTestEntry entry) {
     if (event is PointerDownEvent)
       recognizer?.addPointer(event);
   }

   /// Apply the [style], [text], and [children] of this object to the
   /// given [ParagraphBuilder], from which a [Paragraph] can be obtained.
   /// [Paragraph] objects can be drawn on [Canvas] objects.
   ///
   /// Rather than using this directly, it's simpler to use the
   /// [TextPainter] class to paint [TextSpan] objects onto [Canvas]
   /// objects.
   @override
   void build(
     ui.ParagraphBuilder builder, {
     double textScaleFactor = 1.0,
     List<PlaceholderDimensions>? dimensions,
   }) {
     assert(debugAssertIsValid());
     final bool hasStyle = style != null;
     if (hasStyle)
       builder.pushStyle(style!.getTextStyle(textScaleFactor: textScaleFactor));
     if (text != null) {
       try {
         builder.addText(text!);
       } on ArgumentError catch (exception, stack) {
         FlutterError.reportError(FlutterErrorDetails(
           exception: exception,
           stack: stack,
           library: 'painting library',
           context: ErrorDescription('while building a TextSpan'),
         ));
         // Use a Unicode replacement character as a substitute for invalid text.
         builder.addText('\uFFFD');
       }
     }
     if (children != null) {
       for (final InlineSpan child in children!) {
         assert(child != null);
         child.build(
           builder,
           textScaleFactor: textScaleFactor,
           dimensions: dimensions,
         );
       }
     }
     if (hasStyle)
       builder.pop();
   }

   /// Walks this [TextSpan] and its descendants in pre-order and calls [visitor]
   /// for each span that has text.
   ///
   /// When `visitor` returns true, the walk will continue. When `visitor`
   /// returns false, then the walk will end.
   @override
   bool visitChildren(InlineSpanVisitor visitor) {
     if (text != null) {
       if (!visitor(this))
         return false;
     }
     if (children != null) {
       for (final InlineSpan child in children!) {
         if (!child.visitChildren(visitor))
           return false;
       }
     }
     return true;
   }

   /// Returns the text span that contains the given position in the text.
   @override
   InlineSpan? getSpanForPositionVisitor(TextPosition position, Accumulator offset) {
     if (text == null) {
       return null;
     }
     final TextAffinity affinity = position.affinity;
     final int targetOffset = position.offset;
     final int endOffset = offset.value + text!.length;
     if (offset.value == targetOffset && affinity == TextAffinity.downstream ||
         offset.value < targetOffset && targetOffset < endOffset ||
         endOffset == targetOffset && affinity == TextAffinity.upstream) {
       return this;
     }
     offset.increment(text!.length);
     return null;
   }

   @override
   void computeToPlainText(
     StringBuffer buffer, {
     bool includeSemanticsLabels = true,
     bool includePlaceholders = true,
   }) {
     assert(debugAssertIsValid());
     if (semanticsLabel != null && includeSemanticsLabels) {
       buffer.write(semanticsLabel);
     } else if (text != null) {
       buffer.write(text);
     }
     if (children != null) {
       for (final InlineSpan child in children!) {
         child.computeToPlainText(buffer,
           includeSemanticsLabels: includeSemanticsLabels,
           includePlaceholders: includePlaceholders,
         );
       }
     }
   }

   @override
   void computeSemanticsInformation(
     List<InlineSpanSemanticsInformation> collector, {
     ui.Locale? inheritedLocale,
     bool inheritedSpellOut = false,
   }) {
     assert(debugAssertIsValid());
     final ui.Locale? effectiveLocale = locale ?? inheritedLocale;
     final bool effectiveSpellOut = spellOut ?? inheritedSpellOut;

     if (text != null) {
       final int textLength = semanticsLabel?.length ?? text!.length;
       collector.add(InlineSpanSemanticsInformation(
         text!,
         stringAttributes: <ui.StringAttribute>[
           if (effectiveSpellOut && textLength > 0)
             ui.SpellOutStringAttribute(range: TextRange(start: 0, end: textLength)),
           if (effectiveLocale != null && textLength > 0)
             ui.LocaleStringAttribute(locale: effectiveLocale, range: TextRange(start: 0, end: textLength)),
         ],
         semanticsLabel: semanticsLabel,
         recognizer: recognizer,
       ));
     }
     if (children != null) {
       for (final InlineSpan child in children!) {
         if (child is TextSpan) {
           child.computeSemanticsInformation(
             collector,
             inheritedLocale: effectiveLocale,
             inheritedSpellOut: effectiveSpellOut,
           );
         } else {
           child.computeSemanticsInformation(collector);
         }
       }
     }
   }

   @override
   int? codeUnitAtVisitor(int index, Accumulator offset) {
     if (text == null) {
       return null;
     }
     if (index - offset.value < text!.length) {
       return text!.codeUnitAt(index - offset.value);
     }
     offset.increment(text!.length);
     return null;
   }

   /// Populates the `semanticsOffsets` and `semanticsElements` with the appropriate data
   /// to be able to construct a [SemanticsNode].
   ///
   /// If applicable, the beginning and end text offset are added to [semanticsOffsets].
   /// [PlaceholderSpan]s have a text length of 1, which corresponds to the object
   /// replacement character (0xFFFC) that is inserted to represent it.
   ///
   /// Any [GestureRecognizer]s are added to `semanticsElements`. Null is added to
   /// `semanticsElements` for [PlaceholderSpan]s.
   void describeSemantics(Accumulator offset, List<int> semanticsOffsets, List<dynamic> semanticsElements) {
     if (
       recognizer != null &&
       (recognizer is TapGestureRecognizer || recognizer is LongPressGestureRecognizer)
     ) {
       final int length = semanticsLabel?.length ?? text!.length;
       semanticsOffsets.add(offset.value);
       semanticsOffsets.add(offset.value + length);
       semanticsElements.add(recognizer);
     }
     offset.increment(text != null ? text!.length : 0);
   }

   /// In debug mode, throws an exception if the object is not in a valid
   /// configuration. Otherwise, returns true.
   ///
   /// This is intended to be used as follows:
   ///
   /// ```dart
   /// assert(myTextSpan.debugAssertIsValid());
   /// ```
   @override
   bool debugAssertIsValid() {
     assert(() {
       if (children != null) {
         for (final InlineSpan child in children!) {
           if (child == null) {
             throw FlutterError.fromParts(<DiagnosticsNode>[
               ErrorSummary('TextSpan contains a null child.'),
               ErrorDescription(
                 'A TextSpan object with a non-null child list should not have any nulls in its child list.',
               ),
               toDiagnosticsNode(
                 name: 'The full text in question was',
                 style: DiagnosticsTreeStyle.errorProperty,
               ),
             ]);
           }
           assert(child.debugAssertIsValid());
         }
       }
       return true;
     }());
     return super.debugAssertIsValid();
   }

   @override
   RenderComparison compareTo(InlineSpan other) {
     if (identical(this, other))
       return RenderComparison.identical;
     if (other.runtimeType != runtimeType)
       return RenderComparison.layout;
     final TextSpan textSpan = other as TextSpan;
     if (textSpan.text != text ||
         children?.length != textSpan.children?.length ||
         (style == null) != (textSpan.style == null))
       return RenderComparison.layout;
     RenderComparison result = recognizer == textSpan.recognizer ?
       RenderComparison.identical :
       RenderComparison.metadata;
     if (style != null) {
       final RenderComparison candidate = style!.compareTo(textSpan.style!);
       if (candidate.index > result.index)
         result = candidate;
       if (result == RenderComparison.layout)
         return result;
     }
     if (children != null) {
       for (int index = 0; index < children!.length; index += 1) {
         final RenderComparison candidate = children![index].compareTo(textSpan.children![index]);
         if (candidate.index > result.index)
           result = candidate;
         if (result == RenderComparison.layout)
           return result;
       }
     }
     return result;
   }

   @override
   bool operator ==(Object other) {
     if (identical(this, other))
       return true;
     if (other.runtimeType != runtimeType)
       return false;
     if (super != other)
       return false;
     return other is TextSpan
         && other.text == text
         && other.recognizer == recognizer
         && other.semanticsLabel == semanticsLabel
         && onEnter == other.onEnter
         && onExit == other.onExit
         && mouseCursor == other.mouseCursor
         && listEquals<InlineSpan>(other.children, children);
   }

   @override
   int get hashCode => hashValues(
     super.hashCode,
     text,
     recognizer,
     semanticsLabel,
     onEnter,
     onExit,
     mouseCursor,
     hashList(children),
   );

   @override
   String toStringShort() => objectRuntimeType(this, 'TextSpan');

   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);

     properties.add(
       StringProperty(
         'text',
         text,
         showName: false,
         defaultValue: null,
       ),
     );
     if (style == null && text == null && children == null)
       properties.add(DiagnosticsNode.message('(empty)'));

     properties.add(DiagnosticsProperty<GestureRecognizer>(
       'recognizer', recognizer,
       description: recognizer?.runtimeType.toString(),
       defaultValue: null,
     ));

     properties.add(FlagsSummary<Function?>(
       'callbacks',
       <String, Function?> {
         'enter': onEnter,
         'exit': onExit,
       },
     ));
     properties.add(DiagnosticsProperty<MouseCursor>('mouseCursor', cursor, defaultValue: MouseCursor.defer));

     if (semanticsLabel != null) {
       properties.add(StringProperty('semanticsLabel', semanticsLabel));
     }
   }

   @override
   List<DiagnosticsNode> debugDescribeChildren() {
     if (children == null)
       return const <DiagnosticsNode>[];
     return children!.map<DiagnosticsNode>((InlineSpan child) {
       // `child` has a non-nullable return type, but might be null when running
       // with weak checking, so we need to null check it anyway (and ignore the
       // warning that the null-handling logic is dead code).
       if (child != null) {
         return child.toDiagnosticsNode();
       } else {
         return DiagnosticsNode.message('<null child>');
       }
     }).toList();
   }
 }
	// Copyright 2014 The Flutter Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	import 'dart:ui' as ui show ParagraphBuilder, Locale, StringAttribute, LocaleStringAttribute, SpellOutStringAttribute;

	import 'package:flutter/foundation.dart';
	import 'package:flutter/gestures.dart';
	import 'package:flutter/services.dart';

	import 'basic_types.dart';
	import 'inline_span.dart';
	import 'text_painter.dart';
	import 'text_style.dart';

	/// An immutable span of text.
	///
	/// A [TextSpan] object can be styled using its [style] property. The style will
	/// be applied to the [text] and the [children].
	///
	/// A [TextSpan] object can just have plain text, or it can have children
	/// [TextSpan] objects with their own styles that (possibly only partially)
	/// override the [style] of this object. If a [TextSpan] has both [text] and
	/// [children], then the [text] is treated as if it was an un-styled [TextSpan]
	/// at the start of the [children] list. Leaving the [TextSpan.text] field null
	/// results in the [TextSpan] acting as an empty node in the [InlineSpan] tree
	/// with a list of children.
	///
	/// To paint a [TextSpan] on a [Canvas], use a [TextPainter]. To display a text
	/// span in a widget, use a [RichText]. For text with a single style, consider
	/// using the [Text] widget.
	///
	/// {@tool snippet}
	///
	/// The text "Hello world!", in black:
	///
	/// ```dart
	/// const TextSpan(
	/// text: 'Hello world!',
	/// style: TextStyle(color: Colors.black),
	/// )
	/// ```
	/// {@end-tool}
	///
	/// _There is some more detailed sample code in the documentation for the
	/// [recognizer] property._
	///
	/// The [TextSpan.text] will be used as the semantics label unless overridden
	/// by the [TextSpan.semanticsLabel] property. Any [PlaceholderSpan]s in the
	/// [TextSpan.children] list will separate the text before and after it into two
	/// semantics nodes.
	///
	/// See also:
	///
	/// * [WidgetSpan], a leaf node that represents an embedded inline widget in an
	/// [InlineSpan] tree. Specify a widget within the [children] list by
	/// wrapping the widget with a [WidgetSpan]. The widget will be laid out
	/// inline within the paragraph.
	/// * [Text], a widget for showing uniformly-styled text.
	/// * [RichText], a widget for finer control of text rendering.
	/// * [TextPainter], a class for painting [TextSpan] objects on a [Canvas].
	@immutable
	class TextSpan extends InlineSpan implements HitTestTarget, MouseTrackerAnnotation {
	/// Creates a [TextSpan] with the given values.
	///
	/// For the object to be useful, at least one of [text] or
	/// [children] should be set.
	const TextSpan({
	this.text,
	this.children,
	TextStyle? style,
	this.recognizer,
	MouseCursor? mouseCursor,
	this.onEnter,
	this.onExit,
	this.semanticsLabel,
	this.locale,
	this.spellOut,
	}) : mouseCursor = mouseCursor ??
	(recognizer == null ? MouseCursor.defer : SystemMouseCursors.click),
	assert(!(text == null && semanticsLabel != null)),
	super(style: style);

	/// The text contained in this span.
	///
	/// If both [text] and [children] are non-null, the text will precede the
	/// children.
	///
	/// This getter does not include the contents of its children.
	final String? text;

	/// Additional spans to include as children.
	///
	/// If both [text] and [children] are non-null, the text will precede the
	/// children.
	///
	/// Modifying the list after the [TextSpan] has been created is not supported
	/// and may have unexpected results.
	///
	/// The list must not contain any nulls.
	final List<InlineSpan>? children;

	/// A gesture recognizer that will receive events that hit this span.
	///
	/// [InlineSpan] itself does not implement hit testing or event dispatch. The
	/// object that manages the [InlineSpan] painting is also responsible for
	/// dispatching events. In the rendering library, that is the
	/// [RenderParagraph] object, which corresponds to the [RichText] widget in
	/// the widgets layer; these objects do not bubble events in [InlineSpan]s,
	/// so a [recognizer] is only effective for events that directly hit the
	/// [text] of that [InlineSpan], not any of its [children].
	///
	/// [InlineSpan] also does not manage the lifetime of the gesture recognizer.
	/// The code that owns the [GestureRecognizer] object must call
	/// [GestureRecognizer.dispose] when the [InlineSpan] object is no longer
	/// used.
	///
	/// {@tool snippet}
	///
	/// This example shows how to manage the lifetime of a gesture recognizer
	/// provided to an [InlineSpan] object. It defines a `BuzzingText` widget
	/// which uses the [HapticFeedback] class to vibrate the device when the user
	/// long-presses the "find the" span, which is underlined in wavy green. The
	/// hit-testing is handled by the [RichText] widget. It also changes the
	/// hovering mouse cursor to `precise`.
	///
	/// ```dart
	/// class BuzzingText extends StatefulWidget {
	/// const BuzzingText({Key? key}) : super(key: key);
	///
	/// @override
	/// State<BuzzingText> createState() => _BuzzingTextState();
	/// }
	///
	/// class _BuzzingTextState extends State<BuzzingText> {
	/// late LongPressGestureRecognizer _longPressRecognizer;
	///
	/// @override
	/// void initState() {
	/// super.initState();
	/// _longPressRecognizer = LongPressGestureRecognizer()
	/// ..onLongPress = _handlePress;
	/// }
	///
	/// @override
	/// void dispose() {
	/// _longPressRecognizer.dispose();
	/// super.dispose();
	/// }
	///
	/// void _handlePress() {
	/// HapticFeedback.vibrate();
	/// }
	///
	/// @override
	/// Widget build(BuildContext context) {
	/// return Text.rich(
	/// TextSpan(
	/// text: 'Can you ',
	/// style: const TextStyle(color: Colors.black),
	/// children: <InlineSpan>[
	/// TextSpan(
	/// text: 'find the',
	/// style: const TextStyle(
	/// color: Colors.green,
	/// decoration: TextDecoration.underline,
	/// decorationStyle: TextDecorationStyle.wavy,
	/// ),
	/// recognizer: _longPressRecognizer,
	/// mouseCursor: SystemMouseCursors.precise,
	/// ),
	/// const TextSpan(
	/// text: ' secret?',
	/// ),
	/// ],
	/// ),
	/// );
	/// }
	/// }
	/// ```
	/// {@end-tool}
	final GestureRecognizer? recognizer;

	/// Mouse cursor when the mouse hovers over this span.
	///
	/// The default value is [SystemMouseCursors.click] if [recognizer] is not
	/// null, or [MouseCursor.defer] otherwise.
	///
	/// [TextSpan] itself does not implement hit testing or cursor changing.
	/// The object that manages the [TextSpan] painting is responsible
	/// to return the [TextSpan] in its hit test, as well as providing the
	/// correct mouse cursor when the [TextSpan]'s mouse cursor is
	/// [MouseCursor.defer].
	final MouseCursor mouseCursor;

	@override
	final PointerEnterEventListener? onEnter;

	@override
	final PointerExitEventListener? onExit;

	/// Returns the value of [mouseCursor].
	///
	/// This field, required by [MouseTrackerAnnotation], is hidden publicly to
	/// avoid the confusion as a text cursor.
	@protected
	@override
	MouseCursor get cursor => mouseCursor;

	/// An alternative semantics label for this [TextSpan].
	///
	/// If present, the semantics of this span will contain this value instead
	/// of the actual text.
	///
	/// This is useful for replacing abbreviations or shorthands with the full
	/// text value:
	///
	/// ```dart
	/// TextSpan(text: r'$$', semanticsLabel: 'Double dollars')
	/// ```
	final String? semanticsLabel;

	/// The language of the text in this span and its span children.
	///
	/// Setting the locale of this text span affects the way that assistive
	/// technologies, such as VoiceOver or TalkBack, pronounce the text.
	///
	/// If this span contains other text span children, they also inherit the
	/// locale from this span unless explicitly set to different locales.
	final ui.Locale? locale;

	/// Whether the assistive technologies should spell out this text character
	/// by character.
	///
	/// If the text is 'hello world', setting this to true causes the assistive
	/// technologies, such as VoiceOver or TalkBack, to pronounce
	/// 'h-e-l-l-o-space-w-o-r-l-d' instead of complete words. This is useful for
	/// texts, such as passwords or verification codes.
	///
	/// If this span contains other text span children, they also inherit the
	/// property from this span unless explicitly set.
	///
	/// If the property is not set, this text span inherits the spell out setting
	/// from its parent. If this text span does not have a parent or the parent
	/// does not have a spell out setting, this text span does not spell out the
	/// text by default.
	final bool? spellOut;

	@override
	bool get validForMouseTracker => true;

	@override
	void handleEvent(PointerEvent event, HitTestEntry entry) {
	if (event is PointerDownEvent)
	recognizer?.addPointer(event);
	}

	/// Apply the [style], [text], and [children] of this object to the
	/// given [ParagraphBuilder], from which a [Paragraph] can be obtained.
	/// [Paragraph] objects can be drawn on [Canvas] objects.
	///
	/// Rather than using this directly, it's simpler to use the
	/// [TextPainter] class to paint [TextSpan] objects onto [Canvas]
	/// objects.
	@override
	void build(
	ui.ParagraphBuilder builder, {
	double textScaleFactor = 1.0,
	List<PlaceholderDimensions>? dimensions,
	}) {
	assert(debugAssertIsValid());
	final bool hasStyle = style != null;
	if (hasStyle)
	builder.pushStyle(style!.getTextStyle(textScaleFactor: textScaleFactor));
	if (text != null) {
	try {
	builder.addText(text!);
	} on ArgumentError catch (exception, stack) {
	FlutterError.reportError(FlutterErrorDetails(
	exception: exception,
	stack: stack,
	library: 'painting library',
	context: ErrorDescription('while building a TextSpan'),
	));
	// Use a Unicode replacement character as a substitute for invalid text.
	builder.addText('\uFFFD');
	}
	}
	if (children != null) {
	for (final InlineSpan child in children!) {
	assert(child != null);
	child.build(
	builder,
	textScaleFactor: textScaleFactor,
	dimensions: dimensions,
	);
	}
	}
	if (hasStyle)
	builder.pop();
	}

	/// Walks this [TextSpan] and its descendants in pre-order and calls [visitor]
	/// for each span that has text.
	///
	/// When `visitor` returns true, the walk will continue. When `visitor`
	/// returns false, then the walk will end.
	@override
	bool visitChildren(InlineSpanVisitor visitor) {
	if (text != null) {
	if (!visitor(this))
	return false;
	}
	if (children != null) {
	for (final InlineSpan child in children!) {
	if (!child.visitChildren(visitor))
	return false;
	}
	}
	return true;
	}

	/// Returns the text span that contains the given position in the text.
	@override
	InlineSpan? getSpanForPositionVisitor(TextPosition position, Accumulator offset) {
	if (text == null) {
	return null;
	}
	final TextAffinity affinity = position.affinity;
	final int targetOffset = position.offset;
	final int endOffset = offset.value + text!.length;
	if (offset.value == targetOffset && affinity == TextAffinity.downstream \|\|
	offset.value < targetOffset && targetOffset < endOffset \|\|
	endOffset == targetOffset && affinity == TextAffinity.upstream) {
	return this;
	}
	offset.increment(text!.length);
	return null;
	}

	@override
	void computeToPlainText(
	StringBuffer buffer, {
	bool includeSemanticsLabels = true,
	bool includePlaceholders = true,
	}) {
	assert(debugAssertIsValid());
	if (semanticsLabel != null && includeSemanticsLabels) {
	buffer.write(semanticsLabel);
	} else if (text != null) {
	buffer.write(text);
	}
	if (children != null) {
	for (final InlineSpan child in children!) {
	child.computeToPlainText(buffer,
	includeSemanticsLabels: includeSemanticsLabels,
	includePlaceholders: includePlaceholders,
	);
	}
	}
	}

	@override
	void computeSemanticsInformation(
	List<InlineSpanSemanticsInformation> collector, {
	ui.Locale? inheritedLocale,
	bool inheritedSpellOut = false,
	}) {
	assert(debugAssertIsValid());
	final ui.Locale? effectiveLocale = locale ?? inheritedLocale;
	final bool effectiveSpellOut = spellOut ?? inheritedSpellOut;

	if (text != null) {
	final int textLength = semanticsLabel?.length ?? text!.length;
	collector.add(InlineSpanSemanticsInformation(
	text!,
	stringAttributes: <ui.StringAttribute>[
	if (effectiveSpellOut && textLength > 0)
	ui.SpellOutStringAttribute(range: TextRange(start: 0, end: textLength)),
	if (effectiveLocale != null && textLength > 0)
	ui.LocaleStringAttribute(locale: effectiveLocale, range: TextRange(start: 0, end: textLength)),
	],
	semanticsLabel: semanticsLabel,
	recognizer: recognizer,
	));
	}
	if (children != null) {
	for (final InlineSpan child in children!) {
	if (child is TextSpan) {
	child.computeSemanticsInformation(
	collector,
	inheritedLocale: effectiveLocale,
	inheritedSpellOut: effectiveSpellOut,
	);
	} else {
	child.computeSemanticsInformation(collector);
	}
	}
	}
	}

	@override
	int? codeUnitAtVisitor(int index, Accumulator offset) {
	if (text == null) {
	return null;
	}
	if (index - offset.value < text!.length) {
	return text!.codeUnitAt(index - offset.value);
	}
	offset.increment(text!.length);
	return null;
	}

	/// Populates the `semanticsOffsets` and `semanticsElements` with the appropriate data
	/// to be able to construct a [SemanticsNode].
	///
	/// If applicable, the beginning and end text offset are added to [semanticsOffsets].
	/// [PlaceholderSpan]s have a text length of 1, which corresponds to the object
	/// replacement character (0xFFFC) that is inserted to represent it.
	///
	/// Any [GestureRecognizer]s are added to `semanticsElements`. Null is added to
	/// `semanticsElements` for [PlaceholderSpan]s.
	void describeSemantics(Accumulator offset, List<int> semanticsOffsets, List<dynamic> semanticsElements) {
	if (
	recognizer != null &&
	(recognizer is TapGestureRecognizer \|\| recognizer is LongPressGestureRecognizer)
	) {
	final int length = semanticsLabel?.length ?? text!.length;
	semanticsOffsets.add(offset.value);
	semanticsOffsets.add(offset.value + length);
	semanticsElements.add(recognizer);
	}
	offset.increment(text != null ? text!.length : 0);
	}

	/// In debug mode, throws an exception if the object is not in a valid
	/// configuration. Otherwise, returns true.
	///
	/// This is intended to be used as follows:
	///
	/// ```dart
	/// assert(myTextSpan.debugAssertIsValid());
	/// ```
	@override
	bool debugAssertIsValid() {
	assert(() {
	if (children != null) {
	for (final InlineSpan child in children!) {
	if (child == null) {
	throw FlutterError.fromParts(<DiagnosticsNode>[
	ErrorSummary('TextSpan contains a null child.'),
	ErrorDescription(
	'A TextSpan object with a non-null child list should not have any nulls in its child list.',
	),
	toDiagnosticsNode(
	name: 'The full text in question was',
	style: DiagnosticsTreeStyle.errorProperty,
	),
	]);
	}
	assert(child.debugAssertIsValid());
	}
	}
	return true;
	}());
	return super.debugAssertIsValid();
	}

	@override
	RenderComparison compareTo(InlineSpan other) {
	if (identical(this, other))
	return RenderComparison.identical;
	if (other.runtimeType != runtimeType)
	return RenderComparison.layout;
	final TextSpan textSpan = other as TextSpan;
	if (textSpan.text != text \|\|
	children?.length != textSpan.children?.length \|\|
	(style == null) != (textSpan.style == null))
	return RenderComparison.layout;
	RenderComparison result = recognizer == textSpan.recognizer ?
	RenderComparison.identical :
	RenderComparison.metadata;
	if (style != null) {
	final RenderComparison candidate = style!.compareTo(textSpan.style!);
	if (candidate.index > result.index)
	result = candidate;
	if (result == RenderComparison.layout)
	return result;
	}
	if (children != null) {
	for (int index = 0; index < children!.length; index += 1) {
	final RenderComparison candidate = children![index].compareTo(textSpan.children![index]);
	if (candidate.index > result.index)
	result = candidate;
	if (result == RenderComparison.layout)
	return result;
	}
	}
	return result;
	}

	@override
	bool operator ==(Object other) {
	if (identical(this, other))
	return true;
	if (other.runtimeType != runtimeType)
	return false;
	if (super != other)
	return false;
	return other is TextSpan
	&& other.text == text
	&& other.recognizer == recognizer
	&& other.semanticsLabel == semanticsLabel
	&& onEnter == other.onEnter
	&& onExit == other.onExit
	&& mouseCursor == other.mouseCursor
	&& listEquals<InlineSpan>(other.children, children);
	}

	@override
	int get hashCode => hashValues(
	super.hashCode,
	text,
	recognizer,
	semanticsLabel,
	onEnter,
	onExit,
	mouseCursor,
	hashList(children),
	);

	@override
	String toStringShort() => objectRuntimeType(this, 'TextSpan');

	@override
	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
	super.debugFillProperties(properties);

	properties.add(
	StringProperty(
	'text',
	text,
	showName: false,
	defaultValue: null,
	),
	);
	if (style == null && text == null && children == null)
	properties.add(DiagnosticsNode.message('(empty)'));

	properties.add(DiagnosticsProperty<GestureRecognizer>(
	'recognizer', recognizer,
	description: recognizer?.runtimeType.toString(),
	defaultValue: null,
	));

	properties.add(FlagsSummary<Function?>(
	'callbacks',
	<String, Function?> {
	'enter': onEnter,
	'exit': onExit,
	},
	));
	properties.add(DiagnosticsProperty<MouseCursor>('mouseCursor', cursor, defaultValue: MouseCursor.defer));

	if (semanticsLabel != null) {
	properties.add(StringProperty('semanticsLabel', semanticsLabel));
	}
	}

	@override
	List<DiagnosticsNode> debugDescribeChildren() {
	if (children == null)
	return const <DiagnosticsNode>[];
	return children!.map<DiagnosticsNode>((InlineSpan child) {
	// `child` has a non-nullable return type, but might be null when running
	// with weak checking, so we need to null check it anyway (and ignore the
	// warning that the null-handling logic is dead code).
	if (child != null) {
	return child.toDiagnosticsNode();
	} else {
	return DiagnosticsNode.message('<null child>');
	}
	}).toList();
	}
	}