CarText
@CarProtocol
public final class CarText
A model that represents text to display in the car screen.
Text handling in the library
Models that consume text strings take aCharSequence 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.
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.
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 |
|---|
@CarProtocolA builder of |
Public methods |
|
|---|---|
static @NonNull CarText |
create(@NonNull CharSequence text)Returns a |
boolean |
|
@NonNull List<CharSequence> |
Returns the list of variants for this text. |
int |
hashCode() |
boolean |
isEmpty()Returns whether the text string is empty. |
static boolean |
isNullOrEmpty(@Nullable CarText carText)Returns |
@NonNull CharSequence |
Returns the |
@NonNull String |
toString()Returns the string representation of the |
Public methods
create
public static @NonNull CarText create(@NonNull 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.
| Throws | |
|---|---|
java.lang.NullPointerException |
if the text is |
getVariants
public @NonNull List<CharSequence> getVariants()
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 |
isEmpty
public boolean isEmpty()
Returns whether the text string is empty.
Only the first variant is checked.
isNullOrEmpty
public static boolean isNullOrEmpty(@Nullable CarText carText)
Returns true if the carText is null or an empty string,
false otherwise.
toCharSequence
public @NonNull 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.
| See also | |
|---|---|
create |