# CarText

Artifact: [androidx.car.app:app](https://developer.android.com/jetpack/androidx/releases/car-app) [View Source](https://cs.android.com/search?q=file:androidx/car/app/model/CarText.java+class:androidx.car.app.model.CarText) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

*** ** * ** ***


```
@CarProtocol
public final class CarText
```

<br />

*** ** * ** ***

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

## Text handling in the library

Models that consume text strings take a `https://developer.android.com/reference/java/lang/CharSequence.html` 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](https://developer.android.com/guide/topics/text/spans), you can use types such as `https://developer.android.com/reference/android/text/SpannableString.html` or `https://developer.android.com/reference/android/text/SpannedString.html` to create the strings with the spans

#### Text spans in strings

The Car App Library only supports a specific set of spans of type `https://developer.android.com/reference/androidx/car/app/model/CarSpan`. Further, individual APIs in the library that take text as input may only support a certain subset of `https://developer.android.com/reference/androidx/car/app/model/CarSpan`s. 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 `https://developer.android.com/reference/androidx/car/app/model/Row.Builder#addText(java.lang.CharSequence)` API documents that `https://developer.android.com/reference/androidx/car/app/model/ForegroundCarColorSpan` instances can be used to color the text of the row. This means any other types of spans except `https://developer.android.com/reference/androidx/car/app/model/ForegroundCarColorSpan` will be ignored.

`https://developer.android.com/reference/androidx/car/app/model/CarText` instances represent the text that was passed by the app through a `https://developer.android.com/reference/java/lang/CharSequence.html`, with the non-`https://developer.android.com/reference/androidx/car/app/model/CarSpan` spans removed.

The `https://developer.android.com/reference/androidx/car/app/model/CarText#toString()` method can be used to get a string representation of the string, whereas the `https://developer.android.com/reference/androidx/car/app/model/CarText#toCharSequence()` method returns the reconstructed `https://developer.android.com/reference/java/lang/CharSequence.html`, with the non`https://developer.android.com/reference/androidx/car/app/model/CarSpan` 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 `https://developer.android.com/reference/androidx/car/app/model/CarText.Builder#addVariant(java.lang.CharSequence)` 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 |
|---|
| `@https://developer.android.com/reference/androidx/car/app/annotations/CarProtocol public final class https://developer.android.com/reference/androidx/car/app/model/CarText.Builder` A builder of `https://developer.android.com/reference/androidx/car/app/model/CarText`. |

| ### Public methods |
|---|---|
| `static @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarText` | `https://developer.android.com/reference/androidx/car/app/model/CarText#create(java.lang.CharSequence)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/CharSequence.html text)` Returns a `https://developer.android.com/reference/androidx/car/app/model/CarText` instance for the given `https://developer.android.com/reference/java/lang/CharSequence.html`. |
| `boolean` | `https://developer.android.com/reference/androidx/car/app/model/CarText#equals(java.lang.Object)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/Object.html other)` |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/java/lang/CharSequence.html>` | `https://developer.android.com/reference/androidx/car/app/model/CarText#getVariants()()` Returns the list of variants for this text. |
| `int` | `https://developer.android.com/reference/androidx/car/app/model/CarText#hashCode()()` |
| `boolean` | `https://developer.android.com/reference/androidx/car/app/model/CarText#isEmpty()()` Returns whether the text string is empty. |
| `static boolean` | `https://developer.android.com/reference/androidx/car/app/model/CarText#isNullOrEmpty(androidx.car.app.model.CarText)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/model/CarText carText)` Returns `true` if the `carText` is `null` or an empty string, ` false` otherwise. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/CharSequence.html` | `https://developer.android.com/reference/androidx/car/app/model/CarText#toCharSequence()()` Returns the `https://developer.android.com/reference/java/lang/CharSequence.html` corresponding to the first text variant. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/car/app/model/CarText#toString()()` Returns the string representation of the `https://developer.android.com/reference/androidx/car/app/model/CarText`. |

## Public methods

### create

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public static @NonNull CarText create(@NonNull CharSequence text)
```

Returns a `https://developer.android.com/reference/androidx/car/app/model/CarText` instance for the given `https://developer.android.com/reference/java/lang/CharSequence.html`.

Only `https://developer.android.com/reference/androidx/car/app/model/CarSpan` type spans are allowed in a `https://developer.android.com/reference/androidx/car/app/model/CarText`, other spans will be removed from the provided `https://developer.android.com/reference/java/lang/CharSequence.html`.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if the text is `null` |

### equals

```
public boolean equals(@Nullable Object other)
```

### getVariants

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public @NonNull List<CharSequence> getVariants()
```

Returns the list of variants for this text.

Only the variants set with `https://developer.android.com/reference/androidx/car/app/model/CarText.Builder#addVariant(java.lang.CharSequence)` will be returned. To get the first variant, use `https://developer.android.com/reference/androidx/car/app/model/CarText#toCharSequence()`.

Spans that are not of type `https://developer.android.com/reference/androidx/car/app/model/CarSpan` that were passed when creating the `https://developer.android.com/reference/androidx/car/app/model/CarText` instance will not be present in the returned `https://developer.android.com/reference/java/lang/CharSequence.html`.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/model/CarText.Builder#addVariant(java.lang.CharSequence)` |   |

### hashCode

```
public int hashCode()
```

### isEmpty

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public boolean isEmpty()
```

Returns whether the text string is empty.

Only the first variant is checked.

### isNullOrEmpty

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public static boolean isNullOrEmpty(@Nullable CarText carText)
```

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

### toCharSequence

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public @NonNull CharSequence toCharSequence()
```

Returns the `https://developer.android.com/reference/java/lang/CharSequence.html` corresponding to the first text variant.

Spans that are not of type `https://developer.android.com/reference/androidx/car/app/model/CarSpan` that were passed when creating the `https://developer.android.com/reference/androidx/car/app/model/CarText` instance will not be present in the returned `https://developer.android.com/reference/java/lang/CharSequence.html`.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/model/CarText#create(java.lang.CharSequence)` |   |

### toString

```
public @NonNull String toString()
```

Returns the string representation of the `https://developer.android.com/reference/androidx/car/app/model/CarText`.

Only the first variant is returned.