TextMeasurer

class TextMeasurer(
    private val defaultFontFamilyResolver: FontFamily.Resolver,
    private val defaultDensity: Density,
    private val defaultLayoutDirection: LayoutDirection,
    private val cacheSize: Int = DefaultCacheSize,
)

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.

Parameters

Functions

fun measure(
        text: AnnotatedString,
        style: TextStyle = TextStyle.Default,
        overflow: TextOverflow = TextOverflow.Clip,
        softWrap: Boolean = true,
        maxLines: Int = Int.MAX_VALUE,
        placeholders: List<AnnotatedString.Range<Placeholder>> = listOf(),
        constraints: Constraints = Constraints(),
        layoutDirection: LayoutDirection = this.defaultLayoutDirection,
        density: Density = this.defaultDensity,
        fontFamilyResolver: FontFamily.Resolver = this.defaultFontFamilyResolver,
        skipCache: Boolean = false,
    ): TextLayoutResult

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.

Parameters

fun measure(
        text: String,
        style: TextStyle = TextStyle.Default,
        overflow: TextOverflow = TextOverflow.Clip,
        softWrap: Boolean = true,
        maxLines: Int = Int.MAX_VALUE,
        constraints: Constraints = Constraints(),
        layoutDirection: LayoutDirection = this.defaultLayoutDirection,
        density: Density = this.defaultDensity,
        fontFamilyResolver: FontFamily.Resolver = this.defaultFontFamilyResolver,
        skipCache: Boolean = false,
    ): TextLayoutResult

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.

Parameters

Companion Object