AnnotatedString


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

Summary

Nested types

Builder class for AnnotatedString.

data class AnnotatedString.Range<T : Any?>

The information attached on the text such as a SpanStyle.

Public companion properties

Saver<AnnotatedString, *>

The default Saver implementation for AnnotatedString.

Cmn

Public constructors

AnnotatedString(
    text: String,
    spanStyles: List<AnnotatedString.Range<SpanStyle>>,
    paragraphStyles: List<AnnotatedString.Range<ParagraphStyle>>
)

The basic data structure of text with multiple styles.

Cmn

Public functions

open operator Boolean
equals(other: Any?)
Cmn
open operator Char
get(index: Int)
Cmn
List<AnnotatedString.Range<LinkAnnotation>>
getLinkAnnotations(start: Int, end: Int)

Query all of the LinkAnnotations attached on this AnnotatedString.

Cmn
List<AnnotatedString.Range<String>>
getStringAnnotations(start: Int, end: Int)

Query all of the string annotations attached on this AnnotatedString.

Cmn
List<AnnotatedString.Range<String>>
getStringAnnotations(tag: String, start: Int, end: Int)

Query the string annotations attached on this AnnotatedString.

Cmn
List<AnnotatedString.Range<TtsAnnotation>>
getTtsAnnotations(start: Int, end: Int)

Query all of the TtsAnnotations attached on this AnnotatedString.

Cmn
List<AnnotatedString.Range<UrlAnnotation>>

Query all of the UrlAnnotations attached on this AnnotatedString.

Cmn
Boolean

Compare the annotations between this and another AnnotatedString.

Cmn
Boolean
hasLinkAnnotations(start: Int, end: Int)

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

Cmn
Boolean
hasStringAnnotations(tag: String, start: Int, end: Int)

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

Cmn
open Int
Cmn
operator AnnotatedString
Cmn
AnnotatedString

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

Cmn
open AnnotatedString
subSequence(startIndex: Int, endIndex: Int)

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

Cmn
open String
Cmn

Public properties

open Int
Cmn
List<AnnotatedString.Range<ParagraphStyle>>

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

Cmn
List<AnnotatedString.Range<SpanStyle>>

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

Cmn
String
Cmn

Extension functions

AnnotatedString

Create capitalized AnnotatedString

Cmn
AnnotatedString

Create capitalized AnnotatedString

Cmn
AnnotatedString

Create lower case transformed AnnotatedString

Cmn
AnnotatedString

Create upper case transformed AnnotatedString

Cmn

Public companion properties

Saver

val SaverSaver<AnnotatedString, *>

The default Saver implementation for AnnotatedString.

Public constructors

AnnotatedString

AnnotatedString(
    text: String,
    spanStyles: List<AnnotatedString.Range<SpanStyle>> = listOf(),
    paragraphStyles: List<AnnotatedString.Range<ParagraphStyle>> = listOf()
)

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.style.TextIndent

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
text: String

the text to be displayed.

spanStyles: List<AnnotatedString.Range<SpanStyle>> = listOf()

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.

paragraphStyles: List<AnnotatedString.Range<ParagraphStyle>> = listOf()

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 functions

equals

open operator fun equals(other: Any?): Boolean

get

open operator fun get(index: Int): Char

getLinkAnnotations

fun getLinkAnnotations(start: Int, end: Int): List<AnnotatedString.Range<LinkAnnotation>>

Query all of the LinkAnnotations attached on this AnnotatedString.

Parameters
start: Int

the start of the query range, inclusive.

end: Int

the end of the query range, exclusive.

Returns
List<AnnotatedString.Range<LinkAnnotation>>

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

fun getStringAnnotations(start: Int, end: Int): List<AnnotatedString.Range<String>>

Query all of the string annotations attached on this AnnotatedString.

Parameters
start: Int

the start of the query range, inclusive.

end: Int

the end of the query range, exclusive.

Returns
List<AnnotatedString.Range<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

fun getStringAnnotations(tag: String, start: Int, end: Int): List<AnnotatedString.Range<String>>

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
tag: String

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

start: Int

the start of the query range, inclusive.

end: Int

the end of the query range, exclusive.

Returns
List<AnnotatedString.Range<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.

getTtsAnnotations

fun getTtsAnnotations(start: Int, end: Int): List<AnnotatedString.Range<TtsAnnotation>>

Query all of the TtsAnnotations attached on this AnnotatedString.

Parameters
start: Int

the start of the query range, inclusive.

end: Int

the end of the query range, exclusive.

Returns
List<AnnotatedString.Range<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
fun getUrlAnnotations(start: Int, end: Int): List<AnnotatedString.Range<UrlAnnotation>>

Query all of the UrlAnnotations attached on this AnnotatedString.

Parameters
start: Int

the start of the query range, inclusive.

end: Int

the end of the query range, exclusive.

Returns
List<AnnotatedString.Range<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.

hasEqualsAnnotations

fun hasEqualsAnnotations(other: AnnotatedString): Boolean

Compare the annotations between this and another AnnotatedString.

This may be used for fast partial equality checks.

Note that this only checks annotations, and equals still may be false if any of spanStyles, paragraphStyles, or text are different.

Parameters
other: AnnotatedString

to compare annotations with

Returns
Boolean

true iff this compares equal on annotations with other

hasLinkAnnotations

fun hasLinkAnnotations(start: Int, end: Int): Boolean

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

hasStringAnnotations

fun hasStringAnnotations(tag: String, start: Int, end: Int): Boolean

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

hashCode

open fun hashCode(): Int

plus

operator fun plus(other: AnnotatedString): AnnotatedString

subSequence

fun subSequence(range: TextRange): AnnotatedString

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

Parameters
range: TextRange

the text range

See also
subSequence

(start: Int, end: Int)

subSequence

open fun subSequence(startIndex: Int, endIndex: Int): AnnotatedString

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

Parameters
startIndex: Int

the inclusive start offset of the range

endIndex: Int

the exclusive end offset of the range

toString

open fun toString(): String

Public properties

length

open val lengthInt

paragraphStyles

val paragraphStylesList<AnnotatedString.Range<ParagraphStyle>>

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

spanStyles

val spanStylesList<AnnotatedString.Range<SpanStyle>>

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

text

val textString

Extension functions

capitalize

fun AnnotatedString.capitalize(localeList: LocaleList = LocaleList.current): AnnotatedString

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
localeList: LocaleList = LocaleList.current

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
AnnotatedString

A capitalized string.

decapitalize

fun AnnotatedString.decapitalize(localeList: LocaleList = LocaleList.current): AnnotatedString

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
localeList: LocaleList = LocaleList.current

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
AnnotatedString

A decapitalized string.

toLowerCase

fun AnnotatedString.toLowerCase(localeList: LocaleList = LocaleList.current): AnnotatedString

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
localeList: LocaleList = LocaleList.current

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
AnnotatedString

A lowercase transformed string.

toUpperCase

fun AnnotatedString.toUpperCase(localeList: LocaleList = LocaleList.current): AnnotatedString

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
localeList: LocaleList = LocaleList.current

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
AnnotatedString

A uppercase transformed string.