androidx.ui.text

Classes

AnnotatedString

The basic data structure of text with multiple styles.

Locale

A Locale object represents a specific geographical, political, or cultural region.

LocaleList

Defines a list of Locale objects.

MultiParagraph

Lays out and renders multiple paragraphs at once.

MultiParagraphIntrinsics

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

ParagraphConstraints

Layout constraints for Paragraph objects.

ParagraphStyle

Paragraph styling configuration for a paragraph.

TextDelegate

An object that paints text onto a Canvas.

TextRange

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

TextSpan

A TextSpan object can be styled using its style property.

TextStyle

Styling configuration for a Text.

Top-level functions summary

AnnotatedString
AnnotatedString(text: String, textStyle: TextStyle, paragraphStyle: ParagraphStyle? = null)

Create an AnnotatedString with a textStyle 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, paragraphStyle: ParagraphStyle, textStyles: List<AnnotatedString.Item<TextStyle>>, maxLines: Int? = null, ellipsis: Boolean? = null, constraints: ParagraphConstraints, density: Density, resourceLoader: Font.ResourceLoader)

Lays out a given text with the given constraints.

Paragraph
Paragraph(paragraphIntrinsics: ParagraphIntrinsics, maxLines: Int? = null, ellipsis: Boolean? = null, constraints: ParagraphConstraints)

Lays out the text in ParagraphIntrinsics with the given constraints.

ParagraphIntrinsics
ParagraphIntrinsics(text: String, style: TextStyle, paragraphStyle: ParagraphStyle, textStyles: List<AnnotatedString.Item<TextStyle>>, density: Density, resourceLoader: Font.ResourceLoader)

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

Interpolate between two text styles.

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 TextSpan
AnnotatedString

Convert a TextSpan into an AnnotatedString.

For Builder
R
AnnotatedString.Builder.withStyle(style: TextStyle, 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,
    textStyle: TextStyle,
    paragraphStyle: ParagraphStyle? = null
): AnnotatedString

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

Parameters
textStyle: TextStyle TextStyle 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

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

import androidx.ui.text.AnnotatedString
import androidx.ui.text.TextStyle
import androidx.ui.text.withStyle

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

Paragraph

fun Paragraph(
    text: String,
    style: TextStyle,
    paragraphStyle: ParagraphStyle,
    textStyles: List<AnnotatedString.Item<TextStyle>>,
    maxLines: Int? = null,
    ellipsis: Boolean? = null,
    constraints: ParagraphConstraints,
    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.

Parameters
text: String the text to be laid out
style: TextStyle the TextStyle to be applied to the whole text
paragraphStyle: ParagraphStyle the ParagraphStyle to be applied to the whole text
textStyles: List<AnnotatedString.Item<TextStyle>> TextStyles to be applied to parts of text
maxLines: Int? = null the maximum number of lines that the text can have
ellipsis: Boolean? = null whether to ellipsize text, applied only when maxLines is set
constraints: ParagraphConstraints 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 TextStyles
Exceptions
IllegalArgumentException if ParagraphStyle.textDirectionAlgorithm is not set

Paragraph

fun Paragraph(
    paragraphIntrinsics: ParagraphIntrinsics,
    maxLines: Int? = null,
    ellipsis: Boolean? = null,
    constraints: ParagraphConstraints
): 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? = null the maximum number of lines that the text can have
ellipsis: Boolean? = null whether to ellipsize text, applied only when maxLines is set
constraints: ParagraphConstraints how wide the text is allowed to be

ParagraphIntrinsics

fun ParagraphIntrinsics(
    text: String,
    style: TextStyle,
    paragraphStyle: ParagraphStyle,
    textStyles: List<AnnotatedString.Item<TextStyle>>,
    density: Density,
    resourceLoader: Font.ResourceLoader
): ParagraphIntrinsics
Exceptions
IllegalArgumentException if ParagraphStyle.textDirectionAlgorithm is not set

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.

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

toAnnotatedString

fun TextSpan.toAnnotatedString(): AnnotatedString

Convert a TextSpan into an AnnotatedString.

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: TextStyle,
    crossinline block: AnnotatedString.Builder.() -> R
): R

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

import androidx.ui.text.TextStyle
import androidx.ui.text.withStyle

with(AnnotatedString.Builder()) {
    withStyle(TextStyle(color = Color.Green)) {
        // green text style will be applied to all text in this block
        append("Hello")
    }
    toAnnotatedString()
}
Parameters
style: TextStyle TextStyle 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.ui.text.TextStyle
import androidx.ui.text.withStyle

with(AnnotatedString.Builder()) {
    withStyle(TextStyle(color = Color.Green)) {
        // green text style will be applied to all text in this block
        append("Hello")
    }
    toAnnotatedString()
}
Parameters
style: ParagraphStyle TextStyle 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.