AnnotatedString

Class

Common

class AnnotatedString
internal constructor(internal val annotations: List<Range<out Annotation>>?, val text: String) :
    CharSequence

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

Secondary Constructors

constructor(
    text: String,
    spanStyles: List<Range<SpanStyle>> = listOf(),
    paragraphStyles: List<Range<ParagraphStyle>> = listOf(),
) : this(constructAnnotationsFromSpansAndParagraphs(spanStyles, paragraphStyles), text)

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.

Parameters


text	the text to be displayed.
spanStyles	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	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.

constructor(
    text: String,
    annotations: List<Range<out Annotation>> = listOf(),
) : this(annotations.ifEmpty { null }, text)

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

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.

Parameters


text	the text to be displayed.
annotations	a list of `Range`s that specifies `Annotation`s 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:

Properties

Common

val spanStyles: List<Range<SpanStyle>>

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

Common

val paragraphStyles: List<Range<ParagraphStyle>>

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

Functions

fun subSequence(range: TextRange): AnnotatedString

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

Parameters


range	the text range

operator fun plus(other: AnnotatedString): AnnotatedString

fun getStringAnnotations(tag: String, start: Int, end: Int): List<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	the tag of the annotations that is being queried. It's used to distinguish the annotations for different purposes.
start	the start of the query range, inclusive.
end	the end of the query range, exclusive.

Returns


	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.

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

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

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

Query all of the string annotations attached on this AnnotatedString.

Parameters


start	the start of the query range, inclusive.
end	the end of the query range, exclusive.

Returns


	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.

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

Query all of the TtsAnnotations attached on this AnnotatedString.

Parameters


start	the start of the query range, inclusive.
end	the end of the query range, exclusive.

Returns


	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.

@ExperimentalTextApi
    
    
    fun getUrlAnnotations(start: Int, end: Int): List<Range<UrlAnnotation>>

Query all of the UrlAnnotations attached on this AnnotatedString.

Parameters


start	the start of the query range, inclusive.
end	the end of the query range, exclusive.

Returns


	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.

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

Query all of the LinkAnnotations attached on this AnnotatedString.

Parameters


start	the start of the query range, inclusive.
end	the end of the query range, exclusive.

Returns


	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.

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

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

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	to compare annotations with

Returns


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

fun mapAnnotations(
        transform: (Range<out Annotation>) -> Range<out 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.

fun flatMapAnnotations(
        transform: (Range<out Annotation>) -> List<Range<out 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.

Companion Object

Properties

Common

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