Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Guides Reference Samples Design & Quality
Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

TextListItem

public class TextListItem
extends ListItem<TextListItem.ViewHolder>

java.lang.Object
   ↳ androidx.car.widget.ListItem<androidx.car.widget.TextListItem.ViewHolder>
     ↳ androidx.car.widget.TextListItem

Class to build a list item of text.

An item supports primary action and supplemental action(s).

An item visually composes of 3 parts; each part may contain multiple views.

  • Primary Action: represented by an icon of following types.
    • Primary Icon - icon size could be large or small.
    • No Icon - no icon is shown.
    • Empty Icon - Text offsets start space as if there was an icon.
  • Text: supports any combination of the following text views.
    • Title
    • Body
  • Supplemental Action: represented by one of the following types; aligned toward the end of item.
    • Supplemental Icon
    • Switch

TextListItem binds data to TextListItem.ViewHolder based on components selected.

When conflicting setter methods are called (e.g. setting primary action to both primary icon and no icon), the last called method wins.

Summary

Nested classes

class TextListItem.ViewHolder

Holds views of TextListItem. 

Constants

int PRIMARY_ACTION_ICON_SIZE_LARGE

Large sized icon is as tall as a list item with only title text.

int PRIMARY_ACTION_ICON_SIZE_MEDIUM

Medium sized icon is slightly bigger than SMALL ones.

int PRIMARY_ACTION_ICON_SIZE_SMALL

Small sized icon is the mostly commonly used size.

Public constructors

TextListItem(Context context)

Public methods

static TextListItem.ViewHolder createViewHolder(View itemView)

Creates a TextListItem.ViewHolder.

int getViewType()

Used by ListItemAdapter to choose layout to inflate for view holder.

void onBind(TextListItem.ViewHolder viewHolder)

Hides all views in TextListItem.ViewHolder then applies ViewBinders to adjust view layout params.

void setBody(CharSequence body)

Sets the body text of item.

void setEnabled(boolean enabled)

Sets the enabled state of the bound ListItem.ViewHolder.

void setOnClickListener(View.OnClickListener listener)

Sets View.OnClickListener of TextListItem.

void setPrimaryActionEmptyIcon()

Sets Primary Action to be empty icon.

void setPrimaryActionIcon(int iconResId, int size)

This method is deprecated. Use setPrimaryActionIcon(Icon, int).

void setPrimaryActionIcon(Icon icon, int size)

Sets Primary Action to be represented by an icon.

void setPrimaryActionIcon(Drawable drawable, int size)

This method is deprecated. Use setPrimaryActionIcon(Icon, int).

void setPrimaryActionNoIcon()

Sets Primary Action to have no icon.

void setSupplementalIcon(Icon icon, boolean showDivider)

Sets Supplemental Action to be represented by an Supplemental Icon.

void setSupplementalIcon(int iconResId, boolean showDivider)

This method is deprecated. Use setSupplementalIcon(Icon, boolean).

void setSupplementalIcon(Drawable drawable, boolean showDivider)

This method is deprecated. Use setSupplementalIcon(Icon, boolean).

void setSupplementalIcon(Drawable drawable, boolean showDivider, View.OnClickListener listener)

This method is deprecated. Use setSupplementalIcon(Icon, boolean) and setSupplementalIconOnClickListener(View.OnClickListener).

void setSupplementalIcon(int iconResId, boolean showDivider, View.OnClickListener listener)

This method is deprecated. Use setSupplementalIcon(Icon, boolean) and setSupplementalIconOnClickListener(View.OnClickListener).

void setSupplementalIconOnClickListener(View.OnClickListener listener)

Sets an OnClickListener for the icon representing the Supplemental Action.

void setSwitch(boolean checked, boolean showDivider, CompoundButton.OnCheckedChangeListener listener)

This method is deprecated. Use SwitchListItem instead.

void setSwitchState(boolean isChecked)

This method is deprecated. Use SwitchListItem instead.

void setTitle(CharSequence title)

Sets the title of item.

Protected methods

Context getContext()
void resolveDirtyState()

Calculates the layout params for views in TextListItem.ViewHolder.

Inherited methods

Constants

PRIMARY_ACTION_ICON_SIZE_LARGE

public static final int PRIMARY_ACTION_ICON_SIZE_LARGE

Large sized icon is as tall as a list item with only title text. It is intended for album art.

Constant Value: 2 (0x00000002)

PRIMARY_ACTION_ICON_SIZE_MEDIUM

public static final int PRIMARY_ACTION_ICON_SIZE_MEDIUM

Medium sized icon is slightly bigger than SMALL ones. It is intended for profile pictures (avatar), in which case caller is responsible for passing in a circular image.

Constant Value: 1 (0x00000001)

PRIMARY_ACTION_ICON_SIZE_SMALL

public static final int PRIMARY_ACTION_ICON_SIZE_SMALL

Small sized icon is the mostly commonly used size. It's the same as supplemental action icon.

Constant Value: 0 (0x00000000)

Public constructors

TextListItem

public TextListItem (Context context)

Parameters
context Context

Public methods

createViewHolder

public static TextListItem.ViewHolder createViewHolder (View itemView)

Creates a TextListItem.ViewHolder.

Parameters
itemView View

Returns
TextListItem.ViewHolder

getViewType

public int getViewType ()

Used by ListItemAdapter to choose layout to inflate for view holder.

Returns
int type of this ListItem.

onBind

public void onBind (TextListItem.ViewHolder viewHolder)

Hides all views in TextListItem.ViewHolder then applies ViewBinders to adjust view layout params.

Parameters
viewHolder TextListItem.ViewHolder

setBody

public void setBody (CharSequence body)

Sets the body text of item.

Text beyond length required by regulation will be truncated.

Parameters
body CharSequence: text to be displayed.

setEnabled

public void setEnabled (boolean enabled)

Sets the enabled state of the bound ListItem.ViewHolder.

All visible children views of ViewHolder should be set to enabled. Caller is responsible for notifying ListItemAdapter about data change.

Disabled items are usually styled at 50% opacity. Consider similar styling for consistency.

Parameters
enabled boolean

setOnClickListener

public void setOnClickListener (View.OnClickListener listener)

Sets View.OnClickListener of TextListItem.

Parameters
listener View.OnClickListener

setPrimaryActionEmptyIcon

public void setPrimaryActionEmptyIcon ()

Sets Primary Action to be empty icon.

Text would have a start margin as if Primary Action were set to primary icon.

setPrimaryActionIcon

public void setPrimaryActionIcon (int iconResId, 
                int size)

This method is deprecated.
Use setPrimaryActionIcon(Icon, int).

Sets Primary Action to be represented by an icon.

Parameters
iconResId int: the resource identifier of the drawable.
size int: small/medium/large. Available as PRIMARY_ACTION_ICON_SIZE_SMALL, PRIMARY_ACTION_ICON_SIZE_MEDIUM, PRIMARY_ACTION_ICON_SIZE_LARGE.

setPrimaryActionIcon

public void setPrimaryActionIcon (Icon icon, 
                int size)

Sets Primary Action to be represented by an icon.

Parameters
icon Icon: An icon to set as primary action.
size int: small/medium/large. Available as PRIMARY_ACTION_ICON_SIZE_SMALL, PRIMARY_ACTION_ICON_SIZE_MEDIUM, PRIMARY_ACTION_ICON_SIZE_LARGE.

setPrimaryActionIcon

public void setPrimaryActionIcon (Drawable drawable, 
                int size)

This method is deprecated.
Use setPrimaryActionIcon(Icon, int).

Sets Primary Action to be represented by an icon.

Parameters
drawable Drawable: the Drawable to set, or null to clear the content.
size int: small/medium/large. Available as PRIMARY_ACTION_ICON_SIZE_SMALL, PRIMARY_ACTION_ICON_SIZE_MEDIUM, PRIMARY_ACTION_ICON_SIZE_LARGE.

setPrimaryActionNoIcon

public void setPrimaryActionNoIcon ()

Sets Primary Action to have no icon. Text would align to the start of item.

setSupplementalIcon

public void setSupplementalIcon (Icon icon, 
                boolean showDivider)

Sets Supplemental Action to be represented by an Supplemental Icon.

Parameters
icon Icon: An icon to set as supplemental action.
showDivider boolean: whether to display a vertical bar that separates text and Supplemental Icon.

setSupplementalIcon

public void setSupplementalIcon (int iconResId, 
                boolean showDivider)

This method is deprecated.
Use setSupplementalIcon(Icon, boolean).

Sets Supplemental Action to be represented by an Supplemental Icon.

Parameters
iconResId int: drawable resource id.
showDivider boolean: whether to display a vertical bar that separates text and Supplemental Icon.

setSupplementalIcon

public void setSupplementalIcon (Drawable drawable, 
                boolean showDivider)

This method is deprecated.
Use setSupplementalIcon(Icon, boolean).

Sets Supplemental Action to be represented by an Supplemental Icon.

Parameters
drawable Drawable: the Drawable to set, or null to clear the content.
showDivider boolean: whether to display a vertical bar that separates text and Supplemental Icon.

setSupplementalIcon

public void setSupplementalIcon (Drawable drawable, 
                boolean showDivider, 
                View.OnClickListener listener)

This method is deprecated.
Use setSupplementalIcon(Icon, boolean) and setSupplementalIconOnClickListener(View.OnClickListener).

Sets Supplemental Action to be represented by an Supplemental Icon.

Parameters
drawable Drawable: the Drawable to set, or null to clear the content.
showDivider boolean: whether to display a vertical bar that separates text and Supplemental Icon.
listener View.OnClickListener: the callback that will run when icon is clicked.

setSupplementalIcon

public void setSupplementalIcon (int iconResId, 
                boolean showDivider, 
                View.OnClickListener listener)

This method is deprecated.
Use setSupplementalIcon(Icon, boolean) and setSupplementalIconOnClickListener(View.OnClickListener).

Sets Supplemental Action to be represented by an Supplemental Icon.

Parameters
iconResId int: drawable resource id.
showDivider boolean: whether to display a vertical bar that separates text and Supplemental Icon.
listener View.OnClickListener: the callback that will run when icon is clicked.

setSupplementalIconOnClickListener

public void setSupplementalIconOnClickListener (View.OnClickListener listener)

Sets an OnClickListener for the icon representing the Supplemental Action.

Parameters
listener View.OnClickListener: the callback that will run when icon is clicked.

setSwitch

public void setSwitch (boolean checked, 
                boolean showDivider, 
                CompoundButton.OnCheckedChangeListener listener)

This method is deprecated.
Use SwitchListItem instead.

Sets Supplemental Action to be represented by a Switch.

Parameters
checked boolean: initial value for switched.
showDivider boolean: whether to display a vertical bar between switch and text.
listener CompoundButton.OnCheckedChangeListener: callback to be invoked when the checked state shown in the UI changes.

setSwitchState

public void setSwitchState (boolean isChecked)

This method is deprecated.
Use SwitchListItem instead.

Sets the state of Switch. For this method to take effect, setSwitch(boolean, boolean, CompoundButton.OnCheckedChangeListener) must be called first to set Supplemental Action as a Switch.

Parameters
isChecked boolean: sets the "checked/unchecked, namely on/off" state of switch.

setTitle

public void setTitle (CharSequence title)

Sets the title of item.

Primary text is Title by default. It can be set by setBody(CharSequence)

Title text is limited to one line, and ellipses at the end.

Parameters
title CharSequence: text to display as title.

Protected methods

getContext

protected Context getContext ()

Returns
Context

resolveDirtyState

protected void resolveDirtyState ()

Calculates the layout params for views in TextListItem.ViewHolder.