PrecomputedTextCompat

Added in 1.1.0

class PrecomputedTextCompat : Spannable

A text which has the character metrics data. A text object that contains the character metrics data and can be used to improve the performance of text layout operations. When a PrecomputedTextCompat is created with a given CharSequence, it will measure the text metrics during the creation. This PrecomputedText instance can be set on android.widget.TextView or StaticLayout. Since the text layout information will be included in this instance, android.widget.TextView or StaticLayout will not have to recalculate this information. On API 29 or later, there is full PrecomputedText support by framework. From API 21 to API 27, PrecomputedTextCompat relies on internal text layout cache. PrecomputedTextCompat immediately computes the text layout in the constuctor to warm up the internal text layout cache. On API 20 or before, PrecomputedTextCompat does nothing. Note that any android.text.NoCopySpan attached to the original text won't be passed to PrecomputedText.

Summary

Nested types

The information required for building PrecomputedTextCompat.

A builder for creating Params.

Public functions
Char
charAt(index: Int)
java-static PrecomputedTextCompat!

Create a new PrecomputedText which will pre-compute text measurement and glyph positioning information.
@IntRange(from = 0) Int

Returns the count of paragraphs.
@IntRange(from = 0) Int
getParagraphEnd(paraIndex: @IntRange(from = 0) Int)

Returns the paragraph end offset of the text.
@IntRange(from = 0) Int
getParagraphStart(paraIndex: @IntRange(from = 0) Int)

Returns the paragraph start offset of the text.
PrecomputedTextCompat.Params

Returns the parameters used to measure this text.
Int
getSpanEnd(tag: Any!)
Int
Int
Array<T!>!
<T> getSpans(start: Int, end: Int, type: Class<T!>!)
java-static Future<PrecomputedTextCompat!>!
@UiThread
getTextFuture(
    charSequence: CharSequence,
    params: PrecomputedTextCompat.Params,
    executor: Executor?
)

Helper for PrecomputedText that returns a future to be used with setTextFuture.
Int
Int
nextSpanTransition(start: Int, limit: Int, type: Class!)
Unit
removeSpan(what: Any!)
Unit
setSpan(what: Any!, start: Int, end: Int, flags: Int)
CharSequence!
subSequence(start: Int, end: Int)
String

Inherited Constants
From android.text.Spanned
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int
SPAN_PRIORITY = 16711680
const Int
const Int
SPAN_USER = -16777216
const Int

Inherited functions
From java.lang.CharSequence
IntStream!
IntStream!
java-static Int

Public functions

charAt

Added in 1.1.0
fun charAt(index: Int): Char

create

Added in 1.1.0
java-static fun create(text: CharSequence, params: PrecomputedTextCompat.Params): PrecomputedTextCompat!

Create a new PrecomputedText which will pre-compute text measurement and glyph positioning information.

This can be expensive, so computing this on a background thread before your text will be presented can save work on the UI thread.

Note that any android.text.NoCopySpan attached to the text won't be passed to the created PrecomputedText.
Parameters
text: CharSequence

the text to be measured
params: PrecomputedTextCompat.Params

parameters that define how text will be precomputed
Returns
PrecomputedTextCompat!

A PrecomputedText

getParagraphCount

Added in 1.1.0
fun getParagraphCount(): @IntRange(from = 0) Int

Returns the count of paragraphs.

getParagraphEnd

Added in 1.1.0
fun getParagraphEnd(paraIndex: @IntRange(from = 0) Int): @IntRange(from = 0) Int

Returns the paragraph end offset of the text.

getParagraphStart

Added in 1.1.0
fun getParagraphStart(paraIndex: @IntRange(from = 0) Int): @IntRange(from = 0) Int

Returns the paragraph start offset of the text.

getParams

Added in 1.1.0
fun getParams(): PrecomputedTextCompat.Params

Returns the parameters used to measure this text.

getSpanEnd

Added in 1.1.0
fun getSpanEnd(tag: Any!): Int

getSpanFlags

Added in 1.1.0
fun getSpanFlags(tag: Any!): Int

getSpanStart

Added in 1.1.0
fun getSpanStart(tag: Any!): Int

getSpans

Added in 1.1.0
fun <T> getSpans(start: Int, end: Int, type: Class<T!>!): Array<T!>!

getTextFuture

Added in 1.1.0
@UiThread
java-static fun getTextFuture(
    charSequence: CharSequence,
    params: PrecomputedTextCompat.Params,
    executor: Executor?
): Future<PrecomputedTextCompat!>!

Helper for PrecomputedText that returns a future to be used with setTextFuture. PrecomputedText is suited to compute on a background thread, but when TextView properties are dynamic, it's common to configure text properties and text at the same time, when binding a View. For example, in a RecyclerView Adapter: 

    void onBindViewHolder(ViewHolder vh, int position) {
        ItemData data = getData(position);

        vh.textView.setTextSize(...);
        vh.textView.setFontVariationSettings(...);
        vh.textView.setText(data.text);
    }
 In such cases, using PrecomputedText is difficult, since it isn't safe to defer the setText() code arbitrarily - a layout pass may happen before computation finishes, and will be incorrect if the text isn't ready yet.

With getTextFuture(), you can block on the result of the precomputation safely before the result is needed. AppCompatTextView provides setTextFuture for exactly this use case. With the following code, the app's layout work is largely done on a background thread: 

    void onBindViewHolder(ViewHolder vh, int position) {
        ItemData data = getData(position);

        vh.textView.setTextSize(...);
        vh.textView.setFontVariationSettings(...);

        // start precompute
        Futurefuture = PrecomputedTextCompat.getTextFuture(
                data.text, vh.textView.getTextMetricsParamsCompat(), myExecutor);

        // and pass future to TextView, which awaits result before measuring
        vh.textView.setTextFuture(future);
    }
 Because RecyclerView prefetches bind multiple frames in advance while scrolling, the text work generally has plenty of time to complete before measurement occurs.

Note: all TextView layout properties must be set before creating the Params object. If they are changed during the precomputation, this can cause a IllegalArgumentException when the precomputed value is consumed during measure, and doesn't reflect the TextView's current state.

Parameters
charSequence: CharSequence

the text to be displayed
params: PrecomputedTextCompat.Params

the parameters to be used for displaying text
executor: Executor?

the executor to be process the text layout. If null is passed, the default single threaded pool will be used.
Returns
Future<PrecomputedTextCompat!>!

a future of the precomputed text
See also
setTextFuture

length

Added in 1.1.0
fun length(): Int

nextSpanTransition

Added in 1.1.0
fun nextSpanTransition(start: Int, limit: Int, type: Class!): Int

removeSpan

Added in 1.1.0
fun removeSpan(what: Any!): Unit
Throws
java.lang.IllegalArgumentException

if MetricAffectingSpan is specified.

setSpan

Added in 1.1.0
fun setSpan(what: Any!, start: Int, end: Int, flags: Int): Unit
Throws
java.lang.IllegalArgumentException

if MetricAffectingSpan is specified.

subSequence

Added in 1.1.0
fun subSequence(start: Int, end: Int): CharSequence!

toString

fun toString(): String