This page details the customization options for CarUiListItem list items.
The accepted paradigm for using the Car UI library to display a list of items
is to use a CarUiRecyclerView in conjunction with a
CarUiListItemAdapter and CarUiListItem objects.
CarUiRecyclerView customization is covered in
caruirecyclerview.
Prerequisites
The following content presumes an understanding of runtime resource overlays (RRO) described in Customize apps.
About CarUiListItem
List items can be one of two high-level types, header or content. Each is described below.
Header
CarUiListItemAdapter binds objects of type CarUiHeaderListItem
to a view inflated from the car_ui_header_list_item layout file, which contains
these views:
| Views | |
|---|---|
title |
Title TextView |
body |
Body TextView |
For example, the header list item below is configured to display a title and body text:
Content
CarUiListItemAdapter binds objects of type CarUiHeaderListItem
to a view inflated from the car_ui_list_item layout file. This file
contains these views:
| Views | |
|---|---|
icon_container |
Container for the primary icon |
title |
Title TextView |
body |
Body TextView |
action_container |
Container for the action view |
For example, the content list item below was configured to display an icon and a switch:
Icons
Depending on the icon type configured for the list item, one of the following three views is used for the primary icon:
| Views | |
|---|---|
icon |
Standard icon ImageView |
content_icon |
Content icon ImageView |
avatar_icon |
Avatar icon ImageView |
Action elements
At most, one of the following action element views is displayed, based on the action type for the list item:
| Views | |
|---|---|
switch_widget |
Switch |
checkbox_widget |
CheckBox |
radio_button_widget |
RadioButton |
supplemental_icon |
ImageView |
Customize text
Text styling in both header and content list items is controlled by text appearances styles defined in the Car UI library. To override the text styling of list items, override the corresponding styles listed below.
To customize header styles:
| Header styles | |
|---|---|
| Title text | @style/TextAppearance.CarUi.ListItem |
| Body text | @style/TextAppearance.CarUi.ListItem.Body |
To customize content styles:
| Content styles | |
|---|---|
| Title text | @style/TextAppearance.CarUi.ListItem.Header |
| Body text | @style/TextAppearance.CarUi.ListItem.Body |
Customize icons
Content list items can contain both a primary and a supplemental icon.
Primary icon
Although there are three ImageView objects defined within the icon container
in the content list item layout, at most one icon is displayed based on the list
item's specified icon type. At item bind time, CarUiListItemAdapter sets the
appropriate visibility for the icon ImageView objects.
The width and height of icons are controlled by dimension values that can be overlaid to control the sizing. The dimension values that specify the width and height for the various icon types are listed below.
Standard icon
By default, standard icons have equal height and width.
| Standard icon | |
|---|---|
| Width | car_ui_list_item_icon_size |
| Height | car_ui_list_item_icon_size |
Content icon
| Content icon | |
|---|---|
| Width | car_ui_list_item_content_icon_width |
| Height | car_ui_list_item_content_icon_height |
Avatar icon
By default, primary icons are centered within the icon container view, which
has a width defined by the car_ui_list_item_icon_container_width
dimension value.
| Avatar icon | |
|---|---|
| Width | car_ui_list_item_content_icon_width |
| Height | car_ui_list_item_content_icon_height |
Supplemental icon
The supplemental icon is centered within the action container view. Both the
width and height of the supplemental icon are defined by the
car_ui_list_item_supplemental_icon_size dimension value. Overlay this dimension
value to change the size of the supplemental icon.