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

Paragraph

public sealed interface Paragraph


A paragraph of text that is laid out.

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

Summary

Public methods

abstract @NonNull ResolvedTextDirection
getBidiRunDirection(int offset)

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

abstract @NonNull Rect
getBoundingBox(int offset)

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

abstract @NonNull Rect
getCursorRect(int offset)

Returns rectangle of the cursor area.

abstract 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.

abstract float

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

abstract float

The amount of vertical space this paragraph occupies.

abstract float
getHorizontalPosition(int offset, boolean usePrimaryDirection)

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

abstract float

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

abstract float
getLineBottom(int lineIndex)

Returns the bottom y coordinate of the given line.

abstract int

The total number of lines in the text.

abstract int
getLineEnd(int lineIndex, boolean visibleEnd)

Returns the end offset of the given line

abstract int
getLineForOffset(int offset)

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

abstract int

Returns line number closest to the given graphical vertical position.

abstract float
getLineHeight(int lineIndex)

Returns the height of the given line.

abstract float
getLineLeft(int lineIndex)

Returns the left x Coordinate of the given line.

abstract float
getLineRight(int lineIndex)

Returns the right x Coordinate of the given line.

abstract int
getLineStart(int lineIndex)

Returns the start offset of the given line, inclusive.

abstract float
getLineTop(int lineIndex)

Returns the bottom y coordinate of the given line.

abstract float
getLineWidth(int lineIndex)

Returns the width of the given line.

abstract float

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

abstract float

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

abstract int

Returns the character offset closest to the given graphical position.

abstract @NonNull ResolvedTextDirection

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

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

Returns path that enclose the given text range.

abstract @NonNull List<Rect>

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

abstract float

The amount of horizontal space this paragraph occupies.

abstract @NonNull TextRange
getWordBoundary(int offset)

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

abstract boolean
isLineEllipsized(int lineIndex)

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

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

Draws this paragraph onto given canvas while modifying supported draw properties.

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

Draws this paragraph onto given canvas while modifying supported draw properties.

Public methods

getBidiRunDirection

abstract @NonNull ResolvedTextDirection getBidiRunDirection(int offset)

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

getBoundingBox

abstract @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

abstract @NonNull Rect getCursorRect(int offset)

Returns rectangle of the cursor area.

getDidExceedMaxLines

abstract 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.

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

getFirstBaseline

abstract float getFirstBaseline()

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

getHeight

abstract float getHeight()

The amount of vertical space this paragraph occupies.

getHorizontalPosition

abstract 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.

getLastBaseline

abstract float getLastBaseline()

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

getLineBottom

abstract float getLineBottom(int lineIndex)

Returns the bottom y coordinate of the given line.

getLineCount

abstract int getLineCount()

The total number of lines in the text.

getLineEnd

abstract 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

abstract 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

abstract 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

abstract float getLineHeight(int lineIndex)

Returns the height of the given line.

getLineLeft

abstract float getLineLeft(int lineIndex)

Returns the left x Coordinate of the given line.

getLineRight

abstract float getLineRight(int lineIndex)

Returns the right x Coordinate of the given line.

getLineStart

abstract int getLineStart(int lineIndex)

Returns the start offset of the given line, inclusive.

getLineTop

abstract float getLineTop(int lineIndex)

Returns the bottom y coordinate of the given line.

getLineWidth

abstract float getLineWidth(int lineIndex)

Returns the width of the given line.

getMaxIntrinsicWidth

abstract float getMaxIntrinsicWidth()

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

getMinIntrinsicWidth

abstract float getMinIntrinsicWidth()

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

getOffsetForPosition

abstract int getOffsetForPosition(@NonNull Offset position)

Returns the character offset closest to the given graphical position.

getParagraphDirection

abstract @NonNull ResolvedTextDirection getParagraphDirection(int offset)

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

getPathForRange

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

Returns path that enclose the given text range.

getPlaceholderRects

abstract @NonNull List<RectgetPlaceholderRects()

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.

getWidth

abstract float getWidth()

The amount of horizontal space this paragraph occupies.

getWordBoundary

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

isLineEllipsized

abstract 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

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

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
@NonNull Canvas canvas

Canvas to draw this paragraph on.

@NonNull Color 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 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 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 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.

@NonNull BlendMode blendMode

Blending algorithm to be applied to the Paragraph while painting.

paint

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

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
@NonNull Canvas canvas

Canvas to draw this paragraph on.

@NonNull Brush 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.

float 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 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 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 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.

@NonNull BlendMode blendMode

Blending algorithm to be applied to the Paragraph while painting.