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

AnnotatedString

public final class AnnotatedString implements CharSequence


The basic data structure of text with multiple styles. To construct an AnnotatedString you can use Builder.

Summary

Nested types

public final class AnnotatedString.Builder

Builder class for AnnotatedString.

public final class AnnotatedString.Range<T extends Object>

The information attached on the text such as a SpanStyle.

Public constructors

The basic data structure of text with multiple styles.

Public methods

boolean
equals(Object other)
char
get(int index)
int
final @NonNull List<@NonNull AnnotatedString.Range<@NonNull ParagraphStyle>>

All ParagraphStyle that have been applied to a range of this String

final @NonNull List<@NonNull AnnotatedString.Range<@NonNull SpanStyle>>

All SpanStyle that have been applied to a range of this String

final @NonNull List<@NonNull AnnotatedString.Range<@NonNull String>>
getStringAnnotations(int start, int end)

Query all of the string annotations attached on this AnnotatedString.

final @NonNull List<@NonNull AnnotatedString.Range<@NonNull String>>
getStringAnnotations(@NonNull String tag, int start, int end)

Query the string annotations attached on this AnnotatedString.

final @NonNull String
final @NonNull List<@NonNull AnnotatedString.Range<@NonNull TtsAnnotation>>
getTtsAnnotations(int start, int end)

Query all of the TtsAnnotations attached on this AnnotatedString.

final @NonNull List<@NonNull AnnotatedString.Range<@NonNull UrlAnnotation>>
@ExperimentalTextApi
getUrlAnnotations(int start, int end)

Query all of the UrlAnnotations attached on this AnnotatedString.

final boolean
hasStringAnnotations(@NonNull String tag, int start, int end)

Returns true if getStringAnnotations with the same parameters would return a non-empty list

int
final @NonNull AnnotatedString
final @NonNull AnnotatedString

Return a substring for the AnnotatedString and include the styles in the given range.

@NonNull AnnotatedString
subSequence(int startIndex, int endIndex)

Return a substring for the AnnotatedString and include the styles in the range of startIndex (inclusive) and endIndex (exclusive).

@NonNull String

Extension functions

final @NonNull AnnotatedString
AnnotatedStringKt.capitalize(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create capitalized AnnotatedString

final @NonNull AnnotatedString
AnnotatedStringKt.decapitalize(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create capitalized AnnotatedString

final @NonNull AnnotatedString
AnnotatedStringKt.toLowerCase(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create lower case transformed AnnotatedString

final @NonNull AnnotatedString
AnnotatedStringKt.toUpperCase(
    @NonNull AnnotatedString receiver,
    @NonNull LocaleList localeList
)

Create upper case transformed AnnotatedString

Public constructors

AnnotatedString

public AnnotatedString(
    @NonNull String text,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull SpanStyle>> spanStyles,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull ParagraphStyle>> paragraphStyles
)

The basic data structure of text with multiple styles. To construct an AnnotatedString you can use Builder.

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.ParagraphStyle
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.font.FontStyle
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.text.style.TextIndent
import androidx.compose.ui.unit.sp

AnnotatedString(
    text = "Hello World",
    // make "Hello" italic.
    spanStyles = listOf(
        AnnotatedString.Range(SpanStyle(fontStyle = FontStyle.Italic), 0, 5)
    ),
    // create two paragraphs with different alignment and indent settings.
    paragraphStyles = listOf(
        AnnotatedString.Range(ParagraphStyle(textAlign = TextAlign.Center), 0, 6),
        AnnotatedString.Range(ParagraphStyle(textIndent = TextIndent(5.sp)), 6, 11)
    )
)
Parameters
@NonNull String text

the text to be displayed.

@NonNull List<@NonNull AnnotatedString.Range<@NonNull SpanStyle>> spanStyles

a list of Ranges that specifies SpanStyles on certain portion of the text. These styles will be applied in the order of the list. And the SpanStyles applied later can override the former styles. Notice that SpanStyle attributes which are null or androidx.compose.ui.unit.TextUnit.Unspecified won't change the current ones.

@NonNull List<@NonNull AnnotatedString.Range<@NonNull ParagraphStyle>> paragraphStyles

a list of Ranges that specifies ParagraphStyles on certain portion of the text. Each ParagraphStyle with a Range defines a paragraph of text. It's required that Ranges of paragraphs don't overlap with each other. If there are gaps between specified paragraph Ranges, a default paragraph will be created in between.

Throws
kotlin.IllegalArgumentException

if paragraphStyles contains any two overlapping Ranges.

Public methods

equals

public boolean equals(Object other)

get

public char get(int index)

getLength

public int getLength()

getParagraphStyles

public final @NonNull List<@NonNull AnnotatedString.Range<@NonNull ParagraphStyle>> getParagraphStyles()

All ParagraphStyle that have been applied to a range of this String

getSpanStyles

public final @NonNull List<@NonNull AnnotatedString.Range<@NonNull SpanStyle>> getSpanStyles()

All SpanStyle that have been applied to a range of this String

getStringAnnotations

public final @NonNull List<@NonNull AnnotatedString.Range<@NonNull String>> getStringAnnotations(int start, int end)

Query all of the string annotations attached on this AnnotatedString.

Parameters
int start

the start of the query range, inclusive.

int end

the end of the query range, exclusive.

Returns
@NonNull List<@NonNull AnnotatedString.Range<@NonNull String>>

a list of annotations stored in Range. Notice that All annotations that intersect with the range [start, end) will be returned. When start is bigger than end, an empty list will be returned.

getStringAnnotations

public final @NonNull List<@NonNull AnnotatedString.Range<@NonNull String>> getStringAnnotations(@NonNull String tag, int start, int end)

Query the string annotations attached on this AnnotatedString. Annotations are metadata attached on the AnnotatedString, for example, a URL is a string metadata attached on the a certain range. Annotations are also store with Range like the styles.

Parameters
@NonNull String tag

the tag of the annotations that is being queried. It's used to distinguish the annotations for different purposes.

int start

the start of the query range, inclusive.

int end

the end of the query range, exclusive.

Returns
@NonNull List<@NonNull AnnotatedString.Range<@NonNull String>>

a list of annotations stored in Range. Notice that All annotations that intersect with the range [start, end) will be returned. When start is bigger than end, an empty list will be returned.

getText

public final @NonNull String getText()

getTtsAnnotations

public final @NonNull List<@NonNull AnnotatedString.Range<@NonNull TtsAnnotation>> getTtsAnnotations(int start, int end)

Query all of the TtsAnnotations attached on this AnnotatedString.

Parameters
int start

the start of the query range, inclusive.

int end

the end of the query range, exclusive.

Returns
@NonNull List<@NonNull AnnotatedString.Range<@NonNull TtsAnnotation>>

a list of annotations stored in Range. Notice that All annotations that intersect with the range [start, end) will be returned. When start is bigger than end, an empty list will be returned.

getUrlAnnotations

@ExperimentalTextApi
public final @NonNull List<@NonNull AnnotatedString.Range<@NonNull UrlAnnotation>> getUrlAnnotations(int start, int end)

Query all of the UrlAnnotations attached on this AnnotatedString.

Parameters
int start

the start of the query range, inclusive.

int end

the end of the query range, exclusive.

Returns
@NonNull List<@NonNull AnnotatedString.Range<@NonNull UrlAnnotation>>

a list of annotations stored in Range. Notice that All annotations that intersect with the range [start, end) will be returned. When start is bigger than end, an empty list will be returned.

hasStringAnnotations

public final boolean hasStringAnnotations(@NonNull String tag, int start, int end)

Returns true if getStringAnnotations with the same parameters would return a non-empty list

hashCode

public int hashCode()

plus

public final @NonNull AnnotatedString plus(@NonNull AnnotatedString other)

subSequence

public final @NonNull AnnotatedString subSequence(@NonNull TextRange range)

Return a substring for the AnnotatedString and include the styles in the given range.

Parameters
@NonNull TextRange range

the text range

See also
subSequence

(start: Int, end: Int)

subSequence

public @NonNull AnnotatedString subSequence(int startIndex, int endIndex)

Return a substring for the AnnotatedString and include the styles in the range of startIndex (inclusive) and endIndex (exclusive).

Parameters
int startIndex

the inclusive start offset of the range

int endIndex

the exclusive end offset of the range

toString

public @NonNull String toString()

Extension functions

AnnotatedStringKt.capitalize

public final @NonNull AnnotatedString AnnotatedStringKt.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.

AnnotatedStringKt.decapitalize

public final @NonNull AnnotatedString AnnotatedStringKt.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.

AnnotatedStringKt.toLowerCase

public final @NonNull AnnotatedString AnnotatedStringKt.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.

AnnotatedStringKt.toUpperCase

public final @NonNull AnnotatedString AnnotatedStringKt.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.