Row.Builder

public final class Row.Builder

A builder of Row.

Summary

Public constructors

Returns an empty Builder instance.

Public methods
@NonNull Row.Builder
@RequiresCarApi(value = 6)
addAction(@NonNull Action action)

Adds an additional action to the end of the row.
@NonNull Row.Builder

Adds a text string to the row below the title, with support for multiple length variants.
@NonNull Row.Builder

Adds a text string to the row below the title.
@NonNull Row

Constructs the Row defined by this builder.
@NonNull Row.Builder
setBrowsable(boolean isBrowsable)

Shows an icon at the end of the row that indicates that the row is browsable.
@NonNull Row.Builder
@RequiresCarApi(value = 5)
setEnabled(boolean enabled)

Sets the initial enabled state for Row.
@NonNull Row.Builder

Sets an image to show in the row with the default size IMAGE_TYPE_SMALL.
@NonNull Row.Builder
setImage(@NonNull CarIcon image, int imageType)

Sets an image to show in the row with the given image type.
@NonNull Row.Builder
@ExperimentalCarApi
setIndexable(boolean indexable)

Sets whether this item can be included in indexed lists.
@NonNull Row.Builder

Sets the Metadata associated with the row.
@IntRange(from = 0) @NonNull Row.Builder
@RequiresCarApi(value = 6)
setNumericDecoration(int decoration)

Sets a numeric decoration to display in the row.
@NonNull Row.Builder

Sets the OnClickListener to be called back when the row is clicked.
@NonNull Row.Builder

Sets the title of the row, with support for multiple length variants.
@NonNull Row.Builder

Sets the title of the row.
@NonNull Row.Builder

Sets a Toggle to show in the row.

Public constructors

Builder

Added in 1.0.0
public Builder()

Returns an empty Builder instance.

Public methods

addAction

Added in 1.3.0
@RequiresCarApi(value = 6)
public @NonNull Row.Builder addAction(@NonNull Action action)

Adds an additional action to the end of the row. Note: From Car API 8 onwards, Rows are allowed to have 2 max actions to be set.

Throws
java.lang.NullPointerException

if action is null
java.lang.IllegalArgumentException

if action contains unsupported Action types, exceeds the maximum number of allowed actions or does not contain a valid CarIcon.

addText

Added in 1.0.0
public @NonNull Row.Builder addText(@NonNull CarText text)

Adds a text string to the row below the title, with support for multiple length variants.

Throws
java.lang.NullPointerException

if text is null
java.lang.IllegalArgumentException

if text contains unsupported spans
See also
addText

addText

Added in 1.0.0
public @NonNull Row.Builder addText(@NonNull CharSequence text)

Adds a text string to the row 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.

Most templates allow up to 2 text strings, but this may vary. This limit is documented in each individual template.

Text Wrapping Each string added with this method will not wrap more than 1 line in the UI, with one exception: if the template allows a maximum number of text strings larger than 1, and the app adds a single text string, then this string will wrap up to the maximum.

For example, assuming 2 lines are allowed in the template where the row will be used, this code: 

rowBuilder
    .addText("This is a rather long line of text")
    .addText("More text")

would wrap the text like this: 

This is a rather long li...
More text
In contrast, this code: 
rowBuilder
    .addText("This is a rather long line of text. More text")

would wrap the single line of text at a maximum of 2 lines, producing a different result: 

This is a rather long line
of text. More text

Note that when using a single line, a line break character can be used to break it into two, but the results may be unpredictable depending on the width the text is wrapped at: 

rowBuilder
    .addText("This is a rather long line of text\nMore text")

would produce a result that may loose the "More text" string: 

This is a rather long line
of text
Throws
java.lang.NullPointerException

if text is null
java.lang.IllegalArgumentException

if text contains unsupported spans
See also
ForegroundCarColorSpan

build

Added in 1.0.0
public @NonNull Row build()

Constructs the Row defined by this builder.

Throws
java.lang.IllegalStateException

if the row's title is not set or if the row is not set correctly. See setToggle and setBrowsable.

setBrowsable

Added in 1.0.0
public @NonNull Row.Builder setBrowsable(boolean isBrowsable)

Shows an icon at the end of the row that indicates that the row is browsable.

Browsable rows can be used, for example, to represent the parent row in a hierarchy of lists with child lists.

If a row is browsable, then no Action or Toggle can be added to it. A browsable row must have an OnClickListener set.

setEnabled

Added in 1.3.0
@RequiresCarApi(value = 5)
public @NonNull Row.Builder setEnabled(boolean enabled)

Sets the initial enabled state for Row.

The default state of a Row is enabled.

setImage

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

Sets an image to show in the row with the default size IMAGE_TYPE_SMALL.

Throws
java.lang.NullPointerException

if image is null
See also
setImage

setImage

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

Sets an image to show in the row with the given image type.

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 or null to not display one
int imageType

one of IMAGE_TYPE_ICON, IMAGE_TYPE_SMALL or IMAGE_TYPE_LARGE
Throws
java.lang.NullPointerException

if image is null

setIndexable

Added in 1.7.0-beta03
@ExperimentalCarApi
public @NonNull Row.Builder setIndexable(boolean indexable)

Sets whether this item can be included in indexed lists. By default, this is set to true.

The host creates indexed lists to help users navigate through long lists more easily by sorting, filtering, or some other means.

For example, a media app may, by default, show a user's playlists sorted by date created. If the app provides these playlists via the SectionedItemTemplate and enables #isAlphabeticalIndexingAllowed, the user will be able to select a letter on a keyboard to jump to their playlists that start with that letter. When this happens, the list is reconstructed and sorted alphabetically, then shown to the user, jumping down to the letter. Items that are set to #setIndexable(false), do not show up in this new sorted list. Sticking with the media example, a media app may choose to hide things like "autogenerated playlists" from the list and only keep user created playlists.

Individual items can be set to be included or excluded from filtered lists, but it's also possible to enable/disable the creation of filtered lists as a whole via the template's API (eg. SectionedItemTemplate .Builder#setAlphabeticalIndexingAllowed(Boolean)).

setMetadata

Added in 1.0.0
public @NonNull Row.Builder setMetadata(@NonNull Metadata metadata)

Sets the Metadata associated with the row.

Parameters
@NonNull Metadata metadata

The metadata to set with the row. Pass EMPTY_METADATA to not associate any metadata with the row

setNumericDecoration

Added in 1.3.0
@RequiresCarApi(value = 6)
public @IntRange(from = 0) @NonNull Row.Builder setNumericDecoration(int decoration)

Sets a numeric decoration to display in the row.

Numeric decorations are displayed at the end of the row, but before any actions. Numeric decorations are not displayed in half-list templates.

Numeric decorations typically represent a quantity of unseen content. For example, a decoration might represent a number of missed notifications, or a number of unread messages in a conversation.

Parameters
int decoration

the int to display. Must be positive, zero, or equal to NO_DECORATION.
Throws
java.lang.IllegalArgumentException

if decoration is invalid

setOnClickListener

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

Sets the OnClickListener to be called back when the row is clicked.

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

setTitle

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

Sets the title of the row, 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 Row.Builder setTitle(@NonNull CharSequence title)

Sets the title of the row.

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

setToggle

Added in 1.0.0
public @NonNull Row.Builder setToggle(@NonNull Toggle toggle)

Sets a Toggle to show in the row.

If a row has a toggle set, then no Action, OnClickListener or numeric decoration can be set.

Throws
java.lang.NullPointerException

if toggle is null