belongs to Maven artifact androidx.slice:slice-builders:1.0.0-alpha1

ListBuilder

public class ListBuilder
extends TemplateSliceBuilder

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


A slice can be constructed with ListBuilder.

A slice is a piece of templated app content that can be presented outside of the app 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. A list should have at least one row of content as well as a primary SliceAction. The row types that ListBuilder supports are:

  • ListBuilder.HeaderBuilder - A list can have one header which appears at the top of the list. The header can support showing title, subtitle, and a 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, images, row action, icon actions, and toggle actions.
  • 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).

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 the SliceView is configured. Normally the actions would appear in the header.

To ensure your slice is presented correctly you should consider the configurations SliceView supports:

  • SliceView.MODE_SHORTCUT - The primary SliceAction of the slice is used your primary action should contain an image and title representative of your slice. If providing a tintable icon, use setAccentColor(int) to specify the color. If a header has been specified for the list, the primary action associated with it will be used, otherwise it will be the primary action associated with the first row of the list.
  • SliceView.MODE_SMALL - Only a single row of content is displayed in small format. If a header has been specified it will be displayed. 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.

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 addSeeMoreAction(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.RowBuilder

Builder to construct a row. 

Constants

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 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)

This constructor is deprecated. TO BE REMOVED; use ListBuilder(Context, Uri, long).

ListBuilder(Context context, Uri uri, long ttl)

Create a builder which will construct a slice that will display rows of content.

Public methods

ListBuilder addAction(SliceAction action)

Adds an action to this list builder.

ListBuilder addGrid(GridBuilder builder)

This method is deprecated. TO BE REMOVED; use addGridRow(GridRowBuilder) instead

ListBuilder addGrid(Consumer<GridBuilder> c)

This method is deprecated. TO BE REMOVED; use addGridRow(GridRowBuilder) instead

ListBuilder addGridRow(GridRowBuilder builder)

Add a grid row to the list builder.

ListBuilder addGridRow(Consumer<GridRowBuilder> c)

Add a grid row to the list builder.

ListBuilder addInputRange(ListBuilder.InputRangeBuilder b)

Add an input range row to the list builder.

ListBuilder addInputRange(Consumer<ListBuilder.InputRangeBuilder> c)

Add an input range row to the list builder.

ListBuilder addRange(Consumer<ListBuilder.RangeBuilder> c)

Add a range row to the list builder.

ListBuilder addRange(ListBuilder.RangeBuilder rangeBuilder)

Add a range row to the list builder.

ListBuilder addRow(ListBuilder.RowBuilder builder)

Add a row to the list builder.

ListBuilder addRow(Consumer<ListBuilder.RowBuilder> c)

Add a row to the list builder.

ListBuilder addSeeMoreAction(PendingIntent intent)

This method is deprecated. TO BE REMOVED

ListBuilder addSeeMoreRow(ListBuilder.RowBuilder builder)

This method is deprecated. TO BE REMOVED

ListBuilder addSeeMoreRow(Consumer<ListBuilder.RowBuilder> c)

This method is deprecated. TO BE REMOVED

ListBuilder setAccentColor(int color)

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

ListBuilder setColor(int color)

This method is deprecated. TO BE REMOVED; use setAccentColor(int) instead.

ListBuilder setHeader(ListBuilder.HeaderBuilder builder)

Sets a header for this list builder.

ListBuilder setHeader(Consumer<ListBuilder.HeaderBuilder> c)

Sets a header for this list builder.

ListBuilder setKeywords(List<String> keywords)

Sets keywords to associate with 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 setSeeMoreRow(Consumer<ListBuilder.RowBuilder> c)

If all content in a slice cannot be shown, the row added here 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

ICON_IMAGE

int ICON_IMAGE

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

Constant Value: 0 (0x00000000)

INFINITY

long INFINITY

Constant representing infinity.

Constant Value: -1 (0xffffffffffffffff)

LARGE_IMAGE

int LARGE_IMAGE

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

Constant Value: 2 (0x00000002)

SMALL_IMAGE

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

int UNKNOWN_IMAGE

Indicates that an image mode is unknown.

Constant Value: 3 (0x00000003)

Public constructors

ListBuilder

ListBuilder (Context context, 
                Uri uri)

This constructor is deprecated.
TO BE REMOVED; use ListBuilder(Context, Uri, long).

Create a builder which will construct a slice made up of rows of content.

Parameters
context Context

uri Uri: Uri to tag for this slice.

ListBuilder

ListBuilder (Context context, 
                Uri uri, 
                long ttl)

Create a builder which will construct a slice that will display rows of 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.

Public methods

addAction

ListBuilder addAction (SliceAction action)

Adds an action to this list builder.

Actions added with this method are grouped together on the list template. 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.

Parameters
action SliceAction

Returns
ListBuilder

addGrid

ListBuilder addGrid (GridBuilder builder)

This method is deprecated.
TO BE REMOVED; use addGridRow(GridRowBuilder) instead

Add a grid row to the list builder.

Parameters
builder GridBuilder

Returns
ListBuilder

addGrid

ListBuilder addGrid (Consumer<GridBuilder> c)

This method is deprecated.
TO BE REMOVED; use addGridRow(GridRowBuilder) instead

Add a grid row to the list builder.

Parameters
c Consumer

Returns
ListBuilder

addGridRow

ListBuilder addGridRow (GridRowBuilder builder)

Add a grid row to the list builder.

Parameters
builder GridRowBuilder

Returns
ListBuilder

addGridRow

ListBuilder addGridRow (Consumer<GridRowBuilder> c)

Add a grid row to the list builder.

Parameters
c Consumer

Returns
ListBuilder

addInputRange

ListBuilder addInputRange (ListBuilder.InputRangeBuilder b)

Add an input range row to the list builder.

Parameters
b ListBuilder.InputRangeBuilder

Returns
ListBuilder

addInputRange

ListBuilder addInputRange (Consumer<ListBuilder.InputRangeBuilder> c)

Add an input range row to the list builder.

Parameters
c Consumer

Returns
ListBuilder

addRange

ListBuilder addRange (Consumer<ListBuilder.RangeBuilder> c)

Add a range row to the list builder.

Parameters
c Consumer

Returns
ListBuilder

addRange

ListBuilder addRange (ListBuilder.RangeBuilder rangeBuilder)

Add a range row to the list builder.

Parameters
rangeBuilder ListBuilder.RangeBuilder

Returns
ListBuilder

addRow

ListBuilder addRow (ListBuilder.RowBuilder builder)

Add a row to the list builder.

Parameters
builder ListBuilder.RowBuilder

Returns
ListBuilder

addRow

ListBuilder addRow (Consumer<ListBuilder.RowBuilder> c)

Add a row to the list builder.

Parameters
c Consumer

Returns
ListBuilder

addSeeMoreAction

ListBuilder addSeeMoreAction (PendingIntent intent)

This method is deprecated.
TO BE REMOVED

If all content in a slice cannot be shown, a "see more" affordance may be displayed where the content is cut off. The action added here should take the user to an activity to see all of the content, and will be invoked when the "see more" affordance is tapped.

Only one see more affordance can be added, this throws IllegalStateException if a row or action has been previously added.

Parameters
intent PendingIntent

Returns
ListBuilder

addSeeMoreRow

ListBuilder addSeeMoreRow (ListBuilder.RowBuilder builder)

This method is deprecated.
TO BE REMOVED

If all content in a slice cannot be shown, the row added here may be displayed where the content is cut off. This row should have an affordance to take the user to an activity to see all of the content.

This method should only be used if you want to display a custom row to indicate more content, consider using addSeeMoreAction(PendingIntent) otherwise. If you do choose to specify a custom row, the row should have a content intent or action end item specified to take the user to an activity to see all of the content.

Only one see more affordance can be added, this throws IllegalStateException if a row or action has been previously added.

Parameters
builder ListBuilder.RowBuilder

Returns
ListBuilder

addSeeMoreRow

ListBuilder addSeeMoreRow (Consumer<ListBuilder.RowBuilder> c)

This method is deprecated.
TO BE REMOVED

If all content in a slice cannot be shown, the row added here may be displayed where the content is cut off. This row should have an affordance to take the user to an activity to see all of the content.

This method should only be used if you want to display a custom row to indicate more content, consider using addSeeMoreAction(PendingIntent) otherwise. If you do choose to specify a custom row, the row should have a content intent or action end item specified to take the user to an activity to see all of the content.

Only one see more affordance can be added, this throws IllegalStateException if a row or action has been previously added.

Parameters
c Consumer

Returns
ListBuilder

setAccentColor

ListBuilder setAccentColor (int color)

Sets the color to use on tintable items within the list builder. Things that might be tinted are:

Parameters
color int

Returns
ListBuilder

setColor

ListBuilder setColor (int color)

This method is deprecated.
TO BE REMOVED; use setAccentColor(int) instead.

Parameters
color int

Returns
ListBuilder

setHeader

ListBuilder setHeader (ListBuilder.HeaderBuilder builder)

Sets a header for this list builder. A list can have only one header. Setting a header allows some flexibility in what's displayed in your slice when SliceView displays in SliceView.MODE_SMALL and SliceView.MODE_SHORTCUT.

In MODE_SMALL, the header row shown if one has been added. The header will also display the ListBuilder.HeaderBuilder.setSummary(CharSequence) text if it has been specified, allowing a summary of otherwise hidden content to be shown.

In MODE_SHORTCUT, the primary action set using ListBuilder.HeaderBuilder.setPrimaryAction(SliceAction) will be used for the shortcut representation.

Parameters
builder ListBuilder.HeaderBuilder

Returns
ListBuilder

setHeader

ListBuilder setHeader (Consumer<ListBuilder.HeaderBuilder> c)

Sets a header for this list builder. A list can have only one header. Setting a header allows some flexibility in what's displayed in your slice when SliceView displays in SliceView.MODE_SMALL and SliceView.MODE_SHORTCUT.

In MODE_SMALL, the header row shown if one has been added. The header will also display the ListBuilder.HeaderBuilder.setSummary(CharSequence) text if it has been specified, allowing a summary of otherwise hidden content to be shown.

In MODE_SHORTCUT, the primary action set using ListBuilder.HeaderBuilder.setPrimaryAction(SliceAction) will be used for the shortcut representation.

Parameters
c Consumer

Returns
ListBuilder

setKeywords

ListBuilder setKeywords (List<String> keywords)

Sets keywords to associate with this slice.

Parameters
keywords List

Returns
ListBuilder

setSeeMoreAction

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. The action added here should take the user to an activity to see all of the content, and will be invoked when the "see more" affordance is tapped.

Only one see more affordance can be added, this throws IllegalStateException if a row or action has been previously added.

Parameters
intent PendingIntent

Returns
ListBuilder

setSeeMoreRow

ListBuilder setSeeMoreRow (Consumer<ListBuilder.RowBuilder> c)

If all content in a slice cannot be shown, the row added here may be displayed where the content is cut off. This row should have an affordance to take the user to an activity to see all of the content.

This method should only be used if you want to display a customized row to indicate more content, consider using addSeeMoreAction(PendingIntent) otherwise. If you do choose to specify a custom row, the row should have a content intent or action end item specified to take the user to an activity to see all of the content. The row added here will only appear when not all content can be displayed and it will not be styled any differently from row built by ListBuilder.RowBuilder normally.

Only one see more affordance can be added, this throws IllegalStateException if a row or action has been previously added.

Parameters
c Consumer

Returns
ListBuilder

setSeeMoreRow

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. This row should have an affordance to take the user to an activity to see all of the content.

This method should only be used if you want to display a customized row to indicate more content, consider using addSeeMoreAction(PendingIntent) otherwise. If you do choose to specify a custom row, the row should have a content intent or action end item specified to take the user to an activity to see all of the content. The row added here will only appear when not all content can be displayed and it will not be styled any differently from row built by ListBuilder.RowBuilder normally.

Only one see more affordance can be added, this throws IllegalStateException if a row or action has been previously added.

Parameters
builder ListBuilder.RowBuilder

Returns
ListBuilder