AnnotatedString.Builder - Class in Compose UI Text

Builder class for AnnotatedString.

Common

class Builder(capacity: Int = 16) : Appendable

Builder class for AnnotatedString. Enables construction of an AnnotatedString using methods such as append and addStyle.

This class implements Appendable and can be used with other APIs that don't know about AnnotatedStrings:

Parameters


capacity	initial capacity for the internal char buffer

Secondary Constructors

constructor(text: String) : this() {
        append(text)
    }

Create an Builder instance using the given String.

constructor(text: AnnotatedString) : this() {
        append(text)
    }

Create an Builder instance using the given AnnotatedString.

Properties

Common

val length: Int

Returns the length of the String.

Functions

append

fun append(text: String)

Appends the given String to this Builder.

Parameters


text	the text to append

deprecated_append_returning_void

fun deprecated_append_returning_void(char: Char)

append

fun append(text: AnnotatedString)

Appends the given AnnotatedString to this Builder.

Parameters


text	the text to append

append

fun append(text: AnnotatedString, start: Int, end: Int)

Appends the range of text between start (inclusive) and end (exclusive) to this Builder. All spans and annotations from text between start and end will be copied over as well.

Parameters


text	the text to append
start	The index of the first character in text to copy over (inclusive).
end	The index after the last character in text to copy over (exclusive).

addStyle

fun addStyle(style: SpanStyle, start: Int, end: Int)

Set a SpanStyle for the given range defined by start and end.

Parameters


style	SpanStyle to be applied
start	the inclusive starting offset of the range
end	the exclusive end offset of the range

addStyle

fun addStyle(style: ParagraphStyle, start: Int, end: Int)

Set a ParagraphStyle for the given range defined by start and end. When a ParagraphStyle is applied to the AnnotatedString, it will be rendered as a separate paragraph.

Paragraphs arrangement

AnnotatedString only supports a few ways that arrangements can be arranged.

The () and {} below represent different ParagraphStyles passed in that particular order to the AnnotatedString.

Non-overlapping: paragraphs don't affect each other. (abc){def} or abc(def)ghi{jkl}.
Nested: one paragraph is completely inside the other. (abc{def}ghi) or ({abc}def) or (abd{def}). Note that because () is passed before {} to the AnnotatedString, these are considered nested.
Fully overlapping: two paragraphs cover the exact same range of text. ({abc}).
Overlapping: one paragraph partially overlaps the other. Note that this is invalid! (abc{de)f}.

The order in which you apply ParagraphStyle can affect how the paragraphs are arranged. For example, when you first add () at range 0..4 and then {} at range 0..2, this paragraphs arrangement is considered nested. But if you first add a () paragraph at range 0..2 and then {} at range 0..4, this arrangement is considered overlapping and is invalid.

Styling

If you don't pass a paragraph style for any part of the text, a paragraph will be created anyway with a default style. In case of nested paragraphs, the outer paragraph will be split on the bounds of inner paragraph when the paragraphs are passed to be measured and rendered. For example, (abc{def}ghi) will be split into (abc)({def})(ghi). The inner paragraph, similarly to fully overlapping paragraphs, will have a style that is a combination of two created using a ParagraphStyle.merge method.

Parameters


style	ParagraphStyle to be applied
start	the inclusive starting offset of the range
end	the exclusive end offset of the range

addStringAnnotation

fun addStringAnnotation(tag: String, annotation: String, start: Int, end: Int)

Set an Annotation for the given range defined by start and end.

Parameters


tag	the tag used to distinguish annotations
annotation	the string annotation that is attached
start	the inclusive starting offset of the range
end	the exclusive end offset of the range

addTtsAnnotation

fun addTtsAnnotation(ttsAnnotation: TtsAnnotation, start: Int, end: Int)

Set a TtsAnnotation for the given range defined by start and end.

Parameters


ttsAnnotation	an object that stores text to speech metadata that intended for the TTS engine.
start	the inclusive starting offset of the range
end	the exclusive end offset of the range

addUrlAnnotation

@ExperimentalTextApi
        
        
        fun addUrlAnnotation(urlAnnotation: UrlAnnotation, start: Int, end: Int)

Set a UrlAnnotation for the given range defined by start and end. URLs may be treated specially by screen readers, including being identified while reading text with an audio icon or being summarized in a links menu.

Parameters


urlAnnotation	A UrlAnnotation object that stores the URL being linked to.
start	the inclusive starting offset of the range
end	the exclusive end offset of the range

addLink

fun addLink(url: LinkAnnotation.Url, start: Int, end: Int)

Set a LinkAnnotation.Url for the given range defined by start and end.

When clicking on the text in range, the corresponding URL from the url annotation will be opened using androidx.compose.ui.platform.UriHandler.

URLs may be treated specially by screen readers, including being identified while reading text with an audio icon or being summarized in a links menu.

Parameters


url	A LinkAnnotation.Url object that stores the URL being linked to.
start	the inclusive starting offset of the range
end	the exclusive end offset of the range

addLink

fun addLink(clickable: LinkAnnotation.Clickable, start: Int, end: Int)

Set a LinkAnnotation.Clickable for the given range defined by start and end.

When clicking on the text in range, a LinkInteractionListener will be triggered with the clickable object.

Clickable link may be treated specially by screen readers, including being identified while reading text with an audio icon or being summarized in a links menu.

Parameters


clickable	A LinkAnnotation.Clickable object that stores the tag being linked to.
start	the inclusive starting offset of the range
end	the exclusive end offset of the range

addBullet

fun addBullet(bullet: Bullet, start: Int, end: Int)

Adds an annotation to draw a bullet. Unlike another overload, this one doesn't add a separate ParagraphStyle. As so for bullet to be rendered, make sure it starts on a separate line by adding a newline before or wrapping with a ParagraphStyle.

For a convenient API to create a bullet list check withBulletList.

Parameters


bullet	a bullet to draw before the text
start	the inclusive starting offset of the range
end	the exclusive end offset of the range

addBullet

fun addBullet(bullet: Bullet, indentation: TextUnit, start: Int, end: Int)

Adds an annotation to draw a bullet together with a paragraph that adds an indentation.

Parameters


bullet	a bullet to draw before the text
indentation	indentation that is added to the paragraph. Note that this indentation should be large enough to fit a bullet and a padding between the bullet and beginning of the paragraph
start	the inclusive starting offset of the range
end	the exclusive end offset of the range

pushStyle

fun pushStyle(style: SpanStyle): Int

Applies the given SpanStyle to any appended text until a corresponding pop is called.

Parameters


style	SpanStyle to be applied

pushStyle

fun pushStyle(style: ParagraphStyle): Int

Applies the given ParagraphStyle to any appended text until a corresponding pop is called.

Parameters


style	ParagraphStyle to be applied

pushBullet

fun pushBullet(bullet: Bullet): Int

Applies the given bullet annotation to any appended text until a corresponding pop is called. For bullet to be rendered, make sure it starts on a separate line by either adding a newline before or by wrapping with a ParagraphStyle.

For a convenient API to create a bullet list check withBulletList.

withBulletList

fun <R : Any> withBulletList(
            indentation: TextUnit = Bullet.DefaultIndentation,
            bullet: Bullet = Bullet.Default,
            block: BulletScope.() -> R,
        ): R

Creates a bullet list which allows to define a common indentation and a bullet for evey bullet list item created inside the list.

Note that when nesting the withBulletList calls, the indentation inside the nested list will be a combination of all indentations in the nested chain. For example,

withBulletList(10.sp) { withBulletList(15.sp) {   // items indentation 25.sp }
}

withBulletListItem

fun <R : Any> BulletScope.withBulletListItem(
            bullet: Bullet? = null,
            block: Builder.() -> R,
        ): R

Creates a bullet list item around the content produced by the block. The list item creates a separate paragraph with the indentation to the bullet defined by the preceding Builder.withBulletList calls.

Parameters


bullet	defines the bullet to be drawn
block	function to be executed

pushStringAnnotation

fun pushStringAnnotation(tag: String, annotation: String): Int

Attach the given annotation to any appended text until a corresponding pop is called.

Parameters


tag	the tag used to distinguish annotations
annotation	the string annotation attached on this AnnotatedString

pushTtsAnnotation

fun pushTtsAnnotation(ttsAnnotation: TtsAnnotation): Int

Attach the given ttsAnnotation to any appended text until a corresponding pop is called.

Parameters


ttsAnnotation	an object that stores text to speech metadata that intended for the TTS engine.

pushUrlAnnotation

@ExperimentalTextApi
        
        
        fun pushUrlAnnotation(urlAnnotation: UrlAnnotation): Int

Attach the given UrlAnnotation to any appended text until a corresponding pop is called.

Parameters


urlAnnotation	A UrlAnnotation object that stores the URL being linked to.

pushLink

fun pushLink(link: LinkAnnotation): Int

Attach the given LinkAnnotation to any appended text until a corresponding pop is called.

Parameters


link	A LinkAnnotation object that stores the URL or clickable tag being linked to.

pop

fun pop()

Ends the style or annotation that was added via a push operation before.

pop

fun pop(index: Int)

Ends the styles or annotation up to and including the pushStyle or pushStringAnnotation that returned the given index.

Parameters


index	the result of the a previous pushStyle or pushStringAnnotation in order to pop to

toAnnotatedString

fun toAnnotatedString(): AnnotatedString

Constructs an AnnotatedString based on the configurations applied to the Builder.