packages/flutter/lib/src/painting/text_span.dart - mirrors/flutter - Git at Google

 // Copyright 2015 The Chromium 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;

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

 import 'basic_types.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 unstyled [TextSpan] at the start of the
 /// [children] list.
 ///
 /// 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 sample}
 ///
 /// The text "Hello world!", in black:
 ///
 /// ```dart
 /// 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._
 ///
 /// See also:
 ///
 ///  * [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 DiagnosticableTree {
   /// 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.style,
     this.text,
     this.children,
     this.recognizer,
     this.semanticsLabel,
   });

   /// The style to apply to the [text] and the [children].
   final TextStyle style;

   /// The text contained in the span.
   ///
   /// If both [text] and [children] are non-null, the text will precede the
   /// 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<TextSpan> children;

   /// A gesture recognizer that will receive events that hit this text span.
   ///
   /// [TextSpan] itself does not implement hit testing or event dispatch. The
   /// object that manages the [TextSpan] 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 [TextSpan]s, so a
   /// [recognizer] is only effective for events that directly hit the [text] of
   /// that [TextSpan], not any of its [children].
   ///
   /// [TextSpan] also does not manage the lifetime of the gesture recognizer.
   /// The code that owns the [GestureRecognizer] object must call
   /// [GestureRecognizer.dispose] when the [TextSpan] object is no longer used.
   ///
   /// {@tool sample}
   ///
   /// This example shows how to manage the lifetime of a gesture recognizer
   /// provided to a [TextSpan] 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.
   ///
   /// ```dart
   /// class BuzzingText extends StatefulWidget {
   ///   @override
   ///   _BuzzingTextState createState() => _BuzzingTextState();
   /// }
   ///
   /// class _BuzzingTextState extends State<BuzzingText> {
   ///   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 RichText(
   ///       text: TextSpan(
   ///         text: 'Can you ',
   ///         style: TextStyle(color: Colors.black),
   ///         children: <TextSpan>[
   ///           TextSpan(
   ///             text: 'find the',
   ///             style: TextStyle(
   ///               color: Colors.green,
   ///               decoration: TextDecoration.underline,
   ///               decorationStyle: TextDecorationStyle.wavy,
   ///             ),
   ///             recognizer: _longPressRecognizer,
   ///           ),
   ///           TextSpan(
   ///             text: ' secret?',
   ///           ),
   ///         ],
   ///       ),
   ///     );
   ///   }
   /// }
   /// ```
   /// {@end-tool}
   final GestureRecognizer recognizer;

   /// An alternative semantics label for this text.
   ///
   /// 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;

   /// 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.
   void build(ui.ParagraphBuilder builder, { double textScaleFactor = 1.0 }) {
     assert(debugAssertIsValid());
     final bool hasStyle = style != null;
     if (hasStyle)
       builder.pushStyle(style.getTextStyle(textScaleFactor: textScaleFactor));
     if (text != null)
       builder.addText(text);
     if (children != null) {
       for (TextSpan child in children) {
         assert(child != null);
         child.build(builder, textScaleFactor: textScaleFactor);
       }
     }
     if (hasStyle)
       builder.pop();
   }

   /// Walks this text span and its descendants in pre-order and calls [visitor]
   /// for each span that has text.
   bool visitTextSpan(bool visitor(TextSpan span)) {
     if (text != null) {
       if (!visitor(this))
         return false;
     }
     if (children != null) {
       for (TextSpan child in children) {
         if (!child.visitTextSpan(visitor))
           return false;
       }
     }
     return true;
   }

   /// Returns the text span that contains the given position in the text.
   TextSpan getSpanForPosition(TextPosition position) {
     assert(debugAssertIsValid());
     final TextAffinity affinity = position.affinity;
     final int targetOffset = position.offset;
     int offset = 0;
     TextSpan result;
     visitTextSpan((TextSpan span) {
       assert(result == null);
       final int endOffset = offset + span.text.length;
       if (targetOffset == offset && affinity == TextAffinity.downstream ||
           targetOffset > offset && targetOffset < endOffset ||
           targetOffset == endOffset && affinity == TextAffinity.upstream) {
         result = span;
         return false;
       }
       offset = endOffset;
       return true;
     });
     return result;
   }

   /// Flattens the [TextSpan] tree into a single string.
   ///
   /// Styles are not honored in this process. If `includeSemanticsLabels` is
   /// true, then the text returned will include the [semanticsLabel]s instead of
   /// the text contents when they are present.
   String toPlainText({bool includeSemanticsLabels = true}) {
     assert(debugAssertIsValid());
     final StringBuffer buffer = StringBuffer();
     visitTextSpan((TextSpan span) {
       if (span.semanticsLabel != null && includeSemanticsLabels) {
         buffer.write(span.semanticsLabel);
       } else {
         buffer.write(span.text);
       }
       return true;
     });
     return buffer.toString();
   }

   /// Returns the UTF-16 code unit at the given index in the flattened string.
   ///
   /// Returns null if the index is out of bounds.
   int codeUnitAt(int index) {
     if (index < 0)
       return null;
     int offset = 0;
     int result;
     visitTextSpan((TextSpan span) {
       if (index - offset < span.text.length) {
         result = span.text.codeUnitAt(index - offset);
         return false;
       }
       offset += span.text.length;
       return true;
     });
     return result;
   }

   /// In checked 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());
   /// ```
   bool debugAssertIsValid() {
     assert(() {
       if (!visitTextSpan((TextSpan span) {
         if (span.children != null) {
           for (TextSpan child in span.children) {
             if (child == null)
               return false;
           }
         }
         return true;
       })) {
         throw FlutterError(
           'TextSpan contains a null child.\n'
           'A TextSpan object with a non-null child list should not have any nulls in its child list.\n'
           'The full text in question was:\n'
           '${toStringDeep(prefixLineOne: '  ')}'
         );
       }
       return true;
     }());
     return true;
   }

   /// Describe the difference between this text span and another, in terms of
   /// how much damage it will make to the rendering. The comparison is deep.
   ///
   /// See also:
   ///
   ///  * [TextStyle.compareTo], which does the same thing for [TextStyle]s.
   RenderComparison compareTo(TextSpan other) {
     if (identical(this, other))
       return RenderComparison.identical;
     if (other.text != text ||
         children?.length != other.children?.length ||
         (style == null) != (other.style == null))
       return RenderComparison.layout;
     RenderComparison result = recognizer == other.recognizer ? RenderComparison.identical : RenderComparison.metadata;
     if (style != null) {
       final RenderComparison candidate = style.compareTo(other.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(other.children[index]);
         if (candidate.index > result.index)
           result = candidate;
         if (result == RenderComparison.layout)
           return result;
       }
     }
     return result;
   }

   @override
   bool operator ==(dynamic other) {
     if (identical(this, other))
       return true;
     if (other.runtimeType != runtimeType)
       return false;
     final TextSpan typedOther = other;
     return typedOther.text == text
         && typedOther.style == style
         && typedOther.recognizer == recognizer
         && typedOther.semanticsLabel == semanticsLabel
         && listEquals<TextSpan>(typedOther.children, children);
   }

   @override
   int get hashCode => hashValues(style, text, recognizer, semanticsLabel, hashList(children));

   @override
   String toStringShort() => '$runtimeType';

   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
     properties.defaultDiagnosticsTreeStyle = DiagnosticsTreeStyle.whitespace;
     // Properties on style are added as if they were properties directly on
     // this TextSpan.
     if (style != null)
       style.debugFillProperties(properties);

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


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


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

   @override
   List<DiagnosticsNode> debugDescribeChildren() {
     if (children == null)
       return const <DiagnosticsNode>[];
     return children.map<DiagnosticsNode>((TextSpan child) {
       if (child != null) {
         return child.toDiagnosticsNode();
       } else {
         return DiagnosticsNode.message('<null child>');
       }
     }).toList();
   }
 }
	// Copyright 2015 The Chromium 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;

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

	import 'basic_types.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 unstyled [TextSpan] at the start of the
	/// [children] list.
	///
	/// 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 sample}
	///
	/// The text "Hello world!", in black:
	///
	/// ```dart
	/// 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._
	///
	/// See also:
	///
	/// * [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 DiagnosticableTree {
	/// 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.style,
	this.text,
	this.children,
	this.recognizer,
	this.semanticsLabel,
	});

	/// The style to apply to the [text] and the [children].
	final TextStyle style;

	/// The text contained in the span.
	///
	/// If both [text] and [children] are non-null, the text will precede the
	/// 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<TextSpan> children;

	/// A gesture recognizer that will receive events that hit this text span.
	///
	/// [TextSpan] itself does not implement hit testing or event dispatch. The
	/// object that manages the [TextSpan] 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 [TextSpan]s, so a
	/// [recognizer] is only effective for events that directly hit the [text] of
	/// that [TextSpan], not any of its [children].
	///
	/// [TextSpan] also does not manage the lifetime of the gesture recognizer.
	/// The code that owns the [GestureRecognizer] object must call
	/// [GestureRecognizer.dispose] when the [TextSpan] object is no longer used.
	///
	/// {@tool sample}
	///
	/// This example shows how to manage the lifetime of a gesture recognizer
	/// provided to a [TextSpan] 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.
	///
	/// ```dart
	/// class BuzzingText extends StatefulWidget {
	/// @override
	/// _BuzzingTextState createState() => _BuzzingTextState();
	/// }
	///
	/// class _BuzzingTextState extends State<BuzzingText> {
	/// 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 RichText(
	/// text: TextSpan(
	/// text: 'Can you ',
	/// style: TextStyle(color: Colors.black),
	/// children: <TextSpan>[
	/// TextSpan(
	/// text: 'find the',
	/// style: TextStyle(
	/// color: Colors.green,
	/// decoration: TextDecoration.underline,
	/// decorationStyle: TextDecorationStyle.wavy,
	/// ),
	/// recognizer: _longPressRecognizer,
	/// ),
	/// TextSpan(
	/// text: ' secret?',
	/// ),
	/// ],
	/// ),
	/// );
	/// }
	/// }
	/// ```
	/// {@end-tool}
	final GestureRecognizer recognizer;

	/// An alternative semantics label for this text.
	///
	/// 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;

	/// 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.
	void build(ui.ParagraphBuilder builder, { double textScaleFactor = 1.0 }) {
	assert(debugAssertIsValid());
	final bool hasStyle = style != null;
	if (hasStyle)
	builder.pushStyle(style.getTextStyle(textScaleFactor: textScaleFactor));
	if (text != null)
	builder.addText(text);
	if (children != null) {
	for (TextSpan child in children) {
	assert(child != null);
	child.build(builder, textScaleFactor: textScaleFactor);
	}
	}
	if (hasStyle)
	builder.pop();
	}

	/// Walks this text span and its descendants in pre-order and calls [visitor]
	/// for each span that has text.
	bool visitTextSpan(bool visitor(TextSpan span)) {
	if (text != null) {
	if (!visitor(this))
	return false;
	}
	if (children != null) {
	for (TextSpan child in children) {
	if (!child.visitTextSpan(visitor))
	return false;
	}
	}
	return true;
	}

	/// Returns the text span that contains the given position in the text.
	TextSpan getSpanForPosition(TextPosition position) {
	assert(debugAssertIsValid());
	final TextAffinity affinity = position.affinity;
	final int targetOffset = position.offset;
	int offset = 0;
	TextSpan result;
	visitTextSpan((TextSpan span) {
	assert(result == null);
	final int endOffset = offset + span.text.length;
	if (targetOffset == offset && affinity == TextAffinity.downstream \|\|
	targetOffset > offset && targetOffset < endOffset \|\|
	targetOffset == endOffset && affinity == TextAffinity.upstream) {
	result = span;
	return false;
	}
	offset = endOffset;
	return true;
	});
	return result;
	}

	/// Flattens the [TextSpan] tree into a single string.
	///
	/// Styles are not honored in this process. If `includeSemanticsLabels` is
	/// true, then the text returned will include the [semanticsLabel]s instead of
	/// the text contents when they are present.
	String toPlainText({bool includeSemanticsLabels = true}) {
	assert(debugAssertIsValid());
	final StringBuffer buffer = StringBuffer();
	visitTextSpan((TextSpan span) {
	if (span.semanticsLabel != null && includeSemanticsLabels) {
	buffer.write(span.semanticsLabel);
	} else {
	buffer.write(span.text);
	}
	return true;
	});
	return buffer.toString();
	}

	/// Returns the UTF-16 code unit at the given index in the flattened string.
	///
	/// Returns null if the index is out of bounds.
	int codeUnitAt(int index) {
	if (index < 0)
	return null;
	int offset = 0;
	int result;
	visitTextSpan((TextSpan span) {
	if (index - offset < span.text.length) {
	result = span.text.codeUnitAt(index - offset);
	return false;
	}
	offset += span.text.length;
	return true;
	});
	return result;
	}

	/// In checked 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());
	/// ```
	bool debugAssertIsValid() {
	assert(() {
	if (!visitTextSpan((TextSpan span) {
	if (span.children != null) {
	for (TextSpan child in span.children) {
	if (child == null)
	return false;
	}
	}
	return true;
	})) {
	throw FlutterError(
	'TextSpan contains a null child.\n'
	'A TextSpan object with a non-null child list should not have any nulls in its child list.\n'
	'The full text in question was:\n'
	'${toStringDeep(prefixLineOne: ' ')}'
	);
	}
	return true;
	}());
	return true;
	}

	/// Describe the difference between this text span and another, in terms of
	/// how much damage it will make to the rendering. The comparison is deep.
	///
	/// See also:
	///
	/// * [TextStyle.compareTo], which does the same thing for [TextStyle]s.
	RenderComparison compareTo(TextSpan other) {
	if (identical(this, other))
	return RenderComparison.identical;
	if (other.text != text \|\|
	children?.length != other.children?.length \|\|
	(style == null) != (other.style == null))
	return RenderComparison.layout;
	RenderComparison result = recognizer == other.recognizer ? RenderComparison.identical : RenderComparison.metadata;
	if (style != null) {
	final RenderComparison candidate = style.compareTo(other.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(other.children[index]);
	if (candidate.index > result.index)
	result = candidate;
	if (result == RenderComparison.layout)
	return result;
	}
	}
	return result;
	}

	@override
	bool operator ==(dynamic other) {
	if (identical(this, other))
	return true;
	if (other.runtimeType != runtimeType)
	return false;
	final TextSpan typedOther = other;
	return typedOther.text == text
	&& typedOther.style == style
	&& typedOther.recognizer == recognizer
	&& typedOther.semanticsLabel == semanticsLabel
	&& listEquals<TextSpan>(typedOther.children, children);
	}

	@override
	int get hashCode => hashValues(style, text, recognizer, semanticsLabel, hashList(children));

	@override
	String toStringShort() => '$runtimeType';

	@override
	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
	super.debugFillProperties(properties);
	properties.defaultDiagnosticsTreeStyle = DiagnosticsTreeStyle.whitespace;
	// Properties on style are added as if they were properties directly on
	// this TextSpan.
	if (style != null)
	style.debugFillProperties(properties);

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


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


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

	@override
	List<DiagnosticsNode> debugDescribeChildren() {
	if (children == null)
	return const <DiagnosticsNode>[];
	return children.map<DiagnosticsNode>((TextSpan child) {
	if (child != null) {
	return child.toDiagnosticsNode();
	} else {
	return DiagnosticsNode.message('<null child>');
	}
	}).toList();
	}
	}