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)
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 ofSliceView
.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)
.
In addition to rows of content, ListBuilder can also have SliceAction
s 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.
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.
See also:
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 |
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 | |
---|---|
ListBuilder |
build
public Slice build ()
Construct the slice defined by this ListBuilder.
Note that a ListBuilder requires a row containing a piece of text that is not created
from a GridRowBuilder
. If the first row added does not fulfill this requirement,
build the slice will throw IllegalStateException
.
Note that a ListBuilder requires a primary action, this can be set on any of the rows added
to the list. If a primary action has not been set on any of the rows, building this slice
will throw IllegalStateException
.
Returns | |
---|---|
Slice |
setAccentColor
public ListBuilder setAccentColor (int color)
Sets the color to use on tintable items within the list builder. Things that might be tinted are:
- Any
SliceAction
s within your slice. - UI controls such as
Switch
s orSeekBar
s - Tinting the
SliceView.MODE_SHORTCUT
representation
Parameters | |
---|---|
color |
int |
Returns | |
---|---|
ListBuilder |
setHeader
public 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 |
setHostExtras
public ListBuilder setHostExtras (PersistableBundle extras)
Sets additional information to be passed to the host of the slice.
Parameters | |
---|---|
extras |
PersistableBundle : The Bundle of extras to add to this slice.
|
Returns | |
---|---|
ListBuilder |
setIsError
public ListBuilder setIsError (boolean isError)
Sets whether this slice indicates an error, i.e. the normal contents of this slice are unavailable and instead the slice contains a message indicating an error.
Parameters | |
---|---|
isError |
boolean |
Returns | |
---|---|
ListBuilder |
setKeywords
public ListBuilder setKeywords (Set<String> keywords)
Sets keywords to associate with this slice.
Parameters | |
---|---|
keywords |
Set |
Returns | |
---|---|
ListBuilder |
setLayoutDirection
public ListBuilder setLayoutDirection (int layoutDirection)
Sets the desired layout direction for this slice.
Parameters | |
---|---|
layoutDirection |
int : the layout direction to set.
|
Returns | |
---|---|
ListBuilder |
setSeeMoreAction
public 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 |
setSeeMoreAction
public 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. 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 | |
---|---|
callback |
RemoteCallback |
Returns | |
---|---|
ListBuilder |
setSeeMoreRow
public 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 setSeeMoreAction(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 |
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2021-02-24 UTC.