# MessageTemplate.Builder

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/MessageTemplate.java+class:androidx.car.app.model.MessageTemplate.Builder) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

*** ** * ** ***

<br />

```
public final class MessageTemplate.Builder
```

<br />

*** ** * ** ***

A builder of `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#Builder(androidx.car.app.model.CarText)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarText message)` Returns a `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` instance. |
| `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#Builder(java.lang.CharSequence)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/CharSequence.html message)` Returns a `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` instance. |

| ### Public methods |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#addAction(androidx.car.app.model.Action)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Action action)` Adds an `https://developer.android.com/reference/androidx/car/app/model/Action` to display along with the message. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate` | `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#build()()` Constructs the `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate` defined by this builder. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 2) [setActionStrip](https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setActionStrip(androidx.car.app.model.ActionStrip))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ActionStrip actionStrip)` **This method is deprecated.** Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#addEndHeaderAction(androidx.car.app.model.Action)` <br /> |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setDebugMessage(java.lang.Throwable)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/Throwable.html cause)` Sets a `https://developer.android.com/reference/java/lang/Throwable.html` for debugging purposes. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setDebugMessage(java.lang.String)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html debugMessage)` Sets a debug message for debugging purposes. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 7) https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setHeader(androidx.car.app.model.Header)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Header header)` Sets the `https://developer.android.com/reference/androidx/car/app/model/Header` for this template. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` | `[setHeaderAction](https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setHeaderAction(androidx.car.app.model.Action))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Action headerAction)` **This method is deprecated.** Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#setStartHeaderAction(androidx.car.app.model.Action)` <br /> |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setIcon(androidx.car.app.model.CarIcon)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarIcon icon)` Sets the icon to be displayed along with the message. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 2) https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setLoading(boolean)(boolean isLoading)` Sets whether the template is in a loading state. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` | `[setTitle](https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setTitle(java.lang.CharSequence))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/CharSequence.html title)` **This method is deprecated.** Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#setTitle(androidx.car.app.model.CarText)` <br /> |

## Public constructors

### Builder

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

```
public Builder(@NonNull CarText message)
```

Returns a `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` instance.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarText message` | the text message to display in the template |

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

### Builder

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

```
public Builder(@NonNull CharSequence message)
```

Returns a `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder` instance.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/CharSequence.html message` | the text message to display in the template |

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

## Public methods

### addAction

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

```
public @NonNull MessageTemplate.Builder addAction(@NonNull Action action)
```

Adds an `https://developer.android.com/reference/androidx/car/app/model/Action` to display along with the message.

#### Requirements

This template allows up to 2 `https://developer.android.com/reference/androidx/car/app/model/Action`s in its body. Each action's title color can be customized with `https://developer.android.com/reference/androidx/car/app/model/ForegroundCarColorSpan` instances. Any other span is not supported.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `action` is `null` |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `action` does not meet the requirements |

### build

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

```
public @NonNull MessageTemplate build()
```

Constructs the `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate` defined by this builder.

#### Requirements

A non-empty message must be set on the template.

If none of the header `https://developer.android.com/reference/androidx/car/app/model/Action`, the header title or the action strip have been set on the template, the header is hidden.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if the message is empty, or if the template is in loading state and an icon is specified. |

### setActionStrip

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

```
@RequiresCarApi(value = 2)
public @NonNull MessageTemplate.Builder [setActionStrip](https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setActionStrip(androidx.car.app.model.ActionStrip))(@NonNull ActionStrip actionStrip)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#addEndHeaderAction(androidx.car.app.model.Action)`

Sets the `https://developer.android.com/reference/androidx/car/app/model/ActionStrip` for this template or `null` to not display an `https://developer.android.com/reference/androidx/car/app/model/ActionStrip`.

Unless set with this method, the template will not have an action strip.

#### Requirements

This template allows up to 2 `https://developer.android.com/reference/androidx/car/app/model/Action`s in its `https://developer.android.com/reference/androidx/car/app/model/ActionStrip`. Of the 2 allowed `https://developer.android.com/reference/androidx/car/app/model/Action`s, one of them can contain a title as set via `https://developer.android.com/reference/androidx/car/app/model/Action.Builder#setTitle(java.lang.CharSequence)`. Otherwise, only `https://developer.android.com/reference/androidx/car/app/model/Action`s with icons are allowed.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `actionStrip` does not meet the requirements |
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `actionStrip` is `null` |

### setDebugMessage

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

```
public @NonNull MessageTemplate.Builder setDebugMessage(@NonNull Throwable cause)
```

Sets a `https://developer.android.com/reference/java/lang/Throwable.html` for debugging purposes.

The cause will be displayed along with the message set in `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setDebugMessage(java.lang.String)`.

The host may choose to not display this debugging information if it doesn't deem it appropriate, for example, when running on a production environment rather than in a simulator such as the Desktop Head Unit.

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

### setDebugMessage

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

```
public @NonNull MessageTemplate.Builder setDebugMessage(@NonNull String debugMessage)
```

Sets a debug message for debugging purposes.

The debug message will be displayed along with the cause set in `https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setDebugMessage(java.lang.Throwable)`.

The host may choose to not display this debugging information if it doesn't deem it appropriate, for example, when running on a production environment rather than in a simulator such as the Desktop Head Unit.

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

### setHeader

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

```
@RequiresCarApi(value = 7)
public @NonNull MessageTemplate.Builder setHeader(@NonNull Header header)
```

Sets the `https://developer.android.com/reference/androidx/car/app/model/Header` for this template.

The end header actions will show up differently inside vs outside of a map template. See `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#addEndHeaderAction(androidx.car.app.model.Action)` for more details.

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

### setHeaderAction

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

```
public @NonNull MessageTemplate.Builder [setHeaderAction](https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setHeaderAction(androidx.car.app.model.Action))(@NonNull Action headerAction)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#setStartHeaderAction(androidx.car.app.model.Action)`

Sets the `https://developer.android.com/reference/androidx/car/app/model/Action` that will be displayed in the header of the template.

Unless set with this method, the template will not have a header action.

#### Requirements

This template only supports either one of `https://developer.android.com/reference/androidx/car/app/model/Action#APP_ICON()` and `https://developer.android.com/reference/androidx/car/app/model/Action#BACK()` as a header `https://developer.android.com/reference/androidx/car/app/model/Action`.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `headerAction` does not meet the template's requirements |
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `headerAction` is `null` |

### setIcon

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

```
public @NonNull MessageTemplate.Builder setIcon(@NonNull CarIcon icon)
```

Sets the icon to be displayed along with the message.

Unless set with this method, an icon will not be displayed.

#### Icon Sizing Guidance

To minimize scaling artifacts across a wide range of car screens, apps should provide icons targeting a 128 x 128 dp bounding box. If the icon exceeds this maximum size in either one of the dimensions, it will be scaled down to be centered inside the bounding box while preserving its aspect ratio.

See `https://developer.android.com/reference/androidx/car/app/model/CarIcon` for more details related to providing icon and image resources that work with different car screen pixel densities.

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

### setLoading

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

```
@RequiresCarApi(value = 2)
public @NonNull MessageTemplate.Builder setLoading(boolean isLoading)
```

Sets whether the template is in a loading state.

If set to `true`, the UI shows a loading indicator where the icon would be otherwise. The caller is expected to call `https://developer.android.com/reference/androidx/car/app/Screen#invalidate()` and send the new template content to the host once the data is ready.

### setTitle

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

```
public @NonNull MessageTemplate.Builder [setTitle](https://developer.android.com/reference/androidx/car/app/model/MessageTemplate.Builder#setTitle(java.lang.CharSequence))(@NonNull CharSequence title)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#setTitle(androidx.car.app.model.CarText)`

Sets the title of the template.

Unless set with this method, the template will not have a title.

Only `https://developer.android.com/reference/androidx/car/app/model/DistanceSpan`s and `https://developer.android.com/reference/androidx/car/app/model/DurationSpan`s are supported in the input string.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `title` is `null` |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `title` contains unsupported spans |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/model/CarText` |   |