CarText

@CarProtocol
class 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 android.text.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 addText 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 addVariant for more information.

Text Localization

The host will render the text the app sends without interpretation. The app must localize the text before sending it to the host.

Summary

Nested types

A builder of CarText.

Public functions

java-static CarText

Returns a CarText instance for the given CharSequence.

Boolean
equals(other: Any?)
(Mutable)List<CharSequence!>

Returns the list of variants for this text.

Int
Boolean

Returns whether the text string is empty.

java-static Boolean

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

CharSequence

Returns the CharSequence corresponding to the first text variant.

String

Returns the string representation of the CarText.

Public functions

create

Added in 1.0.0
java-static fun create(text: CharSequence): CarText

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.

Throws
java.lang.NullPointerException

if the text is null

equals

Added in 1.4.0-rc02
fun equals(other: Any?): Boolean

getVariants

Added in 1.0.0
fun getVariants(): (Mutable)List<CharSequence!>

Returns the list of variants for this text.

Only the variants set with addVariant 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.

See also
addVariant

hashCode

Added in 1.4.0-rc02
fun hashCode(): Int

isEmpty

Added in 1.0.0
fun isEmpty(): Boolean

Returns whether the text string is empty.

Only the first variant is checked.

isNullOrEmpty

Added in 1.0.0
java-static fun isNullOrEmpty(carText: CarText?): Boolean

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

toCharSequence

Added in 1.0.0
fun toCharSequence(): CharSequence

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.

See also
create

toString

Added in 1.4.0-rc02
fun toString(): String

Returns the string representation of the CarText.

Only the first variant is returned.