{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

TextMeasurer

public final class TextMeasurer


TextMeasurer is responsible for measuring a text in its entirety so that it's ready to be drawn.

A TextMeasurer instance should be created via androidx.compose.ui.rememberTextMeasurer in a Composable context to use fallback values from default composition locals.

Text layout is a computationally expensive task. Therefore, this class holds an internal LRU Cache of layout input and output pairs to optimize the repeated measure calls that use the same input parameters.

Although most input parameters have a direct influence on layout, some parameters like color, brush, and shadow can be ignored during layout and set at the end. Using TextMeasurer with appropriate cacheSize should provide significant improvements while animating non-layout-affecting attributes like color.

Moreover, if there is a need to render multiple static texts, you can provide the number of texts by cacheSize and their layouts should be cached for repeating calls. Be careful that even a slight change in input parameters like fontSize, maxLines, an additional character in text would create a distinct set of input parameters. As a result, a new layout would be calculated and a new set of input and output pair would be placed in LRU Cache, possibly evicting an earlier result.

FontFamily.Resolver, LayoutDirection, and Density are required parameters to construct a text layout but they have no safe fallbacks outside of composition. These parameters must be provided during the construction of a TextMeasurer to be used as default values when they are skipped in TextMeasurer.measure call.

Summary

Public constructors

TextMeasurer(
    @NonNull FontFamily.Resolver fallbackFontFamilyResolver,
    @NonNull Density fallbackDensity,
    @NonNull LayoutDirection fallbackLayoutDirection,
    int cacheSize
)

Public methods

final @NonNull TextLayoutResult
measure(
    @NonNull String text,
    @NonNull TextStyle style,
    @NonNull TextOverflow overflow,
    boolean softWrap,
    int maxLines,
    @NonNull Constraints constraints,
    @NonNull LayoutDirection layoutDirection,
    @NonNull Density density,
    @NonNull FontFamily.Resolver fontFamilyResolver,
    boolean skipCache
)

Creates a TextLayoutResult according to given parameters.

final @NonNull TextLayoutResult
measure(
    @NonNull AnnotatedString text,
    @NonNull TextStyle style,
    @NonNull TextOverflow overflow,
    boolean softWrap,
    int maxLines,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders,
    @NonNull Constraints constraints,
    @NonNull LayoutDirection layoutDirection,
    @NonNull Density density,
    @NonNull FontFamily.Resolver fontFamilyResolver,
    boolean skipCache
)

Creates a TextLayoutResult according to given parameters.

Public constructors

TextMeasurer

public TextMeasurer(
    @NonNull FontFamily.Resolver fallbackFontFamilyResolver,
    @NonNull Density fallbackDensity,
    @NonNull LayoutDirection fallbackLayoutDirection,
    int cacheSize
)
Parameters
@NonNull FontFamily.Resolver fallbackFontFamilyResolver

to be used to load fonts given in TextStyle and SpanStyles in AnnotatedString.

@NonNull Density fallbackDensity

density of the measurement environment. Density controls the scaling factor for fonts.

@NonNull LayoutDirection fallbackLayoutDirection

layout direction of the measurement environment.

int cacheSize

Capacity of internal cache inside TextMeasurer. Size unit is the number of unique text layout inputs that are measured. Value of this parameter highly depends on the consumer use case. Provide a cache size that is in line with how many distinct text layouts are going to be calculated by this measurer repeatedly. If you are animating font attributes, or any other layout affecting input, cache can be skipped because most repeated measure calls would miss the cache.

Public methods

measure

public final @NonNull TextLayoutResult measure(
    @NonNull String text,
    @NonNull TextStyle style,
    @NonNull TextOverflow overflow,
    boolean softWrap,
    int maxLines,
    @NonNull Constraints constraints,
    @NonNull LayoutDirection layoutDirection,
    @NonNull Density density,
    @NonNull FontFamily.Resolver fontFamilyResolver,
    boolean skipCache
)

Creates a TextLayoutResult according to given parameters.

This function supports laying out text that consists of multiple paragraphs, includes placeholders, wraps around soft line breaks, and might overflow outside the specified size.

Most parameters for text affect the final text layout. One pixel change in constraints boundaries can displace a word to another line which would cause a chain reaction that completely changes how text is rendered.

On the other hand, some attributes only play a role when drawing the created text layout. For example text layout can be created completely in black color but we can apply TextStyle.color later in draw phase. This also means that animating text color shouldn't invalidate text layout.

Thus, textLayoutCache helps in the process of converting a set of text layout inputs to a text layout while ignoring non-layout-affecting attributes. Iterative calls that use the same input parameters should benefit from substantial performance improvements.

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.unit.Constraints
import androidx.compose.ui.unit.sp

textMeasurer.measure(
    text = "Hello, World",
    style = TextStyle(
        color = Color.Red,
        fontSize = 16.sp,
        fontFamily = FontFamily.Cursive
    ),
    constraints = Constraints(
        minWidth = 400,
        maxWidth = 400,
        minHeight = 200,
        maxHeight = 400
    )
)
Parameters
@NonNull String text

the text to be laid out

@NonNull TextStyle style

the TextStyle to be applied to the whole text

@NonNull TextOverflow overflow

How visual overflow should be handled.

boolean softWrap

Whether the text should break at soft line breaks. If false, the glyphs in the text will be positioned as if there was unlimited horizontal space. If softWrap is false, overflow and TextAlign may have unexpected effects.

int maxLines

An optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated according to overflow and softWrap. If it is not null, then it must be greater than zero.

@NonNull Constraints constraints

how wide and tall the text is allowed to be. Constraints.maxWidth will define the width of the MultiParagraph. Constraints.maxHeight helps defining the number of lines that fit with ellipsis is true. Constraints.minWidth defines the minimum width the resulting TextLayoutResult.size will report. Constraints.minHeight is no-op.

@NonNull LayoutDirection layoutDirection

layout direction of the measurement environment. If not specified, defaults to the value that was given during initialization of this TextMeasurer.

@NonNull Density density

density of the measurement environment. If not specified, defaults to the value that was given during initialization of this TextMeasurer.

@NonNull FontFamily.Resolver fontFamilyResolver

to be used to load the font given in SpanStyles. If not specified, defaults to the value that was given during initialization of this TextMeasurer.

boolean skipCache

Disables cache optimization if it is passed as true.

measure

public final @NonNull TextLayoutResult measure(
    @NonNull AnnotatedString text,
    @NonNull TextStyle style,
    @NonNull TextOverflow overflow,
    boolean softWrap,
    int maxLines,
    @NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders,
    @NonNull Constraints constraints,
    @NonNull LayoutDirection layoutDirection,
    @NonNull Density density,
    @NonNull FontFamily.Resolver fontFamilyResolver,
    boolean skipCache
)

Creates a TextLayoutResult according to given parameters.

This function supports laying out text that consists of multiple paragraphs, includes placeholders, wraps around soft line breaks, and might overflow outside the specified size.

Most parameters for text affect the final text layout. One pixel change in constraints boundaries can displace a word to another line which would cause a chain reaction that completely changes how text is rendered.

On the other hand, some attributes only play a role when drawing the created text layout. For example text layout can be created completely in black color but we can apply TextStyle.color later in draw phase. This also means that animating text color shouldn't invalidate text layout.

Thus, textLayoutCache helps in the process of converting a set of text layout inputs to a text layout while ignoring non-layout-affecting attributes. Iterative calls that use the same input parameters should benefit from substantial performance improvements.

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.sp

textMeasurer.measure(
    text = buildAnnotatedString {
        append("Hello, ")
        withStyle(SpanStyle(color = Color.Blue)) {
            append("World!")
        }
    },
    style = TextStyle(
        fontSize = 16.sp,
        fontFamily = FontFamily.Monospace
    )
)
Parameters
@NonNull AnnotatedString text

the text to be laid out

@NonNull TextStyle style

the TextStyle to be applied to the whole text

@NonNull TextOverflow overflow

How visual overflow should be handled.

boolean softWrap

Whether the text should break at soft line breaks. If false, the glyphs in the text will be positioned as if there was unlimited horizontal space. If softWrap is false, overflow and TextAlign may have unexpected effects.

int maxLines

An optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated according to overflow and softWrap. If it is not null, then it must be greater than zero.

@NonNull List<@NonNull AnnotatedString.Range<@NonNull Placeholder>> placeholders

a list of Placeholders that specify ranges of text which will be skipped during layout and replaced with Placeholder. It's required that the range of each Placeholder doesn't cross paragraph boundary, otherwise IllegalArgumentException is thrown.

@NonNull Constraints constraints

how wide and tall the text is allowed to be. Constraints.maxWidth will define the width of the MultiParagraph. Constraints.maxHeight helps defining the number of lines that fit with ellipsis is true. Constraints.minWidth defines the minimum width the resulting TextLayoutResult.size will report. Constraints.minHeight is no-op.

@NonNull LayoutDirection layoutDirection

layout direction of the measurement environment. If not specified, defaults to the value that was given during initialization of this TextMeasurer.

@NonNull Density density

density of the measurement environment. If not specified, defaults to the value that was given during initialization of this TextMeasurer.

@NonNull FontFamily.Resolver fontFamilyResolver

to be used to load the font given in SpanStyles. If not specified, defaults to the value that was given during initialization of this TextMeasurer.

boolean skipCache

Disables cache optimization if it is passed as true.