androidx.compose.ui.text

Interfaces

Paragraph

A paragraph of text that is laid out.

ParagraphIntrinsics

Calculates and presents the intrinsic width and height of text.

Typeface

A class that can be used for changing the font used in text.

Classes

AnnotatedString

The basic data structure of text with multiple styles.

MultiParagraph

Lays out and renders multiple paragraphs at once.

MultiParagraphIntrinsics

Calculates and provides the intrinsic width and height of text that contains ParagraphStyle.

ParagraphStyle

Paragraph styling configuration for a paragraph.

Placeholder

A placeholder is a rectangle box inserted into text, which tells the text processor to leave an empty space.

SoftwareKeyboardController

Provide software keyboard control.

SpanStyle

Styling configuration for a text span.

TextLayoutInput

The data class which holds the set of parameters of the text layout computation.

TextLayoutResult

The data class which holds text layout result.

TextRange

An immutable text range class, represents a text range from start (inclusive) to end (exclusive).

TextStyle

Styling configuration for a Text.

Type-aliases

ParagraphStyleRange

The class changes the paragraph level style of the specified range.

SpanStyleRange

The class changes the character level style of the specified range.

StringAnnotation

The class that stores a string type annotation.

Annotations

InternalTextApi

Enums

PlaceholderVerticalAlign

The settings used to specify how a placeholder is vertically aligned within a text line.

Top-level functions summary

AnnotatedString
AnnotatedString(text: String, spanStyle: SpanStyle, paragraphStyle: ParagraphStyle? = null)

Create an AnnotatedString with a spanStyle that will apply to the whole text.

AnnotatedString
AnnotatedString(text: String, paragraphStyle: ParagraphStyle)

Create an AnnotatedString with a paragraphStyle that will apply to the whole text.

AnnotatedString

Build a new AnnotatedString by populating newly created AnnotatedString.Builder provided by builder.

Paragraph
Paragraph(text: String, style: TextStyle, spanStyles: List<AnnotatedString.Range<SpanStyle>> = listOf(), placeholders: List<AnnotatedString.Range<Placeholder>> = listOf(), maxLines: Int = DefaultMaxLines, ellipsis: Boolean = false, width: Float, density: Density, resourceLoader: Font.ResourceLoader)

Lays out a given text with the given constraints.

Paragraph
Paragraph(paragraphIntrinsics: ParagraphIntrinsics, maxLines: Int = DefaultMaxLines, ellipsis: Boolean = false, width: Float)

Lays out the text in ParagraphIntrinsics with the given constraints.

ParagraphIntrinsics
ParagraphIntrinsics(text: String, style: TextStyle, spanStyles: List<AnnotatedString.Range<SpanStyle>> = listOf(), placeholders: List<AnnotatedString.Range<Placeholder>> = listOf(), density: Density, resourceLoader: Font.ResourceLoader)

Factory method to create a ParagraphIntrinsics.

TextRange
TextRange(index: Int)

Creates a TextRange where start is equal to end, and the value of those are index.

AnnotatedString

Build a new AnnotatedString by populating newly created AnnotatedString.Builder provided by builder.

TextLayoutResult
createTextLayoutResult(layoutInput: TextLayoutInput = TextLayoutInput( text = AnnotatedString(""), style = TextStyle(), placeholders = emptyList(), maxLines = 1, softWrap = false, overflow = TextOverflow.Clip, density = Density(1f), layoutDirection = LayoutDirection.Ltr, resourceLoader = object : Font.ResourceLoader { override fun load(font: Font): Any { return false } }, constraints = Constraints() ), multiParagraph: MultiParagraph = MultiParagraph( annotatedString = layoutInput.text, style = layoutInput.style, width = 0f, density = layoutInput.density, resourceLoader = layoutInput.resourceLoader ), size: IntSize = IntSize.Zero)

ParagraphStyle
lerp(start: ParagraphStyle, stop: ParagraphStyle, fraction: Float)

Interpolate between two ParagraphStyles.

SpanStyle
lerp(start: SpanStyle, stop: SpanStyle, fraction: Float)

Interpolate between two span styles.

TextStyle
lerp(start: TextStyle, stop: TextStyle, fraction: Float)

Interpolate between two text styles.

TextStyle

Fills missing values in TextStyle with default values and resolve TextDirection.

Extension functions summary

For kotlin.CharSequence
String

For kotlin.String
String

Returns capitalized String.

String

Returns capitalized String.

String

Returns decapitalized String.

String

Returns decapitalized String.

String

Returns lowercase transformed String.

String

Returns lowercase transformed String.

String

Returns uppercase transformed String.

String

Returns uppercase transformed String.

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

Create capitalized AnnotatedString

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

Create capitalized AnnotatedString

AnnotatedString

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

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

Create lower case transformed AnnotatedString

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

Create upper case transformed AnnotatedString

For Builder
R
AnnotatedString.Builder.withStyle(style: SpanStyle, crossinline block: AnnotatedString.Builder.() -> R)

Pushes style to the AnnotatedString.Builder, executes block and then pops the style.

R

Pushes style to the AnnotatedString.Builder, executes block and then pops the style.

Extension properties summary

For AnnotatedString
Int

Returns the length of the AnnotatedString.

Top-level functions

AnnotatedString

fun AnnotatedString(
    text: String,
    spanStyle: SpanStyle,
    paragraphStyle: ParagraphStyle? = null
): AnnotatedString

Create an AnnotatedString with a spanStyle that will apply to the whole text.

Parameters
spanStyle: SpanStyle SpanStyle to be applied to whole text
paragraphStyle: ParagraphStyle? = null ParagraphStyle to be applied to whole text

AnnotatedString

fun AnnotatedString(
    text: String,
    paragraphStyle: ParagraphStyle
): AnnotatedString

Create an AnnotatedString with a paragraphStyle that will apply to the whole text.

Parameters
paragraphStyle: ParagraphStyle ParagraphStyle to be applied to whole text

AnnotatedString

inline fun AnnotatedString(builder: AnnotatedString.Builder.() -> Unit): AnnotatedString

Deprecated.

Build a new AnnotatedString by populating newly created AnnotatedString.Builder provided by builder.

import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.annotatedString
import androidx.compose.ui.text.withStyle

// create an AnnotatedString using the lambda builder
annotatedString {
    // append "Hello" with red text color
    withStyle(SpanStyle(color = Color.Red)) {
        append("Hello")
    }
    append(" ")
    // append "Hello" with blue text color
    withStyle(SpanStyle(color = Color.Blue)) {
        append("World!")
    }
}
Parameters
builder: AnnotatedString.Builder.() -> Unit lambda to modify AnnotatedString.Builder

Paragraph

fun Paragraph(
    text: String,
    style: TextStyle,
    spanStyles: List<AnnotatedString.Range<SpanStyle>> = listOf(),
    placeholders: List<AnnotatedString.Range<Placeholder>> = listOf(),
    maxLines: Int = DefaultMaxLines,
    ellipsis: Boolean = false,
    width: Float,
    density: Density,
    resourceLoader: Font.ResourceLoader
): Paragraph

Lays out a given text with the given constraints. A paragraph is a text that has a single ParagraphStyle.

If the style does not contain any androidx.compose.ui.text.style.TextDirection, androidx.compose.ui.text.style.TextDirection.Content is used as the default value.

Parameters
text: String the text to be laid out
style: TextStyle the TextStyle to be applied to the whole text
spanStyles: List<AnnotatedString.Range<SpanStyle>> = listOf() SpanStyles to be applied to parts of text
placeholders: List<AnnotatedString.Range<Placeholder>> = listOf() a list of placeholder metrics which tells Paragraph where should be left blank to leave space for inline elements.
maxLines: Int = DefaultMaxLines the maximum number of lines that the text can have
ellipsis: Boolean = false whether to ellipsize text, applied only when maxLines is set
width: Float how wide the text is allowed to be
density: Density density of the device
resourceLoader: Font.ResourceLoader Font.ResourceLoader to be used to load the font given in SpanStyles
Exceptions
IllegalArgumentException if ParagraphStyle.textDirection is not set

Paragraph

fun Paragraph(
    paragraphIntrinsics: ParagraphIntrinsics,
    maxLines: Int = DefaultMaxLines,
    ellipsis: Boolean = false,
    width: Float
): Paragraph

Lays out the text in ParagraphIntrinsics with the given constraints. A paragraph is a text that has a single ParagraphStyle.

Parameters
paragraphIntrinsics: ParagraphIntrinsics ParagraphIntrinsics instance
maxLines: Int = DefaultMaxLines the maximum number of lines that the text can have
ellipsis: Boolean = false whether to ellipsize text, applied only when maxLines is set
width: Float how wide the text is allowed to be

ParagraphIntrinsics

fun ParagraphIntrinsics(
    text: String,
    style: TextStyle,
    spanStyles: List<AnnotatedString.Range<SpanStyle>> = listOf(),
    placeholders: List<AnnotatedString.Range<Placeholder>> = listOf(),
    density: Density,
    resourceLoader: Font.ResourceLoader
): ParagraphIntrinsics

Factory method to create a ParagraphIntrinsics.

If the style does not contain any androidx.compose.ui.text.style.TextDirection, androidx.compose.ui.text.style.TextDirection.Content is used as the default value.

TextRange

fun TextRange(index: Int): TextRange

Creates a TextRange where start is equal to end, and the value of those are index.

annotatedString

inline fun annotatedString(builder: AnnotatedString.Builder.() -> Unit): AnnotatedString

Build a new AnnotatedString by populating newly created AnnotatedString.Builder provided by builder.

import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.annotatedString
import androidx.compose.ui.text.withStyle

// create an AnnotatedString using the lambda builder
annotatedString {
    // append "Hello" with red text color
    withStyle(SpanStyle(color = Color.Red)) {
        append("Hello")
    }
    append(" ")
    // append "Hello" with blue text color
    withStyle(SpanStyle(color = Color.Blue)) {
        append("World!")
    }
}
Parameters
builder: AnnotatedString.Builder.() -> Unit lambda to modify AnnotatedString.Builder

createTextLayoutResult

fun createTextLayoutResult(
    layoutInput: TextLayoutInput = TextLayoutInput( text = AnnotatedString(""), style = TextStyle(), placeholders = emptyList(), maxLines = 1, softWrap = false, overflow = TextOverflow.Clip, density = Density(1f), layoutDirection = LayoutDirection.Ltr, resourceLoader = object : Font.ResourceLoader { override fun load(font: Font): Any { return false } }, constraints = Constraints() ),
    multiParagraph: MultiParagraph = MultiParagraph( annotatedString = layoutInput.text, style = layoutInput.style, width = 0f, density = layoutInput.density, resourceLoader = layoutInput.resourceLoader ),
    size: IntSize = IntSize.Zero
): TextLayoutResult

lerp

@Stable fun lerp(
    start: ParagraphStyle,
    stop: ParagraphStyle,
    fraction: Float
): ParagraphStyle

Interpolate between two ParagraphStyles.

This will not work well if the styles don't set the same fields.

The fraction argument represents position on the timeline, with 0.0 meaning that the interpolation has not started, returning start (or something equivalent to start), 1.0 meaning that the interpolation has finished, returning stop (or something equivalent to stop), and values in between meaning that the interpolation is at the relevant point on the timeline between start and stop. The interpolation can be extrapolated beyond 0.0 and 1.0, so negative values and values greater than 1.0 are valid.

lerp

fun lerp(
    start: SpanStyle,
    stop: SpanStyle,
    fraction: Float
): SpanStyle

Interpolate between two span styles.

This will not work well if the styles don't set the same fields.

The fraction argument represents position on the timeline, with 0.0 meaning that the interpolation has not started, returning start (or something equivalent to start), 1.0 meaning that the interpolation has finished, returning stop (or something equivalent to stop), and values in between meaning that the interpolation is at the relevant point on the timeline between start and stop. The interpolation can be extrapolated beyond 0.0 and 1.0, so negative values and values greater than 1.0 are valid.

lerp

fun lerp(
    start: TextStyle,
    stop: TextStyle,
    fraction: Float
): TextStyle

Interpolate between two text styles.

This will not work well if the styles don't set the same fields.

The fraction argument represents position on the timeline, with 0.0 meaning that the interpolation has not started, returning start (or something equivalent to start), 1.0 meaning that the interpolation has finished, returning stop (or something equivalent to stop), and values in between meaning that the interpolation is at the relevant point on the timeline between start and stop. The interpolation can be extrapolated beyond 0.0 and 1.0, so negative values and values greater than 1.0 are valid.

resolveDefaults

fun resolveDefaults(
    style: TextStyle,
    direction: LayoutDirection
): TextStyle

Fills missing values in TextStyle with default values and resolve TextDirection.

This function will fill all null or TextUnit.Inherit field with actual values.

Parameters
style: TextStyle a text style to be resolved
direction: LayoutDirection a layout direction to be used for resolving text layout direction algorithm
Return
resolved text style.

Extension functions

capitalize

fun String.capitalize(locale: Locale): String

Returns capitalized String.

Parameters
locale: Locale a locale object
Return
a transformed text

capitalize

fun String.capitalize(localeList: LocaleList): String

Returns capitalized String.

Parameters
localeList: LocaleList a locale list object. If empty locale list object is passed, use current locale instead.
Return
a transformed text

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.
Return
A capitalized string.

decapitalize

fun String.decapitalize(locale: Locale): String

Returns decapitalized String.

Parameters
locale: Locale a locale object
Return
a transformed text

decapitalize

fun String.decapitalize(localeList: LocaleList): String

Returns decapitalized String.

Parameters
localeList: LocaleList a locale list object. If empty locale list object is passed, use current locale instead.

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.
Return
A decapitalized string.

subSequence

fun AnnotatedString.subSequence(
    start: Int,
    end: Int
): AnnotatedString

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

Parameters
start: Int the inclusive start offset of the range
end: Int the exclusive end offset of the range

substring

fun CharSequence.substring(range: TextRange): String

toLowerCase

fun String.toLowerCase(locale: Locale): String

Returns lowercase transformed String.

Parameters
locale: Locale a locale object
Return
a transformed text

toLowerCase

fun String.toLowerCase(localeList: LocaleList): String

Returns lowercase transformed String.

Parameters
localeList: LocaleList a locale list object. If empty locale list object is passed, use current locale instead.
Return
a transformed text

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.
Return
A lowercase transformed string.

toUpperCase

fun String.toUpperCase(locale: Locale): String

Returns uppercase transformed String.

Parameters
locale: Locale a locale object
Return
a transformed text

toUpperCase

fun String.toUpperCase(localeList: LocaleList): String

Returns uppercase transformed String.

Parameters
localeList: LocaleList a locale list object. If empty locale list object is passed, use current locale instead.
Return
a transformed text

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.
Return
A uppercase transformed string.

withStyle

inline fun <R : Any> AnnotatedString.Builder.withStyle(
    style: SpanStyle,
    crossinline block: AnnotatedString.Builder.() -> R
): R

Pushes style to the AnnotatedString.Builder, executes block and then pops the style.

import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.withStyle

with(AnnotatedString.Builder()) {
    withStyle(SpanStyle(color = Color.Green)) {
        // green text style will be applied to all text in this block
        append("Hello")
    }
    toAnnotatedString()
}
Parameters
style: SpanStyle SpanStyle to be applied
block: AnnotatedString.Builder.() -> R function to be executed
Return
result of the block

withStyle

inline fun <R : Any> AnnotatedString.Builder.withStyle(
    style: ParagraphStyle,
    crossinline block: AnnotatedString.Builder.() -> R
): R

Pushes style to the AnnotatedString.Builder, executes block and then pops the style.

import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.withStyle

with(AnnotatedString.Builder()) {
    withStyle(SpanStyle(color = Color.Green)) {
        // green text style will be applied to all text in this block
        append("Hello")
    }
    toAnnotatedString()
}
Parameters
style: ParagraphStyle SpanStyle to be applied
block: AnnotatedString.Builder.() -> R function to be executed
Return
result of the block

Extension properties

length

val AnnotatedString.length: Int

Returns the length of the AnnotatedString.