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

*** ** * ** ***


```
class GridTemplate.Builder
```

<br />

*** ** * ** ***

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

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder#Builder()()` Returns an empty `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder` instance. |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder` | `@https://developer.android.com/reference/kotlin/androidx/car/app/annotations/RequiresCarApi(value = 7) https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder#addAction(androidx.car.app.model.Action)(action: https://developer.android.com/reference/kotlin/androidx/car/app/model/Action)` Adds a template scoped action outside of the grid items. |
| `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate` | `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder#build()()` Constructs the template defined by this builder. |
| `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder` | `[setActionStrip](https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.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/GridTemplate.Builder` | `@https://developer.android.com/reference/kotlin/androidx/car/app/annotations/RequiresCarApi(value = 7) https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.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/GridTemplate.Builder` | `[setHeaderAction](https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.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/GridTemplate.Builder` | `@https://developer.android.com/reference/kotlin/androidx/car/app/annotations/RequiresCarApi(value = 8) https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder#setItemImageShape(int)(itemImageShape: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Sets the item image shape for this template. |
| `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder` | `@https://developer.android.com/reference/kotlin/androidx/car/app/annotations/RequiresCarApi(value = 8) https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder#setItemSize(int)(gridItemSize: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Sets a relative size of all grid items in the template. |
| `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder` | `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.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/GridTemplate.Builder` | `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder#setSingleList(androidx.car.app.model.ItemList)(list: https://developer.android.com/reference/kotlin/androidx/car/app/model/ItemList)` Sets a single `https://developer.android.com/reference/kotlin/androidx/car/app/model/ItemList` to show in the template. |
| `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder` | `[setTitle](https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.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()
```

Returns an empty `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder` instance.

## Public functions

### addAction

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

```
@RequiresCarApi(value = 7)
fun addAction(action: Action): GridTemplate.Builder
```

Adds a template scoped action outside of the grid items. This action will be displayed as a floating action button.

Note: Starting in Car API 9, for media apps (apps with `https://developer.android.com/reference/kotlin/androidx/car/app/CarAppPermission#MEDIA_TEMPLATES()`), a maximum of 1 action can be set, as the host reserves space to render a persistent media entry point or miniplayer. If extra actions are sent by a media app, the host will drop the extra action.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `action` contains unsupported Action types, or does not contain a valid `https://developer.android.com/reference/kotlin/androidx/car/app/model/CarIcon` and background `https://developer.android.com/reference/kotlin/androidx/car/app/model/CarColor`, or if exceeds the maximum number of allowed actions for the template. |

| See also |
|---|---|
| `androidx.car.app.model.constraints.ActionsConstraints.ACTIONS_CONSTRAINTS_FAB` |   |

### build

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

```
fun build(): GridTemplate
```

Constructs the template defined by this builder.

#### Requirements

The number of items in the `https://developer.android.com/reference/kotlin/androidx/car/app/model/ItemList` should be smaller or equal than the limit provided by `https://developer.android.com/reference/kotlin/androidx/car/app/constraints/ConstraintManager#CONTENT_LIMIT_TYPE_GRID()`. The host will ignore any items over that limit.

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 template is in a loading state but there are lists added, or vice versa. |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if the added `https://developer.android.com/reference/kotlin/androidx/car/app/model/ItemList` does not meet the template's requirements. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/car/app/constraints/ConstraintManager#getContentLimit(int)` |   |

### setActionStrip

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

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` |

### 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): GridTemplate.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/GridTemplate.Builder#setHeaderAction(androidx.car.app.model.Action))(headerAction: Action): GridTemplate.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` |

### setItemImageShape

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

```
@RequiresCarApi(value = 8)
fun setItemImageShape(itemImageShape: Int): GridTemplate.Builder
```

Sets the item image shape for this template.

Grid item images will all be cropped to the specified shape. If set to ITEM_IMAGE_SHAPE_UNSET, the images will be rendered as-is without changing the shape.

If not set, default to ITEM_IMAGE_SHAPE_UNSET.

### setItemSize

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

```
@RequiresCarApi(value = 8)
fun setItemSize(gridItemSize: Int): GridTemplate.Builder
```

Sets a relative size of all grid items in the template.

This setting will affect the grid item image size and minimum width of each item. It can also impact the number of items displayed per row depending on screen size. These values may change in the future.

This setting takes precedence over the `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridItem#IMAGE_TYPE_LARGE()` setting for determining the grid item image size.

If this is not called, the default value is `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate#ITEM_SIZE_SMALL()`

### setLoading

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

```
fun setLoading(isLoading: Boolean): GridTemplate.Builder
```

Sets whether the template is in a loading state.

If set to `true`, the UI shows a loading indicator where the grid content 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. If set to `false`, the UI shows the `https://developer.android.com/reference/kotlin/androidx/car/app/model/ItemList` contents added via `https://developer.android.com/reference/kotlin/androidx/car/app/model/GridTemplate.Builder#setSingleList(androidx.car.app.model.ItemList)`.

### setSingleList

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

```
fun setSingleList(list: ItemList): GridTemplate.Builder
```

Sets a single `https://developer.android.com/reference/kotlin/androidx/car/app/model/ItemList` to show in the template.

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

### 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/GridTemplate.Builder#setTitle(java.lang.CharSequence))(title: CharSequence): GridTemplate.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 |