/
Android Studio Sign in

AnnotatedString.Builder

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

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString

buildAnnotatedString {
    append("Hello")
    // push green text style so that any appended text will be green
    pushStyle(SpanStyle(color = Color.Green))
    // append new text, this text will be rendered as green
    append(" World")
    // pop the green style
    pop()
    // append a string without style
    append("!")
    // then style the last added word as red, exclamation mark will be red
    addStyle(SpanStyle(color = Color.Red), "Hello World".length, this.length)

    toAnnotatedString()
}

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

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.buildAnnotatedString

val words = listOf("Hello", "World")
buildAnnotatedString {
    // joinTo is a Kotlin stdlib function that takes an Appendable
    words.joinTo(this, separator = " ", postfix = "!")

    toAnnotatedString()
}

Summary

Nested types

Scope for a bullet list

Public constructors
Builder(capacity: Int)
Cmn

Create an Builder instance using the given AnnotatedString.
Cmn
Builder(text: String)

Create an Builder instance using the given String.
Cmn

Public functions
Unit
addBullet(bullet: Bullet, start: Int, end: Int)

Adds an annotation to draw a bullet.
Cmn
Unit
addBullet(bullet: Bullet, indentation: TextUnit, start: Int, end: Int)

Adds an annotation to draw a bullet together with a paragraph that adds an indentation.
Cmn
Unit
addLink(clickable: LinkAnnotation.Clickable, start: Int, end: Int)

Set a LinkAnnotation.Clickable for the given range defined by start and end.
Cmn
Unit
addLink(url: LinkAnnotation.Url, start: Int, end: Int)

Set a LinkAnnotation.Url for the given range defined by start and end.
Cmn
Unit
addStringAnnotation(tag: String, annotation: String, start: Int, end: Int)

Set an Annotation for the given range defined by start and end.
Cmn
Unit
addStyle(style: ParagraphStyle, start: Int, end: Int)

Set a ParagraphStyle for the given range defined by start and end.
Cmn
Unit
addStyle(style: SpanStyle, start: Int, end: Int)

Set a SpanStyle for the given range defined by start and end.
Cmn
Unit
addTtsAnnotation(ttsAnnotation: TtsAnnotation, start: Int, end: Int)

Set a TtsAnnotation for the given range defined by start and end.
Cmn
Unit
@ExperimentalTextApi
addUrlAnnotation(urlAnnotation: UrlAnnotation, start: Int, end: Int)

This function is deprecated. Use LinkAnnotation API for links instead
Cmn
open AnnotatedString.Builder
append(char: Char)
Cmn
Unit

Appends the given AnnotatedString to this Builder.
Cmn
open AnnotatedString.Builder

Appends text to this Builder if non-null, and returns this Builder.
Cmn
Unit
append(text: String)

Appends the given String to this Builder.
Cmn
Unit
append(text: AnnotatedString, start: Int, end: Int)

Appends the range of text between start (inclusive) and end (exclusive) to this Builder.
Cmn
open AnnotatedString.Builder
append(text: CharSequence?, start: Int, end: Int)

Appends the range of text between start (inclusive) and end (exclusive) to this Builder if non-null, and returns this Builder.
Cmn
Unit
pop()

Ends the style or annotation that was added via a push operation before.
Cmn
Unit
pop(index: Int)

Ends the styles or annotation up to and including the pushStyle or pushStringAnnotation that returned the given index.
Cmn
Int
pushBullet(bullet: Bullet)

Applies the given bullet annotation to any appended text until a corresponding pop is called.
Cmn
Int

Attach the given LinkAnnotation to any appended text until a corresponding pop is called.
Cmn
Int
pushStringAnnotation(tag: String, annotation: String)

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

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

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

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

This function is deprecated. Use LinkAnnotation API for links instead
Cmn
AnnotatedString

Constructs an AnnotatedString based on the configurations applied to the Builder.
Cmn
R
<R : Any> withBulletList(indentation: TextUnit, bullet: Bullet, block: AnnotatedString.Builder.BulletScope.() -> R)

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

Creates a bullet list item around the content produced by the block.
Cmn

Public properties
Int

Returns the length of the String.
Cmn

Extension functions
inline R
<R : Any> AnnotatedString.Builder.withAnnotation(
    ttsAnnotation: TtsAnnotation,
    crossinline block: AnnotatedString.Builder.() -> R
)

Pushes an TtsAnnotation to the AnnotatedString.Builder, executes block and then pops the annotation.
Cmn
inline R
@ExperimentalTextApi
<R : Any> AnnotatedString.Builder.withAnnotation(
    urlAnnotation: UrlAnnotation,
    crossinline block: AnnotatedString.Builder.() -> R
)

This function is deprecated. Use LinkAnnotation API for links instead
Cmn
inline R
<R : Any> AnnotatedString.Builder.withAnnotation(
    tag: String,
    annotation: String,
    crossinline block: AnnotatedString.Builder.() -> R
)

Pushes an annotation to the AnnotatedString.Builder, executes block and then pops the annotation.
Cmn
inline R
<R : Any> AnnotatedString.Builder.withLink(
    link: LinkAnnotation,
    block: AnnotatedString.Builder.() -> R
)

Pushes a LinkAnnotation to the AnnotatedString.Builder, executes block and then pops the annotation.
Cmn
inline R
<R : Any> AnnotatedString.Builder.withStyle(
    style: ParagraphStyle,
    crossinline block: AnnotatedString.Builder.() -> R
)

Pushes style to the AnnotatedString.Builder, executes block and then pops the style.
Cmn
inline R

Pushes style to the AnnotatedString.Builder, executes block and then pops the style.
Cmn
Unit
AnnotatedString.Builder.appendInlineContent(
    id: String,
    alternateText: String
)

Used to insert composables into the text layout.
Cmn

Public constructors

Builder

Cmn
Added in 1.0.0
Builder(capacity: Int = 16)
Parameters
capacity: Int = 16

initial capacity for the internal char buffer

Builder

Cmn
Added in 1.0.0
Builder(text: AnnotatedString)

Create an Builder instance using the given AnnotatedString.

Builder

Cmn
Added in 1.0.0
Builder(text: String)

Create an Builder instance using the given String.

Public functions

addBullet

Cmn
Added in 1.9.0
fun addBullet(bullet: Bullet, start: Int, end: Int): Unit

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: Bullet

a bullet to draw before the text
start: Int

the inclusive starting offset of the range
end: Int

the exclusive end offset of the range
See also
withBulletList

addBullet

Cmn
Added in 1.10.0
fun addBullet(bullet: Bullet, indentation: TextUnit, start: Int, end: Int): Unit

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

Parameters
bullet: Bullet

a bullet to draw before the text
indentation: TextUnit

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

the inclusive starting offset of the range
end: Int

the exclusive end offset of the range
See also
withBulletList

addLink

Cmn
Added in 1.7.0
fun addLink(clickable: LinkAnnotation.Clickable, start: Int, end: Int): Unit

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: LinkAnnotation.Clickable

A LinkAnnotation.Clickable object that stores the tag being linked to.
start: Int

the inclusive starting offset of the range
end: Int

the exclusive end offset of the range
See also
getStringAnnotations

addLink

Cmn
Added in 1.7.0
fun addLink(url: LinkAnnotation.Url, start: Int, end: Int): Unit

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: LinkAnnotation.Url

A LinkAnnotation.Url object that stores the URL being linked to.
start: Int

the inclusive starting offset of the range
end: Int

the exclusive end offset of the range
See also
getStringAnnotations

addStringAnnotation

Cmn
Added in 1.0.0
fun addStringAnnotation(tag: String, annotation: String, start: Int, end: Int): Unit

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

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.buildAnnotatedString

buildAnnotatedString {
    append("link: Jetpack Compose")
    // attach a string annotation that stores a URL to the text "Jetpack Compose".
    addStringAnnotation(
        tag = "URL",
        annotation = "https://developer.android.com/jetpack/compose",
        start = 6,
        end = 21,
    )
}
Parameters
tag: String

the tag used to distinguish annotations
annotation: String

the string annotation that is attached
start: Int

the inclusive starting offset of the range
end: Int

the exclusive end offset of the range
See also
getStringAnnotations

addStyle

Cmn
Added in 1.0.0
fun addStyle(style: ParagraphStyle, start: Int, end: Int): Unit

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. Example: (abc){def} or abc(def)ghi{jkl}.

  • Nested: one paragraph is completely inside the other. Example: (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. Example: ({abc}).

  • Overlapping: one paragraph partially overlaps the other. Note that this is invalid! Example: (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

ParagraphStyle to be applied
start: Int

the inclusive starting offset of the range
end: Int

the exclusive end offset of the range

addStyle

Cmn
Added in 1.0.0
fun addStyle(style: SpanStyle, start: Int, end: Int): Unit

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

Parameters
style: SpanStyle

SpanStyle to be applied
start: Int

the inclusive starting offset of the range
end: Int

the exclusive end offset of the range

addTtsAnnotation

Cmn
Added in 1.0.0
fun addTtsAnnotation(ttsAnnotation: TtsAnnotation, start: Int, end: Int): Unit

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

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.buildAnnotatedString

buildAnnotatedString {
    append("link: Jetpack Compose")
    // attach a string annotation that stores a URL to the text "Jetpack Compose".
    addStringAnnotation(
        tag = "URL",
        annotation = "https://developer.android.com/jetpack/compose",
        start = 6,
        end = 21,
    )
}
Parameters
ttsAnnotation: TtsAnnotation

an object that stores text to speech metadata that intended for the TTS engine.
start: Int

the inclusive starting offset of the range
end: Int

the exclusive end offset of the range
See also
getStringAnnotations

addUrlAnnotation

Cmn
Added in 1.3.0
Deprecated in 1.7.0
@ExperimentalTextApi
fun addUrlAnnotation(urlAnnotation: UrlAnnotation, start: Int, end: Int): Unit

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.

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.buildAnnotatedString

buildAnnotatedString {
    append("link: Jetpack Compose")
    // attach a string annotation that stores a URL to the text "Jetpack Compose".
    addStringAnnotation(
        tag = "URL",
        annotation = "https://developer.android.com/jetpack/compose",
        start = 6,
        end = 21,
    )
}
Parameters
urlAnnotation: UrlAnnotation

A UrlAnnotation object that stores the URL being linked to.
start: Int

the inclusive starting offset of the range
end: Int

the exclusive end offset of the range
See also
getStringAnnotations

append

Cmn
Added in 1.0.0
open fun append(char: Char): AnnotatedString.Builder

append

Cmn
Added in 1.0.0
fun append(text: AnnotatedString): Unit

Appends the given AnnotatedString to this Builder.

Parameters
text: AnnotatedString

the text to append

append

Cmn
Added in 1.4.0
open fun append(text: CharSequence?): AnnotatedString.Builder

Appends text to this Builder if non-null, and returns this Builder.

If text is an AnnotatedString, all spans and annotations will be copied over as well. No other subtypes of CharSequence will be treated specially. For example, any platform-specific types, such as SpannedString on Android, will only have their text copied and any other information held in the sequence, such as Android Spans, will be dropped.

Parameters
text: CharSequence?

the text to append

append

Cmn
Added in 1.0.0
fun append(text: String): Unit

Appends the given String to this Builder.

Parameters
text: String

the text to append

append

Cmn
Added in 1.4.0
fun append(text: AnnotatedString, start: Int, end: Int): Unit

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: AnnotatedString

the text to append
start: Int

The index of the first character in text to copy over (inclusive).
end: Int

The index after the last character in text to copy over (exclusive).

append

Cmn
Added in 1.4.0
open fun append(text: CharSequence?, start: Int, end: Int): AnnotatedString.Builder

Appends the range of text between start (inclusive) and end (exclusive) to this Builder if non-null, and returns this Builder.

If text is an AnnotatedString, all spans and annotations from text between start and end will be copied over as well. No other subtypes of CharSequence will be treated specially. For example, any platform-specific types, such as SpannedString on Android, will only have their text copied and any other information held in the sequence, such as Android Spans, will be dropped.

Parameters
text: CharSequence?

the text to append
start: Int

The index of the first character in text to copy over (inclusive).
end: Int

The index after the last character in text to copy over (exclusive).

pop

Cmn
Added in 1.0.0
fun pop(): Unit

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

See also
pushStyle
pushStringAnnotation

pop

Cmn
Added in 1.0.0
fun pop(index: Int): Unit

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

Parameters
index: Int

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

pushBullet

Cmn
Added in 1.9.0
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.

See also
withBulletList

pushLink

Cmn
Added in 1.7.0
fun pushLink(link: LinkAnnotation): Int

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

Parameters
link: LinkAnnotation

A LinkAnnotation object that stores the URL or clickable tag being linked to.
See also
getStringAnnotations
AnnotatedString.Range

pushStringAnnotation

Cmn
Added in 1.0.0
fun pushStringAnnotation(tag: String, annotation: String): Int

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

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.buildAnnotatedString

buildAnnotatedString {
    // push a string annotation to be applied to any appended text after this point.
    pushStringAnnotation("ParagrapLabel", "paragraph1")
    // append a paragraph, the annotation "paragraph1" is attached
    append("Paragraph One\n")
    // pop the annotation
    pop()
    // append new paragraph
    append("Paragraph Two\n")

    toAnnotatedString()
}
Parameters
tag: String

the tag used to distinguish annotations
annotation: String

the string annotation attached on this AnnotatedString
See also
getStringAnnotations
AnnotatedString.Range

pushStyle

Cmn
Added in 1.0.0
fun pushStyle(style: ParagraphStyle): Int

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

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.ParagraphStyle
import androidx.compose.ui.unit.sp

with(AnnotatedString.Builder()) {
    // push a ParagraphStyle to be applied to any appended text after this point.
    pushStyle(ParagraphStyle(lineHeight = 18.sp))
    // append a paragraph which will have lineHeight 18.sp
    append("Paragraph One\n")
    // pop the ParagraphStyle
    pop()
    // append new paragraph, this paragraph will not have the line height defined.
    append("Paragraph Two\n")

    toAnnotatedString()
}
Parameters
style: ParagraphStyle

ParagraphStyle to be applied

pushStyle

Cmn
Added in 1.0.0
fun pushStyle(style: SpanStyle): Int

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

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString

buildAnnotatedString {
    // push green text color so that any appended text will be rendered green
    pushStyle(SpanStyle(color = Color.Green))
    // append string, this text will be rendered green
    append("Hello")
    // pop the green text style
    pop()
    // append new string, this string will be default color
    append(" World")

    toAnnotatedString()
}
Parameters
style: SpanStyle

SpanStyle to be applied

pushTtsAnnotation

Cmn
Added in 1.0.0
fun pushTtsAnnotation(ttsAnnotation: TtsAnnotation): Int

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

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.buildAnnotatedString

buildAnnotatedString {
    // push a string annotation to be applied to any appended text after this point.
    pushStringAnnotation("ParagrapLabel", "paragraph1")
    // append a paragraph, the annotation "paragraph1" is attached
    append("Paragraph One\n")
    // pop the annotation
    pop()
    // append new paragraph
    append("Paragraph Two\n")

    toAnnotatedString()
}
Parameters
ttsAnnotation: TtsAnnotation

an object that stores text to speech metadata that intended for the TTS engine.
See also
getStringAnnotations
AnnotatedString.Range

pushUrlAnnotation

Cmn
Added in 1.3.0
Deprecated in 1.7.0
@ExperimentalTextApi
fun pushUrlAnnotation(urlAnnotation: UrlAnnotation): Int

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

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.buildAnnotatedString

buildAnnotatedString {
    // push a string annotation to be applied to any appended text after this point.
    pushStringAnnotation("ParagrapLabel", "paragraph1")
    // append a paragraph, the annotation "paragraph1" is attached
    append("Paragraph One\n")
    // pop the annotation
    pop()
    // append new paragraph
    append("Paragraph Two\n")

    toAnnotatedString()
}
Parameters
urlAnnotation: UrlAnnotation

A UrlAnnotation object that stores the URL being linked to.
See also
getStringAnnotations
AnnotatedString.Range

toAnnotatedString

Cmn
Added in 1.0.0
fun toAnnotatedString(): AnnotatedString

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

withBulletList

Cmn 
fun <R : Any> withBulletList(
    indentation: TextUnit = Bullet.DefaultIndentation,
    bullet: Bullet = Bullet.Default,
    block: AnnotatedString.Builder.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

Cmn 
fun <R : Any> AnnotatedString.Builder.BulletScope.withBulletListItem(
    bullet: Bullet? = null,
    block: AnnotatedString.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.

import androidx.compose.foundation.text.BasicText
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.Bullet
import androidx.compose.ui.text.buildAnnotatedString

BasicText(
    buildAnnotatedString {
        append("Not a bullet item")
        withBulletList {
            withBulletListItem { append("Item 1") }
            withBulletList { withBulletListItem { append("Nested item 2") } }
            withBulletListItem { append("Item 3") }
        }
    }
)
Parameters
bullet: Bullet? = null

defines the bullet to be drawn
block: AnnotatedString.Builder.() -> R

function to be executed

Public properties

length

Cmn
Added in 1.0.0
val length: Int

Returns the length of the String.

Extension functions

withAnnotation

Cmn 
inline fun <R : Any> AnnotatedString.Builder.withAnnotation(
    ttsAnnotation: TtsAnnotation,
    crossinline block: AnnotatedString.Builder.() -> R
): R

Pushes an TtsAnnotation to the AnnotatedString.Builder, executes block and then pops the annotation.

Parameters
ttsAnnotation: TtsAnnotation

an object that stores text to speech metadata that intended for the TTS engine.
crossinline block: AnnotatedString.Builder.() -> R

function to be executed
Returns
R

result of the block
See also
pushStringAnnotation
pop

withAnnotation

Cmn 
@ExperimentalTextApi
inline fun <R : Any> AnnotatedString.Builder.withAnnotation(
    urlAnnotation: UrlAnnotation,
    crossinline block: AnnotatedString.Builder.() -> R
): R

Pushes an UrlAnnotation to the AnnotatedString.Builder, executes block and then pops the annotation.

Parameters
urlAnnotation: UrlAnnotation

A UrlAnnotation object that stores the URL being linked to.
crossinline block: AnnotatedString.Builder.() -> R

function to be executed
Returns
R

result of the block
See also
pushStringAnnotation
pop

withAnnotation

Cmn 
inline fun <R : Any> AnnotatedString.Builder.withAnnotation(
    tag: String,
    annotation: String,
    crossinline block: AnnotatedString.Builder.() -> R
): R

Pushes an annotation to the AnnotatedString.Builder, executes block and then pops the annotation.

Parameters
tag: String

the tag used to distinguish annotations
annotation: String

the string annotation attached on this AnnotatedString
crossinline block: AnnotatedString.Builder.() -> R

function to be executed
Returns
R

result of the block
See also
pushStringAnnotation
pop

withLink

Cmn 
inline fun <R : Any> AnnotatedString.Builder.withLink(
    link: LinkAnnotation,
    block: AnnotatedString.Builder.() -> R
): R

Pushes a LinkAnnotation to the AnnotatedString.Builder, executes block and then pops the annotation.

import androidx.compose.foundation.text.BasicText
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.LinkAnnotation
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.TextLinkStyles
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.withLink
import androidx.compose.ui.unit.sp

// Display a link in the text
BasicText(
    buildAnnotatedString {
        append("Build better apps faster with ")
        withLink(
            LinkAnnotation.Url(
                "https://developer.android.com/jetpack/compose",
                TextLinkStyles(style = SpanStyle(color = Color.Blue)),
            )
        ) {
            append("Jetpack Compose")
        }
    }
)
 
import androidx.compose.foundation.text.BasicText
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.LinkAnnotation
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.TextLinkStyles
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.style.TextDecoration
import androidx.compose.ui.text.withLink
import androidx.compose.ui.unit.sp

// Display a link in the text that gets an underline when hovered
BasicText(
    buildAnnotatedString {
        append("Build better apps faster with ")
        val link =
            LinkAnnotation.Url(
                "https://developer.android.com/jetpack/compose",
                TextLinkStyles(
                    style = SpanStyle(color = Color.Blue),
                    hoveredStyle = SpanStyle(textDecoration = TextDecoration.Underline),
                ),
            )
        withLink(link) { append("Jetpack Compose") }
    }
)
 
import androidx.compose.foundation.text.BasicText
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalUriHandler
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.LinkAnnotation
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.TextLinkStyles
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.withLink
import androidx.compose.ui.unit.sp

// Display a link in the text and log metrics whenever user clicks on it. In that case we handle
// the link using openUri method of the LocalUriHandler
val uriHandler = LocalUriHandler.current
BasicText(
    buildAnnotatedString {
        append("Build better apps faster with ")
        val link =
            LinkAnnotation.Url(
                "https://developer.android.com/jetpack/compose",
                TextLinkStyles(SpanStyle(color = Color.Blue)),
            ) {
                val url = (it as LinkAnnotation.Url).url
                // log some metrics
                uriHandler.openUri(url)
            }
        withLink(link) { append("Jetpack Compose") }
    }
)
Parameters
link: LinkAnnotation

A LinkAnnotation object representing a clickable part of the text
block: AnnotatedString.Builder.() -> R

function to be executed
Returns
R

result of the block

withStyle

Cmn 
inline fun <R : Any> AnnotatedString.Builder.withStyle(
    style: ParagraphStyle,
    crossinline block: AnnotatedString.Builder.() -> R
): R

Pushes style to the AnnotatedString.Builder, executes block and then pops the style.

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.withStyle

buildAnnotatedString {
    withStyle(SpanStyle(color = Color.Green)) {
        // green text style will be applied to all text in this block
        append("Hello")
    }
    toAnnotatedString()
}
Parameters
style: ParagraphStyle

SpanStyle to be applied
crossinline block: AnnotatedString.Builder.() -> R

function to be executed
Returns
R

result of the block
See also
pushStyle
pop

withStyle

Cmn 
inline fun <R : Any> AnnotatedString.Builder.withStyle(style: SpanStyle, block: AnnotatedString.Builder.() -> R): R

Pushes style to the AnnotatedString.Builder, executes block and then pops the style.

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.withStyle

buildAnnotatedString {
    withStyle(SpanStyle(color = Color.Green)) {
        // green text style will be applied to all text in this block
        append("Hello")
    }
    toAnnotatedString()
}
Parameters
style: SpanStyle

SpanStyle to be applied
block: AnnotatedString.Builder.() -> R

function to be executed
Returns
R

result of the block
See also
pushStyle
pop

appendInlineContent

Cmn 
fun AnnotatedString.Builder.appendInlineContent(
    id: String,
    alternateText: String = REPLACEMENT_CHAR
): Unit

Used to insert composables into the text layout. This method can be used together with the inlineContent parameter of BasicText. It will append the alternateText to this AnnotatedString and also mark this range of text to be replaced by a composable. BasicText will try to find an InlineTextContent in the map defined by inlineContent whose key equals to id, and it will use the InlineTextContent.children to replace this range of text.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.text.BasicText
import androidx.compose.foundation.text.InlineTextContent
import androidx.compose.foundation.text.appendInlineContent
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.Placeholder
import androidx.compose.ui.text.PlaceholderVerticalAlign
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.unit.em

val myId = "inlineContent"
val text = buildAnnotatedString {
    append("Hello")
    // Append a placeholder string "[myBox]" and attach an annotation "inlineContent" on it.
    appendInlineContent(myId, "[myBox]")
}

val inlineContent =
    mapOf(
        Pair(
            // This tells the [BasicText] to replace the placeholder string "[myBox]" by
            // the composable given in the [InlineTextContent] object.
            myId,
            InlineTextContent(
                // Placeholder tells text layout the expected size and vertical alignment of
                // children composable.
                Placeholder(
                    width = 0.5.em,
                    height = 0.5.em,
                    placeholderVerticalAlign = PlaceholderVerticalAlign.AboveBaseline,
                )
            ) {
                // This [Box] will fill maximum size, which is specified by the [Placeholder]
                // above. Notice the width and height in [Placeholder] are specified in
                // TextUnit,
                // and are converted into pixel by text layout.
                Box(modifier = Modifier.fillMaxSize().background(color = Color.Red))
            },
        )
    )

BasicText(text = text, inlineContent = inlineContent)
Parameters
id: String

The id used to look up the InlineTextContent, it is referred by the inlineContent parameter of BasicText to replace the alternateText to the corresponding composable.
alternateText: String = REPLACEMENT_CHAR

The text to be replaced by the inline content. It's displayed when the inlineContent parameter of BasicText doesn't contain id. Accessibility features will also use this text to describe the inline content.
Throws
kotlin.IllegalArgumentException

if alternateText has zero length.
See also
InlineTextContent
BasicText
Morty Proxy This is a proxified and sanitized view of the page, visit original site.