AnnotatedString

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

Summary

Nested types

Defines annotations that specify additional information to apply to ranges of text within the given AnnotatedString.

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

The basic data structure of text with multiple styles and other annotations.
Cmn
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
AnnotatedString

Returns a new AnnotatedString where a list of annotations contains all elements yielded from results transform function being invoked on each element of original annotations list.
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>>

This function is deprecated. Use LinkAnnotation API instead
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
AnnotatedString

Returns a new AnnotatedString where a list of annotations contains the results of applying the given transform function to each element in the original annotations list.
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

Cmn
Added in 1.7.0
val Saver: Saver<AnnotatedString, *>

The default Saver implementation for AnnotatedString.

Note this Saver doesn't preserve the LinkInteractionListener of the links. You should handle this case manually if required (check https://issuetracker.google.com/issues/332901550 for an example).

Public constructors

AnnotatedString

Cmn 
AnnotatedString(
    text: String,
    annotations: List<AnnotatedString.Range<AnnotatedString.Annotation>> = listOf()
)

The basic data structure of text with multiple styles and other annotations. To construct an AnnotatedString you may use a Builder.

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.AnnotatedString.Range
import androidx.compose.ui.text.LinkAnnotation
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

AnnotatedString(
    text = "Jetpack Compose",
    // mark all text as a link, separate it into two paragraphs and make "Compose" italic
    annotations =
        listOf(
            AnnotatedString.Range(
                LinkAnnotation.Url("https://developer.android.com/jetpack/compose"),
                0,
                15
            ),
            AnnotatedString.Range(ParagraphStyle(textAlign = TextAlign.Center), 0, 8),
            AnnotatedString.Range(SpanStyle(fontStyle = FontStyle.Italic), 8, 15)
        )
)
Parameters
text: String

the text to be displayed.
annotations: List<AnnotatedString.Range<AnnotatedString.Annotation>> = listOf()

a list of Ranges that specifies Annotations on certain portion of the text. These annotations will be applied in the order of the list. There're a few properties that these annotations have:

  • Annotations applied later can override the former annotations. For example, the attributes of the last applied SpanStyle will override similar attributes of the previously applied SpanStyles.

  • SpanStyle attributes which are null or Unspecified won't change the styling.

  • If there are gaps between specified paragraph Ranges, a default paragraph will be created in between.

  • The paragraph Ranges can't partially overlap. They must either not overlap at all, be nested (when inner paragraph's range is fully within the range of the outer paragraph) or fully overlap (when ranges of two paragraph are the same). For more details check the AnnotatedString.Builder.addStyle documentation.
Throws
kotlin.IllegalArgumentException

if ParagraphStyles contains any two overlapping Ranges.
See also
AnnotatedString.Annotation

AnnotatedString

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

If you need to provide other types of Annotations, use an alternative constructor.

import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.AnnotatedString.Range
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
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 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.
See also
SpanStyle
ParagraphStyle

Public functions

equals

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

flatMapAnnotations

Cmn 
fun flatMapAnnotations(
    transform: (AnnotatedString.Range<AnnotatedString.Annotation>) -> List<AnnotatedString.Range<AnnotatedString.Annotation>>
): AnnotatedString

Returns a new AnnotatedString where a list of annotations contains all elements yielded from results transform function being invoked on each element of original annotations list.

See also
mapAnnotations

get

Cmn
Added in 1.0.0
open operator fun get(index: Int): Char

getLinkAnnotations

Cmn
Added in 1.7.0
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

Cmn
Added in 1.0.0
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

Cmn
Added in 1.0.0
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

Cmn
Added in 1.0.0
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

Cmn
Added in 1.3.0
Deprecated in 1.7.0
@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.

hasEqualAnnotations

Cmn
Added in 1.7.0
fun hasEqualAnnotations(other: AnnotatedString): Boolean

Compare the annotations between this and another AnnotatedString.

This may be used for fast partial equality checks.

Note that this checks all annotations including spanStyles and paragraphStyles, but equals still may be false if text is different.

Parameters
other: AnnotatedString

to compare annotations with
Returns
Boolean

true if and only if this compares equal on annotations with other

hasLinkAnnotations

Cmn
Added in 1.7.0
fun hasLinkAnnotations(start: Int, end: Int): Boolean

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

hasStringAnnotations

Cmn
Added in 1.4.0
fun hasStringAnnotations(tag: String, start: Int, end: Int): Boolean

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

hashCode

Cmn 
open fun hashCode(): Int

mapAnnotations

Cmn
Added in 1.8.0-alpha04
fun mapAnnotations(
    transform: (AnnotatedString.Range<AnnotatedString.Annotation>) -> AnnotatedString.Range<AnnotatedString.Annotation>
): AnnotatedString

Returns a new AnnotatedString where a list of annotations contains the results of applying the given transform function to each element in the original annotations list.

import androidx.compose.foundation.text.BasicText
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.AnnotatedString.Range
import androidx.compose.ui.text.LinkAnnotation
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.TextLinkStyles

// An example of applying color to the links in the given text where the `linkColor` would
// usually come from the theme in your app
val linkStyles = TextLinkStyles(style = SpanStyle(color = linkColor))
BasicText(
    text.mapAnnotations {
        when (it.item) {
            is LinkAnnotation.Url ->
                (it as Range<LinkAnnotation.Url>).copy(it.item.copy(styles = linkStyles))
            is LinkAnnotation.Clickable ->
                (it as Range<LinkAnnotation.Clickable>).copy(it.item.copy(styles = linkStyles))
            else -> it
        }
    }
)

plus

Cmn
Added in 1.0.0
operator fun plus(other: AnnotatedString): AnnotatedString

subSequence

Cmn 
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

Cmn
Added in 1.0.0
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

Cmn 
open fun toString(): String

Public properties

length

Cmn
Added in 1.0.0
open val length: Int

paragraphStyles

Cmn
Added in 1.0.0
val paragraphStyles: List<AnnotatedString.Range<ParagraphStyle>>

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

spanStyles

Cmn
Added in 1.0.0
val spanStyles: List<AnnotatedString.Range<SpanStyle>>

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

text

Cmn
Added in 1.0.0
val text: String

Extension functions

capitalize

Cmn 
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

Cmn 
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

Cmn 
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

Cmn 
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.