ListBuilder

public class ListBuilder
extends TemplateSliceBuilder

java.lang.Object
   ↳ androidx.slice.builders.TemplateSliceBuilder
     ↳ androidx.slice.builders.ListBuilder


Builder for constructing slices composed of rows of content.

A slice is a piece of templated app content that can be presented outside of the app providing the slice in a SliceView. To provide a slice you should implement a SliceProvider and use ListBuilder to construct your slice when SliceProvider.onBindSlice(Uri) is called.

ListBuilder allows you to construct a slice made up of rows of content. The row types that ListBuilder supports are:

  • ListBuilder.HeaderBuilder - The first row of your slice should be a header. The header supports a title, subtitle, and tappable row action. A header can also have a summary of the contents of the slice which can be shown when not all of the slice can be displayed.
  • ListBuilder.RowBuilder - A basic row supports title, subtitle, timestamps, and various action types.
  • GridRowBuilder - A grid row supports cells of vertically laid out content displayed in a single row.
  • ListBuilder.RangeBuilder - A range row supports displaying a horizontal progress indicator.
  • ListBuilder.InputRangeBuilder - An input range row supports displaying a horizontal slider allowing slider input (e.g. brightness or volume slider).
  • ListBuilder.RatingBuilder - An star rating row supports displaying a horizontal star rating input (e.g. rating 4/5 stars)

Handling modes

Slices are meant to be presented outside of the app providing them, the slice presenter could be an Android system surface or another application. The presenter will normally use a SliceView to display a slice. SliceView supports a couple of different modes. These modes are not controlled by the app providing the slice, but rather by the surface that is presenting the slice. To ensure your slice is presented correctly you should consider the different modes SliceView supports:

  • SliceView.MODE_SMALL - Only the first row of content is displayed in small format, normally this will be the header. If no header was set, then the first row will be used and may appear differently depending on the row type and the configuration of SliceView.
  • SliceView.MODE_LARGE - As many rows of content are shown as possible. If the presenter of the slice allows scrolling then all rows of content will be displayed in a scrollable view.
  • SliceView.MODE_SHORTCUT - In shortcut mode only a tappable image is displayed. The image and action used to represent this will be the primary action of your slice, i.e. ListBuilder.HeaderBuilder.setPrimaryAction(SliceAction).

Specifying actions

In addition to rows of content, ListBuilder can also have SliceActions added to it. These actions may appear differently on your slice depending on how SliceView is configured. Normally the actions appear as icons in the header of the slice.

How much content to add

There is no limit to the number of rows added to ListBuilder, however, the contents of a slice should be related to a primary task, action, or set of information. For example: it might make sense for a slice to manage wi-fi state to have a row for each available network, this might result in a large number of rows but each of these rows serve utility for the primary purpose of the slice which is managing wi-fi.

Note that scrolling on SliceView can be disabled, in which case only the header and one or two rows of content may be shown for your slice. If your slice contains many rows of content to scroll through (e.g. list of wifi networks), consider using setSeeMoreAction(PendingIntent) to provide a link to open the activity associated with the content.

Summary

Nested classes

class ListBuilder.HeaderBuilder

Builder to construct a header row. 

class ListBuilder.InputRangeBuilder

Builder to construct a input range row. 

class ListBuilder.RangeBuilder

Builder to construct a range row which can be added to a ListBuilder

class ListBuilder.RatingBuilder

Builder to construct a input star rating. 

class ListBuilder.RowBuilder

Builder to construct a row. 

Constants

int ACTION_WITH_LABEL

Indicates that an button should be presented with text.

int ICON_IMAGE

Indicates that an image should be presented as an icon and it can be tinted.

long INFINITY

Constant representing infinity.

int LARGE_IMAGE

Indicates that an image presented in a larger size and it shouldn't be tinted.

int RANGE_MODE_DETERMINATE

Indicates that the progress bar should be presented in determinate mode.

int RANGE_MODE_INDETERMINATE

Indicates that the progress bar should be presented in indeterminate mode.

int RANGE_MODE_STAR_RATING

Indicates that the progress bar should be presented as a star rating.

int RAW_IMAGE_LARGE

Indicates that an image should be presented in its intrinsic size and shouldn't be tinted.

int RAW_IMAGE_SMALL

Indicates that an image should be presented in its intrinsic size and shouldn't be tinted.

int SMALL_IMAGE

Indicates that an image should be presented in a smaller size and it shouldn't be tinted.

int UNKNOWN_IMAGE

Indicates that an image mode is unknown.

Public constructors

ListBuilder(Context context, Uri uri, long ttl)

Create a ListBuilder for constructing slice content.

ListBuilder(Context context, Uri uri, Duration ttl)

Create a ListBuilder for constructing slice content.

Public methods

ListBuilder addAction(SliceAction action)

Adds an action to this list builder.

ListBuilder addGridRow(GridRowBuilder builder)

Add a grid row to the list builder.

ListBuilder addInputRange(ListBuilder.InputRangeBuilder b)

Add an input range row to the list builder.

ListBuilder addRange(ListBuilder.RangeBuilder rangeBuilder)

Add a range row to the list builder.

ListBuilder addRating(ListBuilder.RatingBuilder b)

Add an star rating row to the list builder.

ListBuilder addRow(ListBuilder.RowBuilder builder)

Add a row to the list builder.

ListBuilder addSelection(SelectionBuilder selectionBuilder)

Add a selection row to the list builder.

Slice build()

Construct the slice defined by this ListBuilder.

ListBuilder setAccentColor(int color)

Sets the color to use on tintable items within the list builder.

ListBuilder setHeader(ListBuilder.HeaderBuilder builder)

Sets a header for this list builder.

ListBuilder setHostExtras(PersistableBundle extras)

Sets additional information to be passed to the host of the slice.

ListBuilder setIsError(boolean isError)

Sets whether this slice indicates an error, i.e.

ListBuilder setKeywords(Set<String> keywords)

Sets keywords to associate with this slice.

ListBuilder setLayoutDirection(int layoutDirection)

Sets the desired layout direction for this slice.

ListBuilder setSeeMoreAction(PendingIntent intent)

If all content in a slice cannot be shown, a "see more" affordance may be displayed where the content is cut off.

ListBuilder setSeeMoreAction(RemoteCallback callback)

If all content in a slice cannot be shown, a "see more" affordance may be displayed where the content is cut off.

ListBuilder setSeeMoreRow(ListBuilder.RowBuilder builder)

If all content in a slice cannot be shown, the row added here may be displayed where the content is cut off.

Inherited methods

Constants

ACTION_WITH_LABEL

public static final int ACTION_WITH_LABEL

Indicates that an button should be presented with text.

Constant Value: 6 (0x00000006)

ICON_IMAGE

public static final int ICON_IMAGE

Indicates that an image should be presented as an icon and it can be tinted.

Constant Value: 0 (0x00000000)

INFINITY

public static final long INFINITY

Constant representing infinity.

Constant Value: -1 (0xffffffffffffffff)

LARGE_IMAGE

public static final int LARGE_IMAGE

Indicates that an image presented in a larger size and it shouldn't be tinted.

Constant Value: 2 (0x00000002)

RANGE_MODE_DETERMINATE

public static final int RANGE_MODE_DETERMINATE

Indicates that the progress bar should be presented in determinate mode.

Constant Value: 0 (0x00000000)

RANGE_MODE_INDETERMINATE

public static final int RANGE_MODE_INDETERMINATE

Indicates that the progress bar should be presented in indeterminate mode.

Constant Value: 1 (0x00000001)

RANGE_MODE_STAR_RATING

public static final int RANGE_MODE_STAR_RATING

Indicates that the progress bar should be presented as a star rating.

Constant Value: 2 (0x00000002)

RAW_IMAGE_LARGE

public static final int RAW_IMAGE_LARGE

Indicates that an image should be presented in its intrinsic size and shouldn't be tinted. If SliceView in the call-site doesn't support RAW_IMAGE, fallback to LARGE_IMAGE instead.

Constant Value: 4 (0x00000004)

RAW_IMAGE_SMALL

public static final int RAW_IMAGE_SMALL

Indicates that an image should be presented in its intrinsic size and shouldn't be tinted. If SliceView in the call-site doesn't support RAW_IMAGE, fallback to SMALL_IMAGE instead.

Constant Value: 3 (0x00000003)

SMALL_IMAGE

public static final int SMALL_IMAGE

Indicates that an image should be presented in a smaller size and it shouldn't be tinted.

Constant Value: 1 (0x00000001)

UNKNOWN_IMAGE

public static final int UNKNOWN_IMAGE

Indicates that an image mode is unknown.

Constant Value: 5 (0x00000005)

Public constructors

ListBuilder

public ListBuilder (Context context, 
                Uri uri, 
                long ttl)

Create a ListBuilder for constructing slice content.

A slice requires an associated time-to-live, i.e. how long the data contained in the slice can remain fresh. If your slice has content that is not time sensitive, set a TTL of INFINITY.

Parameters
context Context

uri Uri: Uri to tag for this slice.

ttl long: the length in milliseconds that the content in this slice can live for.

ListBuilder

public ListBuilder (Context context, 
                Uri uri, 
                Duration ttl)

Create a ListBuilder for constructing slice content.

A slice requires an associated time-to-live, i.e. how long the data contained in the slice can remain fresh. If your slice has content that is not time sensitive, set Duration to null and the TTL will be INFINITY.

Parameters
context Context

uri Uri: Uri to tag for this slice.

ttl Duration: the Duration that the content in this slice can live for.

Public methods

addAction

public ListBuilder addAction (SliceAction action)

Adds an action to this list builder.

Actions added with this method are grouped together on the list template and represented as tappable icons or images. These actions may appear differently on the slice depending on how the SliceView is configured. Generally these actions will be displayed in the order they were added, however, if not all actions can be displayed then actions with a higher priority may be shown first.

These actions are only displayed when the slice is displayed in SliceView.MODE_LARGE or SliceView.MODE_SMALL.

These actions differ from a slice's primary action. The primary action is the SliceAction set on the first row of the slice, normally from ListBuilder.HeaderBuilder.setPrimaryAction(SliceAction).

Parameters
action SliceAction

Returns
ListBuilder

addGridRow

public ListBuilder addGridRow (GridRowBuilder builder)

Add a grid row to the list builder.

Note that grid rows cannot be the first row in your slice. Adding a grid row first without calling setHeader(HeaderBuilder) will result in IllegalStateException when the slice is built.

Parameters
builder GridRowBuilder

Returns
ListBuilder

addInputRange

public ListBuilder addInputRange (ListBuilder.InputRangeBuilder b)

Add an input range row to the list builder.

If ListBuilder.InputRangeBuilder.setValue(int) is not between ListBuilder.InputRangeBuilder.setMin(int) and ListBuilder.InputRangeBuilder.setMax(int), this will throw IllegalArgumentException.

Parameters
b ListBuilder.InputRangeBuilder

Returns
ListBuilder

addRange

public ListBuilder addRange (ListBuilder.RangeBuilder rangeBuilder)

Add a range row to the list builder.

If ListBuilder.RangeBuilder.setValue(int) is not between 0 and ListBuilder.RangeBuilder.setMax(int), this will throw IllegalArgumentException.

Parameters
rangeBuilder ListBuilder.RangeBuilder

Returns
ListBuilder

addRating

public ListBuilder addRating (ListBuilder.RatingBuilder b)

Add an star rating row to the list builder.

If ListBuilder.RatingBuilder.setValue(float) is not between ListBuilder.RatingBuilder.setMin(int) and ListBuilder.RatingBuilder.setMax(int), this will show all stars as unselected.

Parameters
b ListBuilder.RatingBuilder

Returns
ListBuilder

addRow

public ListBuilder addRow (ListBuilder.RowBuilder builder)

Add a row to the list builder.

Parameters
builder ListBuilder.RowBuilder

Returns
ListBuilder

addSelection

public ListBuilder addSelection (SelectionBuilder selectionBuilder)

Add a selection row to the list builder.

Parameters
selectionBuilder SelectionBuilder

Returns