PrecomputedTextCompat

Added in 1.1.0

public class PrecomputedTextCompat implements 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
public final class PrecomputedTextCompat.Params

The information required for building PrecomputedTextCompat.

A builder for creating Params.

Public methods
char
charAt(int index)
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(@IntRange(from = 0) int paraIndex)

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

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

Returns the parameters used to measure this text.
int
int
int
T[]
<T> getSpans(int start, int end, Class<T> type)
static Future<PrecomputedTextCompat>
@UiThread
getTextFuture(
    @NonNull CharSequence charSequence,
    @NonNull PrecomputedTextCompat.Params params,
    @Nullable Executor executor
)

Helper for PrecomputedText that returns a future to be used with setTextFuture.
int
int
nextSpanTransition(int start, int limit, Class type)
void
void
setSpan(Object what, int start, int end, int flags)
CharSequence
subSequence(int start, int end)
@NonNull String

Inherited Constants
From android.text.Spanned
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
SPAN_PRIORITY = 16711680
static final int
static final int
SPAN_USER = -16777216
static final int

Inherited methods
From java.lang.CharSequence
IntStream
IntStream
static int
boolean

Public methods

charAt

Added in 1.1.0
public char charAt(int index)

create

Added in 1.1.0
public static PrecomputedTextCompat create(
    @NonNull CharSequence text,
    @NonNull PrecomputedTextCompat.Params params
)

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
@NonNull CharSequence text

the text to be measured
@NonNull PrecomputedTextCompat.Params params

parameters that define how text will be precomputed
Returns
PrecomputedTextCompat

A PrecomputedText

getParagraphCount

Added in 1.1.0
public @IntRange(from = 0) int getParagraphCount()

Returns the count of paragraphs.

getParagraphEnd

Added in 1.1.0
public @IntRange(from = 0) int getParagraphEnd(@IntRange(from = 0) int paraIndex)

Returns the paragraph end offset of the text.

getParagraphStart

Added in 1.1.0
public @IntRange(from = 0) int getParagraphStart(@IntRange(from = 0) int paraIndex)

Returns the paragraph start offset of the text.

getParams

Added in 1.1.0
public @NonNull PrecomputedTextCompat.Params getParams()

Returns the parameters used to measure this text.

getSpanEnd

Added in 1.1.0
public int getSpanEnd(Object tag)

getSpanFlags

Added in 1.1.0
public int getSpanFlags(Object tag)

getSpanStart

Added in 1.1.0
public int getSpanStart(Object tag)

getSpans

Added in 1.1.0
public T[] <T> getSpans(int start, int end, Class<T> type)

getTextFuture

Added in 1.1.0
@UiThread
public static Future<PrecomputedTextCompat> getTextFuture(
    @NonNull CharSequence charSequence,
    @NonNull PrecomputedTextCompat.Params params,
    @Nullable Executor executor
)

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
@NonNull CharSequence charSequence

the text to be displayed
@NonNull PrecomputedTextCompat.Params params

the parameters to be used for displaying text
@Nullable 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
public int length()

nextSpanTransition

Added in 1.1.0
public int nextSpanTransition(int start, int limit, Class type)

removeSpan

Added in 1.1.0
public void removeSpan(Object what)
Throws
java.lang.IllegalArgumentException

if MetricAffectingSpan is specified.

setSpan

Added in 1.1.0
public void setSpan(Object what, int start, int end, int flags)
Throws
java.lang.IllegalArgumentException

if MetricAffectingSpan is specified.

subSequence

Added in 1.1.0
public CharSequence subSequence(int start, int end)

toString

public @NonNull String toString()