# 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 />

```
class MessageTemplate.Builder
```

<br />

*** ** * ** ***

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

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/car/app/model/MessageTemplate.Builder#Builder(androidx.car.app.model.CarText)(message: https://developer.android.com/reference/kotlin/androidx/car/app/model/CarText)` Returns a `https://developer.android.com/reference/kotlin/androidx/car/app/model/MessageTemplate.Builder` instance. |
| `https://developer.android.com/reference/kotlin/androidx/car/app/model/MessageTemplate.Builder#Builder(java.lang.CharSequence)(message: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char-sequence/index.html)` Returns a `https://developer.android.com/reference/kotlin/androidx/car/app/model/MessageTemplate.Builder` instance. |

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

```
Builder(message: CarText)
```

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

| Parameters |
|---|---|
| `message: https://developer.android.com/reference/kotlin/androidx/car/app/model/CarText` | 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)

```
Builder(message: CharSequence)
```

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

| Parameters |
|---|---|
| `message: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char-sequence/index.html` | the text message to display in the template |

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

## Public functions

### addAction

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

```
fun addAction(action: Action): MessageTemplate.Builder
```

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

#### Requirements

This template allows up to 2 `https://developer.android.com/reference/kotlin/androidx/car/app/model/Action`s in its body. Each action's title color can be customized with `https://developer.android.com/reference/kotlin/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)

```
fun build(): MessageTemplate
```

Constructs the `https://developer.android.com/reference/kotlin/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/kotlin/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)
fun [setActionStrip](https://developer.android.com/reference/kotlin/androidx/car/app/model/MessageTemplate.Builder#setActionStrip(androidx.car.app.model.ActionStrip))(actionStrip: ActionStrip): MessageTemplate.Builder
```

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

Sets the `https://developer.android.com/reference/kotlin/androidx/car/app/model/ActionStrip` for this template or `null` to not display an `https://developer.android.com/reference/kotlin/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/kotlin/androidx/car/app/model/Action`s in its `https://developer.android.com/reference/kotlin/androidx/car/app/model/ActionStrip`. Of the 2 allowed `https://developer.android.com/reference/kotlin/androidx/car/app/model/Action`s, one of them can contain a title as set via `https://developer.android.com/reference/kotlin/androidx/car/app/model/Action.Builder#setTitle(java.lang.CharSequence)`. Otherwise, only `https://developer.android.com/reference/kotlin/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)

```
fun setDebugMessage(cause: Throwable): MessageTemplate.Builder
```

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/kotlin/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)

```
fun setDebugMessage(debugMessage: String): MessageTemplate.Builder
```

Sets a debug message for debugging purposes.

The debug message will be displayed along with the cause set in `https://developer.android.com/reference/kotlin/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)
fun setHeader(header: Header): MessageTemplate.Builder
```

Sets the `https://developer.android.com/reference/kotlin/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/kotlin/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)

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

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

Sets the `https://developer.android.com/reference/kotlin/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/kotlin/androidx/car/app/model/Action#APP_ICON()` and `https://developer.android.com/reference/kotlin/androidx/car/app/model/Action#BACK()` as a header `https://developer.android.com/reference/kotlin/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)

```
fun setIcon(icon: CarIcon): MessageTemplate.Builder
```

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/kotlin/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)
fun setLoading(isLoading: Boolean): MessageTemplate.Builder
```

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/kotlin/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)

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

> [!CAUTION]
> **This function is deprecated.**   
>
> Use `https://developer.android.com/reference/kotlin/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/kotlin/androidx/car/app/model/DistanceSpan`s and `https://developer.android.com/reference/kotlin/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/kotlin/androidx/car/app/model/CarText` |   |