{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

MultiParagraph

public final class MultiParagraph


Lays out and renders multiple paragraphs at once. Unlike Paragraph, supports multiple ParagraphStyles in a given text.

Summary

Public constructors

MultiParagraph(
    @NonNull MultiParagraphIntrinsics intrinsics,
    @NonNull Constraints constraints,
    int maxLines,
    boolean ellipsis
)
MultiParagraph(
    @NonNull MultiParagraphIntrinsics intrinsics,
    int maxLines,
    boolean ellipsis,
    float width
)

This method is deprecated. MultiParagraph that takes maximum allowed width is deprecated, pass constraints instead.

MultiParagraph(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextStyle style,
    @NonNull Constraints constraints,
    @NonNull Density density,
    @NonNull FontFamily.Resolver fontFamilyResolver,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders,
    int maxLines,
    boolean ellipsis
)

Lays out a given annotatedString with the given constraints.

MultiParagraph(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextStyle style,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders,
    int maxLines,
    boolean ellipsis,
    float width,
    @NonNull Density density,
    @NonNull Font.ResourceLoader resourceLoader
)

This method is deprecated. Font.ResourceLoader is deprecated, use fontFamilyResolver instead

MultiParagraph(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextStyle style,
    float width,
    @NonNull Density density,
    @NonNull FontFamily.Resolver fontFamilyResolver,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders,
    int maxLines,
    boolean ellipsis
)

This method is deprecated. MultiParagraph that takes maximum allowed width is deprecated, pass constraints instead.

Public methods

final @NonNull ResolvedTextDirection
getBidiRunDirection(int offset)

Get the text direction of the character at the given offset.

final @NonNull Rect
getBoundingBox(int offset)

Returns the bounding box as Rect of the character for given character offset.

final @NonNull Rect
getCursorRect(int offset)

Returns rectangle of the cursor area.

final boolean

True if there is more vertical content, but the text was truncated, either because we reached maxLines lines of text or because the maxLines was null, ellipsis was not null, and one of the lines exceeded the width constraint.

final float

The distance from the top of the paragraph to the alphabetic baseline of the first line, in logical pixels.

final float

The amount of vertical space this paragraph occupies.

final float
getHorizontalPosition(int offset, boolean usePrimaryDirection)

Compute the horizontal position where a newly inserted character at offset would be.

final @NonNull MultiParagraphIntrinsics

previously calculated text intrinsics

final float

The distance from the top of the paragraph to the alphabetic baseline of the first line, in logical pixels.

final float
getLineBottom(int lineIndex)

Returns the bottom y coordinate of the given line.

final int

The total number of lines in the text.

final int
getLineEnd(int lineIndex, boolean visibleEnd)

Returns the end offset of the given line

final int
getLineForOffset(int offset)

Returns the line number on which the specified text offset appears.

final int

Returns line number closest to the given graphical vertical position.

final float
getLineHeight(int lineIndex)

Returns the height of the given line.

final float
getLineLeft(int lineIndex)

Returns the left x Coordinate of the given line.

final float
getLineRight(int lineIndex)

Returns the right x Coordinate of the given line.

final int
getLineStart(int lineIndex)

Returns the start offset of the given line, inclusive.

final float
getLineTop(int lineIndex)

Returns the top y coordinate of the given line.

final float
getLineWidth(int lineIndex)

Returns the width of the given line.

final float

Returns the smallest width beyond which increasing the width never decreases the height.

final int

the maximum number of lines that the text can have

final float

The width for text if all soft wrap opportunities were taken.

final int

Returns the character offset closest to the given graphical position.

final @NonNull ResolvedTextDirection

Get the text direction of the paragraph containing the given offset.

final @NonNull Path
getPathForRange(int start, int end)

Returns path that enclose the given text range.

final @NonNull List<Rect>

The bounding boxes reserved for the input placeholders in this MultiParagraph.

final float

The amount of horizontal space this paragraph occupies.

final @NonNull TextRange
getWordBoundary(int offset)

Returns the TextRange of the word at the given character offset.

final boolean
isLineEllipsized(int lineIndex)

Returns true if the given line is ellipsized, otherwise returns false.

final void
paint(
    @NonNull Canvas canvas,
    @NonNull Color color,
    Shadow shadow,
    TextDecoration decoration,
    DrawStyle drawStyle,
    @NonNull BlendMode blendMode
)

Paint the paragraphs to canvas.

final void
paint(
    @NonNull Canvas canvas,
    @NonNull Brush brush,
    float alpha,
    Shadow shadow,
    TextDecoration decoration,
    DrawStyle drawStyle,
    @NonNull BlendMode blendMode
)

Paint the paragraphs to canvas.

Public constructors

MultiParagraph

public MultiParagraph(
    @NonNull MultiParagraphIntrinsics intrinsics,
    @NonNull Constraints constraints,
    int maxLines,
    boolean ellipsis
)
Parameters
@NonNull MultiParagraphIntrinsics intrinsics

previously calculated text intrinsics

@NonNull Constraints constraints

how wide and tall the text is allowed to be. Constraints.maxWidth will define the width of the MultiParagraph. Constraints.maxHeight helps defining the number of lines that fit with ellipsis is true. Minimum components of the Constraints object are no-op.

int maxLines

the maximum number of lines that the text can have

boolean ellipsis

whether to ellipsize text, applied only when maxLines is set

MultiParagraph

public MultiParagraph(
    @NonNull MultiParagraphIntrinsics intrinsics,
    int maxLines,
    boolean ellipsis,
    float width
)

Lays out and renders multiple paragraphs at once. Unlike Paragraph, supports multiple ParagraphStyles in a given text.

Parameters
@NonNull MultiParagraphIntrinsics intrinsics

previously calculated text intrinsics

int maxLines

the maximum number of lines that the text can have

boolean ellipsis

whether to ellipsize text, applied only when maxLines is set

float width

how wide the text is allowed to be

MultiParagraph

public MultiParagraph(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextStyle style,
    @NonNull Constraints constraints,
    @NonNull Density density,
    @NonNull FontFamily.Resolver fontFamilyResolver,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders,
    int maxLines,
    boolean ellipsis
)

Lays out a given annotatedString with the given constraints. Unlike a Paragraph, MultiParagraph can handle a text what has multiple paragraph styles.

Parameters
@NonNull AnnotatedString annotatedString

the text to be laid out

@NonNull TextStyle style

the TextStyle to be applied to the whole text

@NonNull Constraints constraints

how wide and tall the text is allowed to be. Constraints.maxWidth will define the width of the MultiParagraph. Constraints.maxHeight helps defining the number of lines that fit with ellipsis is true. Minimum components of the Constraints object are no-op.

@NonNull Density density

density of the device

@NonNull FontFamily.Resolver fontFamilyResolver

to be used to load the font given in SpanStyles

@NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders

a list of Placeholders that specify ranges of text which will be skipped during layout and replaced with Placeholder. It's required that the range of each Placeholder doesn't cross paragraph boundary, otherwise IllegalArgumentException is thrown.

int maxLines

the maximum number of lines that the text can have

boolean ellipsis

whether to ellipsize text, applied only when maxLines is set

Throws
kotlin.IllegalArgumentException

if ParagraphStyle.textDirection is not set, or any of the placeholders crosses paragraph boundary.

See also
Placeholder

MultiParagraph

public MultiParagraph(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextStyle style,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders,
    int maxLines,
    boolean ellipsis,
    float width,
    @NonNull Density density,
    @NonNull Font.ResourceLoader resourceLoader
)

Lays out a given annotatedString with the given constraints. Unlike a Paragraph, MultiParagraph can handle a text what has multiple paragraph styles.

Parameters
@NonNull AnnotatedString annotatedString

the text to be laid out

@NonNull TextStyle style

the TextStyle to be applied to the whole text

@NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders

a list of Placeholders that specify ranges of text which will be skipped during layout and replaced with Placeholder. It's required that the range of each Placeholder doesn't cross paragraph boundary, otherwise IllegalArgumentException is thrown.

int maxLines

the maximum number of lines that the text can have

boolean ellipsis

whether to ellipsize text, applied only when maxLines is set

float width

how wide the text is allowed to be

@NonNull Density density

density of the device

@NonNull Font.ResourceLoader resourceLoader

Font.ResourceLoader to be used to load the font given in SpanStyles

Throws
kotlin.IllegalArgumentException

if ParagraphStyle.textDirection is not set, or any of the placeholders crosses paragraph boundary.

See also
Placeholder

MultiParagraph

public MultiParagraph(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextStyle style,
    float width,
    @NonNull Density density,
    @NonNull FontFamily.Resolver fontFamilyResolver,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders,
    int maxLines,
    boolean ellipsis
)

Lays out a given annotatedString with the given constraints. Unlike a Paragraph, MultiParagraph can handle a text what has multiple paragraph styles.

Parameters
@NonNull AnnotatedString annotatedString

the text to be laid out

@NonNull TextStyle style

the TextStyle to be applied to the whole text

float width

how wide the text is allowed to be

@NonNull Density density

density of the device

@NonNull FontFamily.Resolver fontFamilyResolver

to be used to load the font given in SpanStyles

@NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders

a list of Placeholders that specify ranges of text which will be skipped during layout and replaced with Placeholder. It's required that the range of each Placeholder doesn't cross paragraph boundary, otherwise IllegalArgumentException is thrown.

int maxLines

the maximum number of lines that the text can have

boolean ellipsis

whether to ellipsize text, applied only when maxLines is set

Throws
kotlin.IllegalArgumentException

if ParagraphStyle.textDirection is not set, or any of the placeholders crosses paragraph boundary.

See also
Placeholder

Public methods

getBidiRunDirection

public final @NonNull ResolvedTextDirection getBidiRunDirection(int offset)

Get the text direction of the character at the given offset.

getBoundingBox

public final @NonNull Rect getBoundingBox(int offset)

Returns the bounding box as Rect of the character for given character offset. Rect includes the top, bottom, left and right of a character.

getCursorRect

public final @NonNull Rect getCursorRect(int offset)

Returns rectangle of the cursor area.

getDidExceedMaxLines

public final boolean getDidExceedMaxLines()

True if there is more vertical content, but the text was truncated, either because we reached maxLines lines of text or because the maxLines was null, ellipsis was not null, and one of the lines exceeded the width constraint.

getFirstBaseline

public final float getFirstBaseline()

The distance from the top of the paragraph to the alphabetic baseline of the first line, in logical pixels.

getHeight

public final float getHeight()

The amount of vertical space this paragraph occupies.

Valid only after layout has been called.

getHorizontalPosition

public final float getHorizontalPosition(int offset, boolean usePrimaryDirection)

Compute the horizontal position where a newly inserted character at offset would be.

If the inserted character at offset is within a LTR/RTL run, the returned position will be the left(right) edge of the character.

For example:
Paragraph's direction is LTR.
Text in logic order: L0 L1 L2 R3 R4 R5
Text in visual order: L0 L1 L2 R5 R4 R3
position of the offset(2): |
position of the offset(4): |

However, when the offset is at the BiDi transition offset, there will be two possible visual positions, which depends on the direction of the inserted character.

For example:
Paragraph's direction is LTR.
Text in logic order: L0 L1 L2 R3 R4 R5
Text in visual order: L0 L1 L2 R5 R4 R3
position of the offset(3): | (The inserted character is LTR)
| (The inserted character is RTL)

In this case, usePrimaryDirection will be used to resolve the ambiguity. If true, the inserted character's direction is assumed to be the same as Paragraph's direction. Otherwise, the inserted character's direction is assumed to be the opposite of the Paragraph's direction.

For example:
Paragraph's direction is LTR.
Text in logic order: L0 L1 L2 R3 R4 R5
Text in visual order: L0 L1 L2 R5 R4 R3
position of the offset(3): | (usePrimaryDirection is true)
| (usePrimaryDirection is false)

This method is useful to compute cursor position.

Parameters
int offset

the offset of the character, in the range of 0, length.

boolean usePrimaryDirection

whether the paragraph direction is respected when offset points to a BiDi transition point.

Returns
float

a float number representing the horizontal position in the unit of pixel.

getIntrinsics

public final @NonNull MultiParagraphIntrinsics getIntrinsics()

previously calculated text intrinsics

getLastBaseline

public final float getLastBaseline()

The distance from the top of the paragraph to the alphabetic baseline of the first line, in logical pixels.

getLineBottom

public final float getLineBottom(int lineIndex)

Returns the bottom y coordinate of the given line.

getLineCount

public final int getLineCount()

The total number of lines in the text.

getLineEnd

public final int getLineEnd(int lineIndex, boolean visibleEnd)

Returns the end offset of the given line

Characters being ellipsized are treated as invisible characters. So that if visibleEnd is false, it will return line end including the ellipsized characters and vice verse.

Parameters
int lineIndex

the line number

boolean visibleEnd

if true, the returned line end will not count trailing whitespaces or linefeed characters. Otherwise, this function will return the logical line end. By default it's false.

Returns
int

an exclusive end offset of the line.

getLineForOffset

public final int getLineForOffset(int offset)

Returns the line number on which the specified text offset appears. If you ask for a position before 0, you get 0; if you ask for a position beyond the end of the text, you get the last line.

getLineForVerticalPosition

public final int getLineForVerticalPosition(float vertical)

Returns line number closest to the given graphical vertical position. If you ask for a vertical position before 0, you get 0; if you ask for a vertical position beyond the last line, you get the last line.

getLineHeight

public final float getLineHeight(int lineIndex)

Returns the height of the given line.

getLineLeft

public final float getLineLeft(int lineIndex)

Returns the left x Coordinate of the given line.

getLineRight

public final float getLineRight(int lineIndex)

Returns the right x Coordinate of the given line.

getLineStart

public final int getLineStart(int lineIndex)

Returns the start offset of the given line, inclusive.

getLineTop

public final float getLineTop(int lineIndex)

Returns the top y coordinate of the given line.

getLineWidth

public final float getLineWidth(int lineIndex)

Returns the width of the given line.

getMaxIntrinsicWidth

public final float getMaxIntrinsicWidth()

Returns the smallest width beyond which increasing the width never decreases the height.

getMaxLines

public final int getMaxLines()

the maximum number of lines that the text can have

getMinIntrinsicWidth

public final float getMinIntrinsicWidth()

The width for text if all soft wrap opportunities were taken.

getOffsetForPosition

public final int getOffsetForPosition(@NonNull Offset position)

Returns the character offset closest to the given graphical position.

getParagraphDirection

public final @NonNull ResolvedTextDirection getParagraphDirection(int offset)

Get the text direction of the paragraph containing the given offset.

getPathForRange

public final @NonNull Path getPathForRange(int start, int end)

Returns path that enclose the given text range.

getPlaceholderRects

public final @NonNull List<RectgetPlaceholderRects()

The bounding boxes reserved for the input placeholders in this MultiParagraph. Their locations are relative to this MultiParagraph's coordinate. The order of this list corresponds to that of input placeholders. Notice that Rect in placeholderRects is nullable. When Rect is null, it indicates that the corresponding Placeholder is ellipsized.

getWidth

public final float getWidth()

The amount of horizontal space this paragraph occupies.

getWordBoundary

public final @NonNull TextRange getWordBoundary(int offset)

Returns the TextRange of the word at the given character 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 TextRange(offset, offset+1). Word boundaries are defined more precisely in Unicode Standard Annex #29 http://www.unicode.org/reports/tr29/#Word_Boundaries

isLineEllipsized

public final boolean isLineEllipsized(int lineIndex)

Returns true if the given line is ellipsized, otherwise returns false.

Parameters
int lineIndex

a 0 based line index

Returns
boolean

true if the given line is ellipsized, otherwise false

paint

public final void paint(
    @NonNull Canvas canvas,
    @NonNull Color color,
    Shadow shadow,
    TextDecoration decoration,
    DrawStyle drawStyle,
    @NonNull BlendMode blendMode
)

Paint the paragraphs to canvas.

paint

public final void paint(
    @NonNull Canvas canvas,
    @NonNull Brush brush,
    float alpha,
    Shadow shadow,
    TextDecoration decoration,
    DrawStyle drawStyle,
    @NonNull BlendMode blendMode
)

Paint the paragraphs to canvas.