TextPainter class

An object that paints a TextSpan tree into a Canvas.

To use a TextPainter, follow these steps:

  1. Create a TextSpan tree and pass it to the TextPainter constructor.

  2. Call layout to prepare the paragraph.

  3. Call paint as often as desired to paint the paragraph.

  4. Call dispose when the object will no longer be accessed to release native resources. For TextPainter objects that are used repeatedly and stored on a State or RenderObject, call dispose from State.dispose or RenderObject.dispose or similar. For TextPainter objects that are only used ephemerally, it is safe to immediately dispose them after the last call to methods or properties on the object.

If the width of the area into which the text is being painted changes, return to step 2. If the text to be painted changes, return to step 1.

The default text style is white. To change the color of the text, pass a TextStyle object to the TextSpan in text.

Constructors

TextPainter({InlineSpan? text, TextAlign textAlign = TextAlign.start, TextDirection? textDirection, @Deprecated('Use textScaler instead. ' 'Use of textScaleFactor was deprecated in preparation for the upcoming nonlinear text scaling support. ' 'This feature was deprecated after v3.12.0-2.0.pre.') double textScaleFactor = 1.0, TextScaler textScaler = TextScaler.noScaling, int? maxLines, String? ellipsis, Locale? locale, StrutStyle? strutStyle, TextWidthBasis textWidthBasis = TextWidthBasis.parent, TextHeightBehavior? textHeightBehavior})
Creates a text painter that paints the given text.

Properties

debugDisposed bool
Whether this object has been disposed or not.
no setter
didExceedMaxLines bool
Whether any text was truncated or ellipsized.
no setter
ellipsis String?
The string used to ellipsize overflowing text. Setting this to a non-empty string will cause this string to be substituted for the remaining text if the text can not fit within the specified maximum width.
getter/setter pair
hashCode int
The hash code for this object.
no setterinherited
height double
The vertical space required to paint this text.
no setter
inlinePlaceholderBoxes List<TextBox>?
An ordered list of TextBoxes that bound the positions of the placeholders in the paragraph.
no setter
locale Locale?
The locale used to select region-specific glyphs.
getter/setter pair
maxIntrinsicWidth double
The width at which increasing the width of the text no longer decreases the height.
no setter
maxLines int?
An optional maximum number of lines for the text to span, wrapping if necessary.
getter/setter pair
minIntrinsicWidth double
The width at which decreasing the width of the text would prevent it from painting itself completely within its bounds.
no setter
plainText String
Returns a plain text version of the text to paint.
no setter
preferredLineHeight double
The height of a space in text in logical pixels.
no setter
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
size Size
The amount of space required to paint this text.
no setter
strutStyle StrutStyle?
The strut style to use. Strut style defines the strut, which sets minimum vertical layout metrics.
getter/setter pair
text InlineSpan?
The (potentially styled) text to paint.
getter/setter pair
textAlign TextAlign
How the text should be aligned horizontally.
getter/setter pair
textDirection TextDirection?
The default directionality of the text.
getter/setter pair
textHeightBehavior TextHeightBehavior?
Defines how to apply TextStyle.height over and under text.
getter/setter pair
textScaleFactor double
Deprecated. Will be removed in a future version of Flutter. Use textScaler instead.
getter/setter pair
textScaler TextScaler
The font scaling strategy to use when laying out and rendering the text.
getter/setter pair
textWidthBasis TextWidthBasis
Defines how to measure the width of the rendered text.
getter/setter pair
width double
The horizontal space required to paint this text.
no setter
wordBoundaries WordBoundary
Returns a TextBoundary that can be used to perform word boundary analysis on the current text.
no setter

Methods

computeDistanceToActualBaseline(TextBaseline baseline) double
Returns the distance from the top of the text to the first baseline of the given type.
computeLineMetrics() List<LineMetrics>
Returns the full list of LineMetrics that describe in detail the various metrics of each laid out line.
dispose() → void
Releases the resources associated with this painter.
getBoxesForSelection(TextSelection selection, {BoxHeightStyle boxHeightStyle = ui.BoxHeightStyle.tight, BoxWidthStyle boxWidthStyle = ui.BoxWidthStyle.tight}) List<TextBox>
Returns a list of rects that bound the given selection.
getClosestGlyphForOffset(Offset offset) GlyphInfo?
Returns the GlyphInfo of the glyph closest to the given offset in the paragraph coordinate system, or null if the text is empty, or is entirely clipped or ellipsized away.
getFullHeightForCaret(TextPosition position, Rect caretPrototype) double
Returns the strut bounded height of the glyph at the given position.
getLineBoundary(TextPosition position) TextRange
Returns the text range of the line at the given offset.
getOffsetAfter(int offset) int?
Returns the closest offset after offset at which the input cursor can be positioned.
getOffsetBefore(int offset) int?
Returns the closest offset before offset at which the input cursor can be positioned.
getOffsetForCaret(TextPosition position, Rect caretPrototype) Offset
Returns the offset at which to paint the caret.
getPositionForOffset(Offset offset) TextPosition
Returns the closest position within the text for the given pixel offset.
getWordBoundary(TextPosition position) TextRange
Returns the text range of the word at the given offset. Characters not part of a word, such as spaces, symbols, and punctuation, have word breaks on both sides. In such cases, this method will return a text range that contains the given text position.
layout({double minWidth = 0.0, double maxWidth = double.infinity}) → void
Computes the visual position of the glyphs for painting the text.
markNeedsLayout() → void
Marks this text painter's layout information as dirty and removes cached information.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
paint(Canvas canvas, Offset offset) → void
Paints the text onto the given canvas at the given offset.
setPlaceholderDimensions(List<PlaceholderDimensions>? value) → void
Sets the dimensions of each placeholder in text.
toString() String
A string representation of this object.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited

Static Methods

computeMaxIntrinsicWidth({required InlineSpan text, required TextDirection textDirection, TextAlign textAlign = TextAlign.start, double textScaleFactor = 1.0, TextScaler textScaler = TextScaler.noScaling, int? maxLines, String? ellipsis, Locale? locale, StrutStyle? strutStyle, TextWidthBasis textWidthBasis = TextWidthBasis.parent, TextHeightBehavior? textHeightBehavior, double minWidth = 0.0, double maxWidth = double.infinity}) double
Computes the max intrinsic width of a configured TextPainter.
computeWidth({required InlineSpan text, required TextDirection textDirection, TextAlign textAlign = TextAlign.start, double textScaleFactor = 1.0, TextScaler textScaler = TextScaler.noScaling, int? maxLines, String? ellipsis, Locale? locale, StrutStyle? strutStyle, TextWidthBasis textWidthBasis = TextWidthBasis.parent, TextHeightBehavior? textHeightBehavior, double minWidth = 0.0, double maxWidth = double.infinity}) double
Computes the width of a configured TextPainter.
isHighSurrogate(int value) bool
Returns true iff the given value is a valid UTF-16 high (first) surrogate. The value must be a UTF-16 code unit, meaning it must be in the range 0x0000-0xFFFF.
isLowSurrogate(int value) bool
Returns true iff the given value is a valid UTF-16 low (second) surrogate. The value must be a UTF-16 code unit, meaning it must be in the range 0x0000-0xFFFF.