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

AnnotatedStringKt

public final class AnnotatedStringKt


Summary

Public methods

static final @NonNull AnnotatedString
AnnotatedString(
    @NonNull String text,
    @NonNull ParagraphStyle paragraphStyle
)

Create an AnnotatedString with a paragraphStyle that will apply to the whole text.

static final @NonNull AnnotatedString
AnnotatedString(
    @NonNull String text,
    @NonNull SpanStyle spanStyle,
    ParagraphStyle paragraphStyle
)

Create an AnnotatedString with a spanStyle that will apply to the whole text.

static final @NonNull AnnotatedString

Build a new AnnotatedString by populating newly created AnnotatedString.Builder provided by builder.

static final @NonNull AnnotatedString
capitalize(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create capitalized AnnotatedString

static final @NonNull AnnotatedString
decapitalize(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create capitalized AnnotatedString

static final @NonNull AnnotatedString
toLowerCase(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create lower case transformed AnnotatedString

static final @NonNull AnnotatedString
toUpperCase(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create upper case transformed AnnotatedString

static final @NonNull R
@ExperimentalTextApi
<R extends Object> withAnnotation(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull TtsAnnotation ttsAnnotation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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

static final @NonNull R
@ExperimentalTextApi
<R extends Object> withAnnotation(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull UrlAnnotation urlAnnotation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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

static final @NonNull R
@ExperimentalTextApi
<R extends Object> withAnnotation(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull String tag,
    @NonNull String annotation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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

static final @NonNull R
<R extends Object> withStyle(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull ParagraphStyle style,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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

static final @NonNull R
<R extends Object> withStyle(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull SpanStyle style,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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

Public methods

AnnotatedString

public static final @NonNull AnnotatedString AnnotatedString(
    @NonNull String text,
    @NonNull ParagraphStyle paragraphStyle
)

Create an AnnotatedString with a paragraphStyle that will apply to the whole text.

Parameters
@NonNull ParagraphStyle paragraphStyle

ParagraphStyle to be applied to whole text

AnnotatedString

public static final @NonNull AnnotatedString AnnotatedString(
    @NonNull String text,
    @NonNull SpanStyle spanStyle,
    ParagraphStyle paragraphStyle
)

Create an AnnotatedString with a spanStyle that will apply to the whole text.

Parameters
@NonNull SpanStyle spanStyle

SpanStyle to be applied to whole text

ParagraphStyle paragraphStyle

ParagraphStyle to be applied to whole text

buildAnnotatedString

public static final @NonNull AnnotatedString buildAnnotatedString(
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.BuilderUnit> builder
)

Build a new AnnotatedString by populating newly created AnnotatedString.Builder provided by builder.

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

// create an AnnotatedString using the lambda builder
buildAnnotatedString {
    // append "Hello" with red text color
    withStyle(SpanStyle(color = Color.Red)) {
        append("Hello")
    }
    append(" ")
    // append "Hello" with blue text color
    withStyle(SpanStyle(color = Color.Blue)) {
        append("World!")
    }
}
Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.BuilderUnit> builder

lambda to modify AnnotatedString.Builder

capitalize

public static final @NonNull AnnotatedString capitalize(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create capitalized AnnotatedString

The capitalization sometimes maps different number of characters. This function adjusts the text style and paragraph style ranges to transformed offset.

Note, if the style's offset is middle of the capitalization context, this function won't transform the character, e.g. style starts from between base alphabet character and accent character.

Parameters
@NonNull LocaleList localeList

A locale list used for capitalize mapping. Only the first locale is effective. If empty locale list is passed, use the current locale instead. Note that, this locale is currently ignored since underlying Kotlin method is experimental.

Returns
@NonNull AnnotatedString

A capitalized string.

decapitalize

public static final @NonNull AnnotatedString decapitalize(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create capitalized AnnotatedString

The decapitalization sometimes maps different number of characters. This function adjusts the text style and paragraph style ranges to transformed offset.

Note, if the style's offset is middle of the decapitalization context, this function won't transform the character, e.g. style starts from between base alphabet character and accent character.

Parameters
@NonNull LocaleList localeList

A locale list used for decapitalize mapping. Only the first locale is effective. If empty locale list is passed, use the current locale instead. Note that, this locale is currently ignored since underlying Kotlin method is experimental.

Returns
@NonNull AnnotatedString

A decapitalized string.

toLowerCase

public static final @NonNull AnnotatedString toLowerCase(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create lower case transformed AnnotatedString

The lowercase sometimes maps different number of characters. This function adjusts the text style and paragraph style ranges to transformed offset.

Note, if the style's offset is middle of the lowercase mapping context, this function won't transform the character, e.g. style starts from between base alphabet character and accent character.

Parameters
@NonNull LocaleList localeList

A locale list used for lower case mapping. Only the first locale is effective. If empty locale list is passed, use the current locale instead.

Returns
@NonNull AnnotatedString

A lowercase transformed string.

toUpperCase

public static final @NonNull AnnotatedString toUpperCase(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create upper case transformed AnnotatedString

The uppercase sometimes maps different number of characters. This function adjusts the text style and paragraph style ranges to transformed offset.

Note, if the style's offset is middle of the uppercase mapping context, this function won't transform the character, e.g. style starts from between base alphabet character and accent character.

Parameters
@NonNull LocaleList localeList

A locale list used for upper case mapping. Only the first locale is effective. If empty locale list is passed, use the current locale instead.

Returns
@NonNull AnnotatedString

A uppercase transformed string.

withAnnotation

@ExperimentalTextApi
public static final @NonNull R <R extends Object> withAnnotation(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull TtsAnnotation ttsAnnotation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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

Parameters
@NonNull TtsAnnotation ttsAnnotation

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

@ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block

function to be executed

Returns
@NonNull R

result of the block

withAnnotation

@ExperimentalTextApi
public static final @NonNull R <R extends Object> withAnnotation(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull UrlAnnotation urlAnnotation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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

Parameters
@NonNull UrlAnnotation urlAnnotation

A UrlAnnotation object that stores the URL being linked to.

@ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block

function to be executed

Returns
@NonNull R

result of the block

withAnnotation

@ExperimentalTextApi
public static final @NonNull R <R extends Object> withAnnotation(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull String tag,
    @NonNull String annotation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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

Parameters
@NonNull String tag

the tag used to distinguish annotations

@NonNull String annotation

the string annotation attached on this AnnotatedString

@ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block

function to be executed

Returns
@NonNull R

result of the block

withStyle

public static final @NonNull R <R extends Object> withStyle(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull ParagraphStyle style,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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
@NonNull ParagraphStyle style

SpanStyle to be applied

@ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block

function to be executed

Returns
@NonNull R

result of the block

See also
pushStyle
pop

withStyle

public static final @NonNull R <R extends Object> withStyle(
    @NonNull AnnotatedString.Builder receiver,
    @NonNull SpanStyle style,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block
)

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
@NonNull SpanStyle style

SpanStyle to be applied

@ExtensionFunctionType @NonNull Function1<@NonNull AnnotatedString.Builder, @NonNull R> block

function to be executed

Returns
@NonNull R

result of the block

See also
pushStyle
pop