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

*** ** * ** ***


```
public final class ItemList.Builder
```

<br />

*** ** * ** ***

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

## Summary

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

| ### Public methods |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#addItem(androidx.car.app.model.Item)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Item item)` Adds an item to the list. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList` | `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#build()()` Constructs the item list defined by this builder. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#clearItems()()` Removes all `https://developer.android.com/reference/androidx/car/app/model/Item`s added via `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#addItem(androidx.car.app.model.Item)` |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#setNoItemsMessage(java.lang.CharSequence)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/CharSequence.html noItemsMessage)` Sets the text to display if the list is empty. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#setOnItemsVisibilityChangedListener(androidx.car.app.model.ItemList.OnItemVisibilityChangedListener)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList.OnItemVisibilityChangedListener itemVisibilityChangedListener )` Sets the `https://developer.android.com/reference/androidx/car/app/model/ItemList.OnItemVisibilityChangedListener` to call when the visible items in the list changes. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#setOnSelectedListener(androidx.car.app.model.ItemList.OnSelectedListener)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList.OnSelectedListener onSelectedListener )` Marks the list as selectable by setting the `https://developer.android.com/reference/androidx/car/app/model/ItemList.OnSelectedListener` to call when an item is selected by the user, or set to `null` to mark the list as non-selectable. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#setSelectedIndex(int)(@https://developer.android.com/reference/androidx/annotation/IntRange(from = 0) int selectedIndex)` Sets the index of the item to show as selected. |

## 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/ItemList.Builder` instance.

## Public methods

### addItem

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

```
public @NonNull ItemList.Builder addItem(@NonNull Item item)
```

Adds an item to the list.

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

### build

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

```
public @NonNull ItemList build()
```

Constructs the item list defined by this builder.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if the list is selectable but does not have any items, if the selected index is greater or equal to the size of the list, or if the list is selectable and any items have either one of their `https://developer.android.com/reference/androidx/car/app/model/OnClickListener` or `https://developer.android.com/reference/androidx/car/app/model/Toggle` set |

### clearItems

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

```
public @NonNull ItemList.Builder clearItems()
```

Removes all `https://developer.android.com/reference/androidx/car/app/model/Item`s added via `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#addItem(androidx.car.app.model.Item)`

### setNoItemsMessage

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

```
public @NonNull ItemList.Builder setNoItemsMessage(@NonNull CharSequence noItemsMessage)
```

Sets the text to display if the list is empty.

If the list is empty and the app does not explicitly set the message with this method, the host will show a default message.

Spans are not supported in the input string and will be ignored.

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

### setOnItemsVisibilityChangedListener

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

```
public @NonNull ItemList.Builder setOnItemsVisibilityChangedListener(
    @NonNull ItemList.OnItemVisibilityChangedListener itemVisibilityChangedListener
)
```

Sets the `https://developer.android.com/reference/androidx/car/app/model/ItemList.OnItemVisibilityChangedListener` to call when the visible items in the list changes.

Note that the listener relates to UI events and will be executed on the main thread using `https://developer.android.com/reference/android/os/Looper.html#getMainLooper()`.

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

### setOnSelectedListener

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

```
public @NonNull ItemList.Builder setOnSelectedListener(
    @NonNull ItemList.OnSelectedListener onSelectedListener
)
```

Marks the list as selectable by setting the `https://developer.android.com/reference/androidx/car/app/model/ItemList.OnSelectedListener` to call when an item is selected by the user, or set to `null` to mark the list as non-selectable.

Selectable lists, where allowed by the template they are added to, automatically display an item in a selected state when selected by the user.

The items in the list define a mutually exclusive selection scope: only a single item will be selected at any given time.

The specific way in which the selection will be visualized depends on the template and the host implementation. For example, some templates may display the list as a radio button group, while others may highlight the selected item's background.

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

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#setSelectedIndex(int)` |   |

### setSelectedIndex

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

```
public @NonNull ItemList.Builder setSelectedIndex(@IntRange(from = 0) int selectedIndex)
```

Sets the index of the item to show as selected.

By default and unless explicitly set with this method, the first item is selected.

If the list is not a selectable list set with `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#setOnSelectedListener(androidx.car.app.model.ItemList.OnSelectedListener)`, this value is ignored.