MultiParagraph


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

Summary

Public constructors

MultiParagraph(
    intrinsics: MultiParagraphIntrinsics,
    constraints: Constraints,
    maxLines: Int,
    ellipsis: Boolean
)
Cmn
MultiParagraph(
    intrinsics: MultiParagraphIntrinsics,
    maxLines: Int,
    ellipsis: Boolean,
    width: Float
)

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

Cmn
MultiParagraph(
    annotatedString: AnnotatedString,
    style: TextStyle,
    constraints: Constraints,
    density: Density,
    fontFamilyResolver: FontFamily.Resolver,
    placeholders: List<AnnotatedString.Range<Placeholder>>,
    maxLines: Int,
    ellipsis: Boolean
)

Lays out a given annotatedString with the given constraints.

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

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

Cmn
MultiParagraph(
    annotatedString: AnnotatedString,
    style: TextStyle,
    width: Float,
    density: Density,
    fontFamilyResolver: FontFamily.Resolver,
    placeholders: List<AnnotatedString.Range<Placeholder>>,
    maxLines: Int,
    ellipsis: Boolean
)

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

Cmn

Public functions

FloatArray
fillBoundingBoxes(
    range: TextRange,
    array: FloatArray,
    arrayStart: @IntRange(from = 0) Int
)

Fills the bounding boxes for characters provided in the range into array.

Cmn
ResolvedTextDirection

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

Cmn
Rect

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

Cmn
Rect
getCursorRect(offset: Int)

Returns rectangle of the cursor area.

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

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

Cmn
Float
getLineBaseline(lineIndex: Int)

Returns the distance from the top of the MultiParagraph to the alphabetic baseline of the given line.

Cmn
Float
getLineBottom(lineIndex: Int)

Returns the bottom y coordinate of the given line.

Cmn
Int
getLineEnd(lineIndex: Int, visibleEnd: Boolean)

Returns the end offset of the given line

Cmn
Int

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

Cmn
Int

Returns line number closest to the given graphical vertical position.

Cmn
Float
getLineHeight(lineIndex: Int)

Returns the height of the given line.

Cmn
Float
getLineLeft(lineIndex: Int)

Returns the left x Coordinate of the given line.

Cmn
Float
getLineRight(lineIndex: Int)

Returns the right x Coordinate of the given line.

Cmn
Int
getLineStart(lineIndex: Int)

Returns the start offset of the given line, inclusive.

Cmn
Float
getLineTop(lineIndex: Int)

Returns the top y coordinate of the given line.

Cmn
Float
getLineWidth(lineIndex: Int)

Returns the width of the given line.

Cmn
Int

Returns the character offset closest to the given graphical position.

Cmn
ResolvedTextDirection

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

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

Returns path that enclose the given text range.

Cmn
TextRange

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

Cmn
Boolean
isLineEllipsized(lineIndex: Int)

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

Cmn
Unit
paint(
    canvas: Canvas,
    color: Color,
    shadow: Shadow?,
    decoration: TextDecoration?,
    drawStyle: DrawStyle?,
    blendMode: BlendMode
)

Paint the paragraphs to canvas.

Cmn
Unit
paint(
    canvas: Canvas,
    brush: Brush,
    alpha: Float,
    shadow: Shadow?,
    decoration: TextDecoration?,
    drawStyle: DrawStyle?,
    blendMode: BlendMode
)

Paint the paragraphs to canvas.

Cmn

Public properties

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.

Cmn
Float

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

Cmn
Float

The amount of vertical space this paragraph occupies.

Cmn
MultiParagraphIntrinsics

previously calculated text intrinsics

Cmn
Float

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

Cmn
Int

The total number of lines in the text.

Cmn
Float

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

Cmn
Int

the maximum number of lines that the text can have

Cmn
Float

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

Cmn
List<Rect?>

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

Cmn
Float

The amount of horizontal space this paragraph occupies.

Cmn

Public constructors

MultiParagraph

MultiParagraph(
    intrinsics: MultiParagraphIntrinsics,
    constraints: Constraints,
    maxLines: Int = DefaultMaxLines,
    ellipsis: Boolean = false
)
Parameters
intrinsics: MultiParagraphIntrinsics

previously calculated text intrinsics

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.

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

MultiParagraph

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

MultiParagraph

MultiParagraph(
    annotatedString: AnnotatedString,
    style: TextStyle,
    constraints: Constraints,
    density: Density,
    fontFamilyResolver: FontFamily.Resolver,
    placeholders: List<AnnotatedString.Range<Placeholder>> = listOf(),
    maxLines: Int = Int.MAX_VALUE,
    ellipsis: Boolean = false
)

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

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.

density: Density

density of the device

fontFamilyResolver: FontFamily.Resolver

to be used to load the font given in SpanStyles

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

Throws
kotlin.IllegalArgumentException

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

See also
Placeholder

MultiParagraph

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

Throws
kotlin.IllegalArgumentException

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

See also
Placeholder

MultiParagraph

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

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

width: Float

how wide the text is allowed to be

density: Density

density of the device

fontFamilyResolver: FontFamily.Resolver

to be used to load the font given in SpanStyles

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

Throws
kotlin.IllegalArgumentException

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

See also
Placeholder

Public functions

fillBoundingBoxes

fun fillBoundingBoxes(
    range: TextRange,
    array: FloatArray,
    arrayStart: @IntRange(from = 0) Int
): FloatArray

Fills the bounding boxes for characters provided in the range into array. The array is filled starting from arrayStart (inclusive). The coordinates are in local text layout coordinates.

The returned information consists of left/right of a character; line top and bottom for the same character.

For the grapheme consists of multiple code points, e.g. ligatures, combining marks, the first character has the total width and the remaining are returned as zero-width.

The array divided into segments of four where each index in that segment represents left, top, right, bottom of the character.

The size of the provided array should be greater or equal than the four times * TextRange length.

The final order of characters in the array is from TextRange.min to TextRange.max.

Parameters
range: TextRange

the TextRange representing the start and end indices in the Paragraph.

array: FloatArray

the array to fill in the values. The array divided into segments of four where each index in that segment represents left, top, right, bottom of the character.

arrayStart: @IntRange(from = 0) Int

the inclusive start index in the array where the function will start filling in the values from

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.

Returns
Float

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

getLineBaseline

fun getLineBaseline(lineIndex: Int): Float

Returns the distance from the top of the MultiParagraph to the alphabetic baseline of the given line.

getLineBottom

fun getLineBottom(lineIndex: Int): Float

Returns the bottom y coordinate of the given line.

getLineEnd

fun getLineEnd(lineIndex: Int, visibleEnd: Boolean = false): Int

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
lineIndex: Int

the line number

visibleEnd: Boolean = false

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

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.

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 the given line is ellipsized, otherwise returns false.

Parameters
lineIndex: Int

a 0 based line index

Returns
Boolean

true if the given line is ellipsized, otherwise false

paint

fun paint(
    canvas: Canvas,
    color: Color = Color.Unspecified,
    shadow: Shadow? = null,
    decoration: TextDecoration? = null,
    drawStyle: DrawStyle? = null,
    blendMode: BlendMode = DrawScope.DefaultBlendMode
): Unit

Paint the paragraphs to canvas.

paint

fun paint(
    canvas: Canvas,
    brush: Brush,
    alpha: Float = Float.NaN,
    shadow: Shadow? = null,
    decoration: TextDecoration? = null,
    drawStyle: DrawStyle? = null,
    blendMode: BlendMode = DrawScope.DefaultBlendMode
): Unit

Paint the paragraphs to canvas.

Public properties

didExceedMaxLines

val didExceedMaxLinesBoolean

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.

firstBaseline

val firstBaselineFloat

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

height

val heightFloat

The amount of vertical space this paragraph occupies.

Valid only after layout has been called.

intrinsics

val intrinsicsMultiParagraphIntrinsics

previously calculated text intrinsics

lastBaseline

val lastBaselineFloat

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

lineCount

val lineCountInt

The total number of lines in the text.

maxIntrinsicWidth

val maxIntrinsicWidthFloat

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

maxLines

val maxLinesInt

the maximum number of lines that the text can have

minIntrinsicWidth

val minIntrinsicWidthFloat

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

placeholderRects

val placeholderRectsList<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 widthFloat

The amount of horizontal space this paragraph occupies.