Row.Builder

class Row.Builder


A builder of Row.

Summary

Public constructors

Returns an empty Builder instance.

Public functions

Row.Builder
@RequiresCarApi(value = 6)
addAction(action: Action)

Adds an additional action to the end of the row.

Row.Builder

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

Row.Builder

Adds a text string to the row below the title.

Row

Constructs the Row defined by this builder.

Row.Builder
setBrowsable(isBrowsable: Boolean)

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

Row.Builder
@RequiresCarApi(value = 5)
setEnabled(enabled: Boolean)

Sets the initial enabled state for Row.

Row.Builder
setImage(image: CarIcon)

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

Row.Builder
setImage(image: CarIcon, imageType: Int)

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

Row.Builder
setMetadata(metadata: Metadata)

Sets the Metadata associated with the row.

@IntRange(from = 0) Row.Builder
@RequiresCarApi(value = 6)
setNumericDecoration(decoration: Int)

Sets a numeric decoration to display in the row.

Row.Builder

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

Row.Builder
setTitle(title: CarText)

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

Row.Builder

Sets the title of the row.

Row.Builder
setToggle(toggle: Toggle)

Sets a Toggle to show in the row.

Public constructors

Builder

Added in 1.0.0
Builder()

Returns an empty Builder instance.

Public functions

addAction

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

Adds an additional action to the end of the row.

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
fun addText(text: CarText): Row.Builder

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
fun addText(text: CharSequence): Row.Builder

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

build

Added in 1.0.0
fun build(): Row

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
fun setBrowsable(isBrowsable: Boolean): Row.Builder

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)
fun setEnabled(enabled: Boolean): Row.Builder

Sets the initial enabled state for Row.

The default state of a Row is enabled.

setImage

Added in 1.0.0
fun setImage(image: CarIcon): Row.Builder

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
fun setImage(image: CarIcon, imageType: Int): Row.Builder

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
image: CarIcon

the CarIcon to display or null to not display one

imageType: Int

one of IMAGE_TYPE_ICON, IMAGE_TYPE_SMALL or IMAGE_TYPE_LARGE

Throws
java.lang.NullPointerException

if image is null

setMetadata

Added in 1.0.0
fun setMetadata(metadata: Metadata): Row.Builder

Sets the Metadata associated with the row.

Parameters
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)
fun setNumericDecoration(decoration: Int): @IntRange(from = 0) Row.Builder

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
decoration: Int

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
fun setOnClickListener(onClickListener: OnClickListener): Row.Builder

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
fun setTitle(title: CarText): Row.Builder

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
fun setTitle(title: CharSequence): Row.Builder

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
fun setToggle(toggle: Toggle): Row.Builder

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