MultiParagraph

Kotlin |Java

class MultiParagraph

kotlin.Any
↳	androidx.compose.ui.text.MultiParagraph

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

Summary

Public constructors
<init>(annotatedString: AnnotatedString, style: TextStyle, placeholders: List<AnnotatedString.Range<Placeholder>> = listOf(), maxLines: Int = Int.MAX_VALUE, ellipsis: Boolean = false, width: Float, density: Density, resourceLoader: Font.ResourceLoader) Lays out a given annotatedString with the given constraints.
<init>(intrinsics: MultiParagraphIntrinsics, maxLines: Int = DefaultMaxLines, ellipsis: Boolean = false, width: Float) Lays out and renders multiple paragraphs at once.

Public methods
ResolvedTextDirection	getBidiRunDirection(offset: Int) Get the text direction of the character at the given offset.
Rect	getBoundingBox(offset: Int) Returns the bounding box as Rect of the character for given character offset.
Rect	getCursorRect(offset: Int) Returns rectangle of the cursor area.
Float	getHorizontalPosition(offset: Int, usePrimaryDirection: Boolean) Compute the horizontal position where a newly inserted character at offset would be.
Float	getLineBottom(lineIndex: Int) Returns the bottom y coordinate of the given line.
Int	getLineEnd(lineIndex: Int) Returns the end offset of the given line
Int	getLineForOffset(offset: Int) Returns the line number on which the specified text offset appears.
Int	getLineForVerticalPosition(vertical: Float) Returns line number closest to the given graphical vertical position.
Float	getLineHeight(lineIndex: Int) Returns the height of the given line.
Float	getLineLeft(lineIndex: Int) Returns the left x Coordinate of the given line.
Float	getLineRight(lineIndex: Int) Returns the right x Coordinate of the given line.
Int	getLineStart(lineIndex: Int) Returns the start offset of the given line, inclusive.
Float	getLineTop(lineIndex: Int) Returns the top y coordinate of the given line.
Int	getLineVisibleEnd(lineIndex: Int) Returns the end of visible offset of the given line.
Float	getLineWidth(lineIndex: Int) Returns the width of the given line.
Int	getOffsetForPosition(position: Offset) Returns the character offset closest to the given graphical position.
ResolvedTextDirection	getParagraphDirection(offset: Int) Get the text direction of the paragraph containing the given offset.
Path	getPathForRange(start: Int, end: Int) Returns path that enclose the given text range.
TextRange	getWordBoundary(offset: Int) Returns the TextRange of the word at the given character offset.
Boolean	isLineEllipsized(lineIndex: Int) Returns true if ellipsis happens on the given line, otherwise returns false
Unit	paint(canvas: Canvas, color: Color = Color.Unspecified, shadow: Shadow? = null, decoration: TextDecoration? = null) Paint the paragraphs to canvas.

Properties
Boolean	didExceedMaxLines 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.
Float	firstBaseline The distance from the top of the paragraph to the alphabetic baseline of the first line, in logical pixels.
Float	height The amount of vertical space this paragraph occupies.
MultiParagraphIntrinsics	intrinsics previously calculated text intrinsics
Float	lastBaseline The distance from the top of the paragraph to the alphabetic baseline of the first line, in logical pixels.
Int	lineCount The total number of lines in the text.
Float	maxIntrinsicWidth Returns the smallest width beyond which increasing the width never decreases the height.
Int	maxLines the maximum number of lines that the text can have
Float	minIntrinsicWidth The width for text if all soft wrap opportunities were taken.
List<Rect?>	placeholderRects The bounding boxes reserved for the input placeholders in this MultiParagraph.
Float	width The amount of horizontal space this paragraph occupies.

Public constructors

<init>

MultiParagraph(
    annotatedString: AnnotatedString, 
    style: TextStyle, 
    placeholders: List<AnnotatedString.Range<Placeholder>> = listOf(), 
    maxLines: Int = Int.MAX_VALUE, 
    ellipsis: Boolean = false, 
    width: Float, 
    density: Density, 
    resourceLoader: Font.ResourceLoader)

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

Parameters
annotatedString: AnnotatedString	the text to be laid out
style: TextStyle	the TextStyle to be applied to the whole text
placeholders: List<AnnotatedString.Range<Placeholder>> = listOf()	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.
maxLines: Int = Int.MAX_VALUE	the maximum number of lines that the text can have
ellipsis: Boolean = false	whether to ellipsize text, applied only when maxLines is set
width: Float	how wide the text is allowed to be
density: Density	density of the device
resourceLoader: Font.ResourceLoader	Font.ResourceLoader to be used to load the font given in SpanStyles

See Also

• Placeholder

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

<init>

MultiParagraph(
    intrinsics: MultiParagraphIntrinsics, 
    maxLines: Int = DefaultMaxLines, 
    ellipsis: Boolean = false, 
    width: Float)

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

Parameters
intrinsics: MultiParagraphIntrinsics	previously calculated text intrinsics
maxLines: Int = DefaultMaxLines	the maximum number of lines that the text can have
ellipsis: Boolean = false	whether to ellipsize text, applied only when maxLines is set
width: Float	how wide the text is allowed to be

Public methods

getBidiRunDirection

fun getBidiRunDirection(offset: Int): ResolvedTextDirection

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

getBoundingBox

fun getBoundingBox(offset: Int): Rect

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

fun getCursorRect(offset: Int): Rect

Returns rectangle of the cursor area.

getHorizontalPosition

fun getHorizontalPosition(
    offset: Int, 
    usePrimaryDirection: Boolean
): Float

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
offset: Int	the offset of the character, in the range of 0,length.
usePrimaryDirection: Boolean	whether the paragraph direction is respected when offset points to a BiDi transition point.

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

getLineBottom

fun getLineBottom(lineIndex: Int): Float

Returns the bottom y coordinate of the given line.

getLineEnd

fun getLineEnd(lineIndex: Int): Int

Returns the end offset of the given line

If ellipsis happens on the given line, this returns the end of text since ellipsized characters are counted into the same line.

Parameters
lineIndex: Int	the line number

Return
an exclusive end offset of the line.

See Also

• getLineVisibleEnd

getLineForOffset

fun getLineForOffset(offset: Int): Int

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

fun getLineForVerticalPosition(vertical: Float): Int

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

fun getLineHeight(lineIndex: Int): Float

Returns the height of the given line.

getLineLeft

fun getLineLeft(lineIndex: Int): Float

Returns the left x Coordinate of the given line.

getLineRight

fun getLineRight(lineIndex: Int): Float

Returns the right x Coordinate of the given line.

getLineStart

fun getLineStart(lineIndex: Int): Int

Returns the start offset of the given line, inclusive.

getLineTop

fun getLineTop(lineIndex: Int): Float

Returns the top y coordinate of the given line.

getLineVisibleEnd

fun getLineVisibleEnd(lineIndex: Int): Int

Returns the end of visible offset of the given line.

If no ellipsis happens on the given line, this returns the line end offset with excluding trailing whitespaces. If ellipsis happens on the given line, this returns the offset that ellipsis started, i.e. the exclusive not ellipsized last character.

Parameters
lineIndex: Int	a 0 based line index

Return
an exclusive line end offset that is visible on the display

See Also

• getLineEnd

getLineWidth

fun getLineWidth(lineIndex: Int): Float

Returns the width of the given line.

getOffsetForPosition

fun getOffsetForPosition(position: Offset): Int

Returns the character offset closest to the given graphical position.

getParagraphDirection

fun getParagraphDirection(offset: Int): ResolvedTextDirection

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

getPathForRange

fun getPathForRange(
    start: Int, 
    end: Int
): Path

Returns path that enclose the given text range.

getWordBoundary

fun getWordBoundary(offset: Int): TextRange

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

fun isLineEllipsized(lineIndex: Int): Boolean

Returns true if ellipsis happens on the given line, otherwise returns false

Parameters
lineIndex: Int	a 0 based line index

Return
true if ellipsis happens on the given line,	otherwise false

paint

fun paint(
    canvas: Canvas, 
    color: Color = Color.Unspecified, 
    shadow: Shadow? = null, 
    decoration: TextDecoration? = null
): Unit

Paint the paragraphs to canvas.

Properties

didExceedMaxLines

val didExceedMaxLines: 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.

See the discussion of the maxLines and ellipsis arguments at ParagraphStyle.

firstBaseline

val firstBaseline: Float

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

height

val height: Float

The amount of vertical space this paragraph occupies.

Valid only after layout has been called.

intrinsics

val intrinsics: MultiParagraphIntrinsics

previously calculated text intrinsics

lastBaseline

val lastBaseline: Float

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

lineCount

val lineCount: Int

The total number of lines in the text.

maxIntrinsicWidth

val maxIntrinsicWidth: Float

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

maxLines

val maxLines: Int

the maximum number of lines that the text can have

minIntrinsicWidth

val minIntrinsicWidth: Float

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

placeholderRects

val placeholderRects: List<Rect?>

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.

width

val width: Float

The amount of horizontal space this paragraph occupies.