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

*** ** * ** ***


```
public final class GridTemplate.Builder
```

<br />

*** ** * ** ***

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

## Summary

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

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

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

## Public methods

### addAction

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

```
@RequiresCarApi(value = 7)
public @NonNull GridTemplate.Builder addAction(@NonNull Action action)
```

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/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/androidx/car/app/model/CarIcon` and background `https://developer.android.com/reference/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)

```
public @NonNull GridTemplate build()
```

Constructs the template defined by this builder.

#### Requirements

The number of items in the `https://developer.android.com/reference/androidx/car/app/model/ItemList` should be smaller or equal than the limit provided by `https://developer.android.com/reference/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/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/androidx/car/app/model/ItemList` does not meet the template's requirements. |

| See also |
|---|---|
| `https://developer.android.com/reference/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)

```
public @NonNull GridTemplate.Builder [setActionStrip](https://developer.android.com/reference/androidx/car/app/model/GridTemplate.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.

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

### setHeader

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

```
@RequiresCarApi(value = 7)
public @NonNull GridTemplate.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 GridTemplate.Builder [setHeaderAction](https://developer.android.com/reference/androidx/car/app/model/GridTemplate.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` |

### setItemImageShape

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

```
@RequiresCarApi(value = 8)
public @NonNull GridTemplate.Builder setItemImageShape(int itemImageShape)
```

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)
public @NonNull GridTemplate.Builder setItemSize(int gridItemSize)
```

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

```
public @NonNull GridTemplate.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 grid content 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. If set to `false`, the UI shows the `https://developer.android.com/reference/androidx/car/app/model/ItemList` contents added via `https://developer.android.com/reference/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)

```
public @NonNull GridTemplate.Builder setSingleList(@NonNull ItemList list)
```

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

```
public @NonNull GridTemplate.Builder [setTitle](https://developer.android.com/reference/androidx/car/app/model/GridTemplate.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 |