GridItem.Builder

public final class GridItem.Builder


A builder of GridItem.

Summary

Public constructors

Returns an empty Builder instance.

Public methods

@NonNull GridItem

Constructs the GridItem defined by this builder.

@NonNull GridItem.Builder

Sets an image to show in the grid item with the default size IMAGE_TYPE_LARGE.

@NonNull GridItem.Builder

Sets an image to show in the grid item with the given Badge to be displayed over the image, with the default size IMAGE_TYPE_LARGE.

@NonNull GridItem.Builder
setImage(@NonNull CarIcon image, int imageType)

Sets an image to show in the grid item with the given imageType.

@NonNull GridItem.Builder
@ExperimentalCarApi
@RequiresCarApi(value = 7)
setImage(@NonNull CarIcon image, int imageType, @NonNull Badge badge)

Sets an image to show in the grid item with the given imageType and given Badge to be displayed over the image.

@NonNull GridItem.Builder
setLoading(boolean isLoading)

Sets whether the item is in a loading state.

@NonNull GridItem.Builder

Sets the OnClickListener to be called back when the grid item is clicked, or null to make the grid item non-clickable.

@NonNull GridItem.Builder

Sets a secondary text string to the grid item that is displayed below the title, with support for multiple length variants.

@NonNull GridItem.Builder

Sets a secondary text string to the grid item that is displayed below the title.

@NonNull GridItem.Builder

Sets the title of the GridItem, with support for multiple length variants.,

@NonNull GridItem.Builder

Sets the title of the GridItem.

Public constructors

Builder

Added in 1.0.0
public Builder()

Returns an empty Builder instance.

Public methods

build

Added in 1.0.0
public @NonNull GridItem build()

Constructs the GridItem defined by this builder.

Throws
java.lang.IllegalStateException

if the grid item's title is not set, if the grid item's image is set when it is loading or vice versa, if the grid item is loading but the click listener is set, or if a badge is set and an image is not set

setImage

Added in 1.0.0
public @NonNull GridItem.Builder setImage(@NonNull CarIcon image)

Sets an image to show in the grid item with the default size IMAGE_TYPE_LARGE.

Throws
java.lang.NullPointerException

if image is null

See also
setImage

setImage

Added in 1.4.0-rc02
@ExperimentalCarApi
@RequiresCarApi(value = 7)
public @NonNull GridItem.Builder setImage(@NonNull CarIcon image, @NonNull Badge badge)

Sets an image to show in the grid item with the given Badge to be displayed over the image, with the default size IMAGE_TYPE_LARGE.

A dot badge denotes some sort of call to action or notification and is displayed in the upper right corner of the image. An icon badge gives additional context about the image and is displayed in the lower right corner.

Throws
java.lang.NullPointerException

if image or badge is null

See also
setImage

setImage

Added in 1.0.0
public @NonNull GridItem.Builder setImage(@NonNull CarIcon image, int imageType)

Sets an image to show in the grid item with the given imageType.

For a custom CarIcon, its androidx.core.graphics.drawable.IconCompat instance can be of TYPE_BITMAP, TYPE_RESOURCE, or TYPE_URI.

Image Sizing Guidance

If the input image's size exceeds the sizing requirements for the given image type in either one of the dimensions, it will be scaled down to be centered inside the bounding box while preserving its aspect ratio.

See CarIcon for more details related to providing icon and image resources that work with different car screen pixel densities.

Parameters
@NonNull CarIcon image

the CarIcon to display

int imageType

one of IMAGE_TYPE_ICON or IMAGE_TYPE_LARGE

Throws
java.lang.NullPointerException

if image is null

setImage

Added in 1.4.0-rc02
@ExperimentalCarApi
@RequiresCarApi(value = 7)
public @NonNull GridItem.Builder setImage(@NonNull CarIcon image, int imageType, @NonNull Badge badge)

Sets an image to show in the grid item with the given imageType and given Badge to be displayed over the image.

A dot badge denotes a call to action or notification and is displayed in the upper right corner of the image. An icon badge gives additional context about the image and is displayed in the lower right corner.

Throws
java.lang.NullPointerException

if image or badge is null

See also
setImage

setLoading

Added in 1.0.0
public @NonNull GridItem.Builder setLoading(boolean isLoading)

Sets whether the item is in a loading state.

If set to true, the UI shows a loading indicator where the grid item would be otherwise. The caller is expected to call invalidate and send the new template content to the host once the data is ready. If set to false, the UI shows the item contents.

setOnClickListener

Added in 1.0.0
public @NonNull GridItem.Builder setOnClickListener(@NonNull OnClickListener onClickListener)

Sets the OnClickListener to be called back when the grid item is clicked, or null to make the grid item non-clickable.

Note that the listener relates to UI events and will be executed on the main thread using getMainLooper

Throws
java.lang.NullPointerException

if onClickListener is null

setText

Added in 1.0.0
public @NonNull GridItem.Builder setText(@NonNull CarText text)

Sets a secondary text string to the grid item that is displayed below the title, with support for multiple length variants.

The text can be customized with ForegroundCarColorSpan, androidx.car.app.model.DistanceSpan, and androidx.car.app.model.DurationSpan instances, any other spans will be ignored by the host.

Text Wrapping

This text is truncated at the end to fit in a single line below the title
Throws
java.lang.NullPointerException

if text is null

java.lang.IllegalArgumentException

if text contains unsupported spans

setText

Added in 1.0.0
public @NonNull GridItem.Builder setText(@NonNull CharSequence text)

Sets a secondary text string to the grid item that is displayed below the title.

The text can be customized with ForegroundCarColorSpan, androidx.car.app.model.DistanceSpan, and androidx.car.app.model.DurationSpan instances, any other spans will be ignored by the host.

Text Wrapping

This text is truncated at the end to fit in a single line below the title
Throws
java.lang.NullPointerException

if text is null

java.lang.IllegalArgumentException

if text contains unsupported spans

setTitle

Added in 1.0.0
public @NonNull GridItem.Builder setTitle(@NonNull CarText title)

Sets the title of the GridItem, with support for multiple length variants.,

Only DistanceSpans and DurationSpans are supported in the input string.

Throws
java.lang.NullPointerException

if title is null

java.lang.IllegalArgumentException

if title is empty, of if it contains unsupported spans

setTitle

Added in 1.0.0
public @NonNull GridItem.Builder setTitle(@NonNull CharSequence title)

Sets the title of the GridItem.

Only DistanceSpans and DurationSpans are supported in the input string.

Throws
java.lang.NullPointerException

if title is null

java.lang.IllegalArgumentException

if title is empty, of if it contains unsupported spans