Paragraph

Interface

Common

@JvmDefaultWithCompatibility
expect sealed interface Paragraph

A paragraph of text that is laid out.

Paragraphs can be displayed on a Canvas using the paint method.

Properties

Common

val width: Float

The amount of horizontal space this paragraph occupies.

Common

val height: Float

The amount of vertical space this paragraph occupies.

Common

val minIntrinsicWidth: Float

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

Common

val maxIntrinsicWidth: Float

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

Common

val firstBaseline: Float

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

Common

val lastBaseline: Float

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

Common

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.

Common

val lineCount: Int

The total number of lines in the text.

Common

val placeholderRects: List<Rect?>

The bounding boxes reserved for the input placeholders in this Paragraphs. Their locations are relative to this Paragraph'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.

Functions

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

Returns path that enclose the given text range.

fun getCursorRect(offset: Int): Rect

Returns rectangle of the cursor area.

fun getLineLeft(lineIndex: Int): Float

Returns the left x Coordinate of the given line.

fun getLineRight(lineIndex: Int): Float

Returns the right x Coordinate of the given line.

fun getLineTop(lineIndex: Int): Float

Returns the bottom y coordinate of the given line.

fun getLineBaseline(lineIndex: Int): Float

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

fun getLineBottom(lineIndex: Int): Float

Returns the bottom y coordinate of the given line.

fun getLineHeight(lineIndex: Int): Float

Returns the height of the given line.

fun getLineWidth(lineIndex: Int): Float

Returns the width of the given line.

fun getLineStart(lineIndex: Int): Int

Returns the start offset of the given line, inclusive.

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	the line number
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


	an exclusive end offset of the line.

fun isLineEllipsized(lineIndex: Int): Boolean

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

Parameters


lineIndex	a 0 based line index

Returns


	true if the given line is ellipsized, otherwise false

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.

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

Returns


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

fun getParagraphDirection(offset: Int): ResolvedTextDirection

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

fun getBidiRunDirection(offset: Int): ResolvedTextDirection

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

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.

fun getOffsetForPosition(position: Offset): Int

Returns the character offset closest to the given graphical position.

fun getRangeForRect(
        rect: Rect,
        granularity: TextGranularity,
        inclusionStrategy: TextInclusionStrategy,
    ): TextRange

Find the range of text which is inside the specified rect. This method will break text into small text segments based on the given granularity such as character or word. It also support different inclusionStrategy, which determines when a small text segments is considered as inside the rect. Note that the word/character breaking is both operating system and language dependent. In the certain cases, the text may be break into smaller segments than the specified the granularity. If a text segment spans multiple lines or multiple directional runs (e.g. a hyphenated word), the text segment is divided into pieces at the line and run breaks, then the text segment is considered to be inside the area if any of its pieces are inside the area.

Parameters


rect	the rectangle area in which the text range will be found.
granularity	the granularity of the text, it controls how text is segmented.
inclusionStrategy	the strategy that determines whether a range of text's bounds is inside the given `rect` or not.

Returns


	the `TextRange` that is inside the given `rect`, or `TextRange.Zero` if no text is found.

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.

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

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	the `TextRange` representing the start and end indices in the `Paragraph`.
array	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	the inclusive start index in the array where the function will start filling in the values from

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). Word boundaries are defined more precisely in Unicode Standard Annex #29 http://www.unicode.org/reports/tr29/#Word_Boundaries

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

Draws this paragraph onto given canvas while modifying supported draw properties. Any change caused by overriding parameters are permanent, meaning that they affect the subsequent paint calls.

Parameters


canvas	Canvas to draw this paragraph on.
color	Applies to the default text paint color that's used by this paragraph. Text color spans are not affected. `Color.Unspecified` is treated as no-op.
shadow	Applies to the default text paint shadow that's used by this paragraph. Text shadow spans are not affected. `Shadow.None` removes any existing shadow on this paragraph, `null` does not change the currently set `Shadow` configuration.
textDecoration	Applies to the default text paint that's used by this paragraph. Spans that specify a TextDecoration are not affected. `TextDecoration.None` removes any existing TextDecoration on this paragraph, `null` does not change the currently set `TextDecoration` configuration.

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

Draws this paragraph onto given canvas while modifying supported draw properties. Any change caused by overriding parameters are permanent, meaning that they affect the subsequent paint calls.

Parameters


canvas	Canvas to draw this paragraph on.
color	Applies to the default text paint color that's used by this paragraph. Text color spans are not affected. `Color.Unspecified` is treated as no-op.
shadow	Applies to the default text paint shadow that's used by this paragraph. Text shadow spans are not affected. `Shadow.None` removes any existing shadow on this paragraph, `null` does not change the currently set `Shadow` configuration.
textDecoration	Applies to the default text paint that's used by this paragraph. Spans that specify a TextDecoration are not affected. `TextDecoration.None` removes any existing TextDecoration on this paragraph, `null` does not change the currently set `TextDecoration` configuration.
drawStyle	Applies to the default text paint style that's used by this paragraph. Spans that specify a DrawStyle are not affected. Passing this value as `null` does not change the currently set DrawStyle.
blendMode	Blending algorithm to be applied to the Paragraph while painting.

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

Draws this paragraph onto given canvas while modifying supported draw properties. Any change caused by overriding parameters are permanent, meaning that they affect the subsequent paint calls.

Parameters


canvas	Canvas to draw this paragraph on.
brush	Applies to the default text paint shader that's used by this paragraph. Text brush spans are not affected. If brush is type of `SolidColor`, color's alpha value is modulated by `alpha` parameter and gets applied as a color. If brush is type of `ShaderBrush`, its internal shader is created using this paragraph's layout size.
alpha	Applies to the default text paint alpha that's used by this paragraph. Text alpha spans are not affected. `Float.NaN` is treated as no-op. All other values are coerced into `0f, 1f` range.
shadow	Applies to the default text paint shadow that's used by this paragraph. Text shadow spans are not affected. `Shadow.None` removes any existing shadow on this paragraph, `null` does not change the currently set `Shadow` configuration.
textDecoration	Applies to the default text paint that's used by this paragraph. Spans that specify a TextDecoration are not affected. `TextDecoration.None` removes any existing TextDecoration on this paragraph, `null` does not change the currently set `TextDecoration` configuration.
drawStyle	Applies to the default text paint style that's used by this paragraph. Spans that specify a DrawStyle are not affected. Passing this value as `null` does not change the currently set DrawStyle.
blendMode	Blending algorithm to be applied to the Paragraph while painting.

Android

@JvmDefaultWithCompatibility
actual sealed interface Paragraph

Properties

Android

actual val width: Float

Android

actual val height: Float

Android

actual val minIntrinsicWidth: Float

Android

actual val maxIntrinsicWidth: Float

Android

actual val firstBaseline: Float

Android

actual val lastBaseline: Float

Android

actual val didExceedMaxLines: Boolean

Android

actual val lineCount: Int

Android

actual val placeholderRects: List<Rect?>

Functions

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

actual fun getCursorRect(offset: Int): Rect

actual fun getLineLeft(lineIndex: Int): Float

actual fun getLineRight(lineIndex: Int): Float

actual fun getLineTop(lineIndex: Int): Float

actual fun getLineBaseline(lineIndex: Int): Float

actual fun getLineBottom(lineIndex: Int): Float

actual fun getLineHeight(lineIndex: Int): Float

actual fun getLineWidth(lineIndex: Int): Float

actual fun getLineStart(lineIndex: Int): Int

actual fun getLineEnd(lineIndex: Int, visibleEnd: Boolean): Int

actual fun isLineEllipsized(lineIndex: Int): Boolean

actual fun getLineForOffset(offset: Int): Int

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

actual fun getParagraphDirection(offset: Int): ResolvedTextDirection

actual fun getBidiRunDirection(offset: Int): ResolvedTextDirection

actual fun getLineForVerticalPosition(vertical: Float): Int

actual fun getOffsetForPosition(position: Offset): Int

actual fun getRangeForRect(
        rect: Rect,
        granularity: TextGranularity,
        inclusionStrategy: TextInclusionStrategy,
    ): TextRange

actual fun getBoundingBox(offset: Int): Rect

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

actual fun getWordBoundary(offset: Int): TextRange

actual fun paint(canvas: Canvas, color: Color, shadow: Shadow?, textDecoration: TextDecoration?)

actual fun paint(
        canvas: Canvas,
        color: Color,
        shadow: Shadow?,
        textDecoration: TextDecoration?,
        drawStyle: DrawStyle?,
        blendMode: BlendMode,
    )

actual fun paint(
        canvas: Canvas,
        brush: Brush,
        alpha: Float,
        shadow: Shadow?,
        textDecoration: TextDecoration?,
        drawStyle: DrawStyle?,
        blendMode: BlendMode,
    )