Row.Builder

public static final class Row.Builder
extends Object

java.lang.Object
   ↳ androidx.car.app.model.Row.Builder


A builder of Row.

Summary

Public constructors

Builder()

Returns an empty Row.Builder instance.

Public methods

Row.Builder addText(CarText text)

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

Row.Builder addText(CharSequence text)

Adds a text string to the row below the title.

Row build()

Constructs the Row defined by this builder.

Row.Builder setBrowsable(boolean isBrowsable)

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

Row.Builder setImage(CarIcon image, int imageType)

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

Row.Builder setImage(CarIcon image)

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

Row.Builder setMetadata(Metadata metadata)

Sets the Metadata associated with the row.

Row.Builder setOnClickListener(OnClickListener onClickListener)

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

Row.Builder setTitle(CharSequence title)

Sets the title of the row.

Row.Builder setTitle(CarText title)

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

Row.Builder setToggle(Toggle toggle)

Sets a Toggle to show in the row.

Inherited methods

Public constructors

Builder

public Builder ()

Returns an empty Row.Builder instance.

Public methods

addText

public Row.Builder addText (CarText text)

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

Parameters
text CarText

Returns
Row.Builder

Throws
NullPointerException if text is null

addText

public Row.Builder addText (CharSequence text)

Adds a text string to the row below the title.

The text's color can be customized with ForegroundCarColorSpan 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
 

Parameters
text CharSequence

Returns
Row.Builder

Throws
NullPointerException if text is null

build

public Row build ()

Constructs the Row defined by this builder.

Returns
Row

Throws
IllegalStateException if the row's title is not set, if it is a browsable row and has a Toggle, if it is a browsable row but does not have a OnClickListener, or if it has both a OnClickListener and a Toggle

setBrowsable

public 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.

Parameters
isBrowsable boolean

Returns
Row.Builder

setImage

public Row.Builder setImage (CarIcon image, 
                int imageType)

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

For a custom CarIcon, its IconCompat instance can be of IconCompat.TYPE_BITMAP, IconCompat.TYPE_RESOURCE, or IconCompat.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 Row.IMAGE_TYPE_ICON, Row.IMAGE_TYPE_SMALL or Row.IMAGE_TYPE_LARGE

Returns
Row.Builder

Throws
NullPointerException if image is null

setImage

public Row.Builder setImage (CarIcon image)

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

Parameters
image CarIcon

Returns
Row.Builder

Throws
NullPointerException if image is null

setMetadata

public Row.Builder setMetadata (Metadata metadata)

Sets the Metadata associated with the row.

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

Returns
Row.Builder

setOnClickListener

public Row.Builder setOnClickListener (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 Looper.getMainLooper().

Parameters
onClickListener OnClickListener

Returns
Row.Builder

Throws
NullPointerException if onClickListener is null

setTitle

public Row.Builder setTitle (CharSequence title)

Sets the title of the row.

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

Parameters
title CharSequence

Returns
Row.Builder

Throws
NullPointerException if title is null
IllegalArgumentException if title is empty

setTitle

public Row.Builder setTitle (CarText title)

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

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

Parameters
title CarText

Returns
Row.Builder

Throws
IllegalArgumentException if title is null or empty

setToggle

public Row.Builder setToggle (Toggle toggle)

Sets a Toggle to show in the row.

Parameters
toggle Toggle

Returns
Row.Builder

Throws
NullPointerException if toggle is null