CarText

public final class CarText
extends Object

java.lang.Object
   ↳ androidx.car.app.model.CarText

A model that represents text to display in the car screen.

Text handling in the library

Models that consume text strings take a CharSequence type as the parameter type. These strings can contain spans that are applied to the text and allow, for example, changing the color of the text, introducing inline images, or displaying a time duration. As described in the span documentation, you can use types such as SpannableString or SpannedString to create the strings with the spans

Text spans in strings

The Car App Library only supports a specific set of spans of type CarSpan. Further, individual APIs in the library that take text as input may only support a certain subset of CarSpans. Spans that are not supported will be simply ignored by the host.

By default and unless explicitly documented in the individual APIs that take a text parameter as input, spans for that API are not supported and will be ignored.

For example, the Row.Builder.addText(CharSequence) API documents that ForegroundCarColorSpan instances can be used to color the text of the row. This means any other types of spans except ForegroundCarColorSpan will be ignored.

CarText instances represent the text that was passed by the app through a CharSequence, with the non-CarSpan spans removed.

The toString() method can be used to get a string representation of the string, whereas the toCharSequence() method returns the reconstructed CharSequence, with the nonCarSpan spans removed.

Text variants of multiple lengths

The app is generally agnostic to the width of the views generated by the host that contain the text strings it supplies. For that reason, some models that take text allow the app to pass a list of text variants of different lengths. In those cases the host will pick the variant that best fits the screen. See CarText.Builder.addVariant(CharSequence) for more information.

Summary

Nested classes

class CarText.Builder

A builder of CarText. 

Public methods

static CarText create(CharSequence text)

Returns a CarText instance for the given CharSequence.

boolean equals(Object other)
List<CharSequence> getVariants()

Returns the list of variants for this text.

int hashCode()
boolean isEmpty()

Returns whether the text string is empty.

static boolean isNullOrEmpty(CarText carText)

Returns true if the carText is null or an empty string, false otherwise.

CharSequence toCharSequence()

Returns the CharSequence corresponding to the first text variant.

String toString()

Returns the string representation of the CarText.

Inherited methods

Public methods

create

public static CarText create (CharSequence text)

Returns a CarText instance for the given CharSequence.

Only CarSpan type spans are allowed in a CarText, other spans will be removed from the provided CharSequence.

Parameters
text CharSequence

Returns
CarText

Throws
NullPointerException if the text is null

equals

public boolean equals (Object other)

Parameters
other Object

Returns
boolean

getVariants

public List<CharSequence> getVariants ()

Returns the list of variants for this text.

Only the variants set with CarText.Builder.addVariant(CharSequence) will be returned. To get the first variant, use toCharSequence().

Spans that are not of type CarSpan that were passed when creating the CarText instance will not be present in the returned CharSequence.

Returns
List<CharSequence>

hashCode

public int hashCode ()

Returns
int

isEmpty

public boolean isEmpty ()

Returns whether the text string is empty.

Only the first variant is checked.

Returns
boolean

isNullOrEmpty

public static boolean isNullOrEmpty (CarText carText)

Returns true if the carText is null or an empty string, false otherwise.

Parameters
carText CarText

Returns
boolean

toCharSequence

public CharSequence toCharSequence ()

Returns the CharSequence corresponding to the first text variant.

Spans that are not of type CarSpan that were passed when creating the CarText instance will not be present in the returned CharSequence.

Returns
CharSequence

toString

public String toString ()

Returns the string representation of the CarText.

Only the first variant is returned.

Returns
String