AnnotatedString

Added in 1.0.0

Cmn
```
class AnnotatedString : CharSequence
```

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

Summary

Nested types
`sealed interface AnnotatedString.Annotation` Defines annotations that specify additional information to apply to ranges of text within the given AnnotatedString.
`class AnnotatedString.Builder` Builder class for AnnotatedString.
`class AnnotatedString.Builder.BulletScope` Scope for a bullet list
`object AnnotatedString.Companion`
`data class AnnotatedString.Range<T : Any?>` The information attached on the text such as a `SpanStyle`.

Public companion properties
`Saver<AnnotatedString, *>`	`Saver` The default `Saver` implementation for `AnnotatedString`.	Cmn

Public constructors
`AnnotatedString( text: String, annotations: List<AnnotatedString.Range<AnnotatedString.Annotation>> )` 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`	`flatMapAnnotations( transform: (AnnotatedString.Range<AnnotatedString.Annotation>) -> List<AnnotatedString.Range<AnnotatedString.Annotation>> )` 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 `LinkAnnotation`s 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 `TtsAnnotation`s attached on this `AnnotatedString`.	Cmn
`List<AnnotatedString.Range<UrlAnnotation>>`	`@ExperimentalTextApi getUrlAnnotations(start: Int, end: Int)` This function is deprecated. Use LinkAnnotation API instead	Cmn
`Boolean`	`hasEqualAnnotations(other: AnnotatedString)` 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`	`hashCode()`	Cmn
`AnnotatedString`	`mapAnnotations( transform: (AnnotatedString.Range<AnnotatedString.Annotation>) -> AnnotatedString.Range<AnnotatedString.Annotation> )` 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`	`plus(other: AnnotatedString)`	Cmn
`AnnotatedString`	`subSequence(range: TextRange)` 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`	`toString()`	Cmn

Public properties
`open Int`	`length`	Cmn
`List<AnnotatedString.Range<ParagraphStyle>>`	`paragraphStyles` All `ParagraphStyle` that have been applied to a range of this String	Cmn
`List<AnnotatedString.Range<SpanStyle>>`	`spanStyles` All `SpanStyle` that have been applied to a range of this String	Cmn
`String`	`text`	Cmn

Extension functions
`AnnotatedString`	`AnnotatedString.capitalize(localeList: LocaleList)` Create capitalized `AnnotatedString`	Cmn
`AnnotatedString`	`AnnotatedString.decapitalize(localeList: LocaleList)` Create capitalized `AnnotatedString`	Cmn
`AnnotatedString`	`AnnotatedString.toLowerCase(localeList: LocaleList)` Create lower case transformed `AnnotatedString`	Cmn
`AnnotatedString`	`AnnotatedString.toUpperCase(localeList: LocaleList)` 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 `ParagraphStyle`s contains any two overlapping `Range`s.

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 `Range`s that specifies `SpanStyle`s on certain portion of the text. These styles will be applied in the order of the list. And the `SpanStyle`s 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 `Range`s that specifies `ParagraphStyle`s on certain portion of the text. Each `ParagraphStyle` with a `Range` defines a paragraph of text. It's required that `Range`s of paragraphs don't overlap with each other. If there are gaps between specified paragraph `Range`s, a default paragraph will be created in between.

Throws
`kotlin.IllegalArgumentException`	if `paragraphStyles` contains any two overlapping `Range`s.

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

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

Added in 1.10.0-rc01

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

Artifact: androidx.compose.ui:ui-text

View Source

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

Artifact: androidx.compose.ui:ui-text

View Source

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

Artifact: androidx.compose.ui:ui-text

View Source

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

Artifact: androidx.compose.ui:ui-text

View Source

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.

AnnotatedString

Summary

Nested types

Public companion properties

Public constructors

Public functions

Public properties

Extension functions

Public companion properties

Saver

Public constructors

AnnotatedString

AnnotatedString

Public functions

equals

flatMapAnnotations

get

getLinkAnnotations

getStringAnnotations

getStringAnnotations

getTtsAnnotations

getUrlAnnotations

hasEqualAnnotations

hasLinkAnnotations

hasStringAnnotations

hashCode

mapAnnotations

plus

subSequence

subSequence

toString

Public properties

length

paragraphStyles

spanStyles

text

Extension functions

capitalize

decapitalize

toLowerCase

toUpperCase