@RequiresApi(value = 19)
public class ListBuilder extends TemplateSliceBuilder

Known direct subclasses
ListBuilderDsl

Helper class annotated with @SliceMarker, which is annotated with @DslMarker.


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 androidx.slice.widget.SliceView. To provide a slice you should implement a androidx.slice.SliceProvider and use ListBuilder to construct your slice when onBindSlice is called.

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

  • 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.
  • 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.
  • RangeBuilder - A range row supports displaying a horizontal progress indicator.
  • InputRangeBuilder - An input range row supports displaying a horizontal slider allowing slider input (e.g. brightness or volume slider).
  • 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 androidx.slice.widget.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:

  • 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 androidx.slice.widget.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.
  • 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. setPrimaryAction.
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 androidx.slice.widget.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 to provide a link to open the activity associated with the content.

Summary

Nested types

Builder to construct a header row.

Builder to construct a input range row.

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

public final class ListBuilder.RatingBuilder

Builder to construct a input star rating.

Builder to construct a row.

Constants

static final int

Indicates that an button should be presented with text.

static final int

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

static final long

Constant representing infinity.

static final int

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

static final int

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

static final int

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

static final int

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

static final int

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

static final int

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

static final int

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

static final int

Indicates that an image mode is unknown.

Public constructors

@RequiresApi(value = 26)
ListBuilder(
    @NonNull Context context,
    @NonNull Uri uri,
    @Nullable Duration ttl
)

Create a ListBuilder for constructing slice content.

ListBuilder(@NonNull Context context, @NonNull Uri uri, long ttl)

Create a ListBuilder for constructing slice content.

Public methods

@NonNull ListBuilder

Adds an action to this list builder.

@NonNull ListBuilder

Add a grid row to the list builder.

@NonNull ListBuilder

Add an input range row to the list builder.

@NonNull ListBuilder

Add a range row to the list builder.

@NonNull ListBuilder

Add an star rating row to the list builder.

@NonNull ListBuilder

Add a row to the list builder.

@NonNull ListBuilder

Add a selection row to the list builder.

@NonNull Slice

Construct the slice defined by this ListBuilder.

@NonNull ListBuilder

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

@NonNull ListBuilder

Sets a header for this list builder.

@NonNull ListBuilder

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

@NonNull 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.

@NonNull ListBuilder

Sets keywords to associate with this slice.

@NonNull ListBuilder
setLayoutDirection(int layoutDirection)

Sets the desired layout direction for this slice.

@NonNull ListBuilder

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

@NonNull ListBuilder

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

@NonNull ListBuilder

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

Constants

ACTION_WITH_LABEL

Added in 1.1.0-alpha02
public static final int ACTION_WITH_LABEL = 6

Indicates that an button should be presented with text.

ICON_IMAGE

Added in 1.1.0-alpha02
public static final int ICON_IMAGE = 0

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

INFINITY

Added in 1.1.0-alpha02
public static final long INFINITY = -1

Constant representing infinity.

LARGE_IMAGE

Added in 1.1.0-alpha02
public static final int LARGE_IMAGE = 2

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

RANGE_MODE_DETERMINATE

Added in 1.1.0-alpha02
public static final int RANGE_MODE_DETERMINATE = 0

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

RANGE_MODE_INDETERMINATE

Added in 1.1.0-alpha02
public static final int RANGE_MODE_INDETERMINATE = 1

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

RANGE_MODE_STAR_RATING

Added in 1.1.0-alpha02
public static final int RANGE_MODE_STAR_RATING = 2

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

RAW_IMAGE_LARGE

Added in 1.1.0-alpha02
public static final int RAW_IMAGE_LARGE = 4

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.

RAW_IMAGE_SMALL

Added in 1.1.0-alpha02
public static final int RAW_IMAGE_SMALL = 3

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.

SMALL_IMAGE

Added in 1.1.0-alpha02
public static final int SMALL_IMAGE = 1

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

UNKNOWN_IMAGE

Added in 1.1.0-alpha02
public static final int UNKNOWN_IMAGE = 5

Indicates that an image mode is unknown.

Public constructors

ListBuilder

Added in 1.1.0-alpha02
@RequiresApi(value = 26)
public ListBuilder(
    @NonNull Context context,
    @NonNull Uri uri,
    @Nullable 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
@NonNull Uri uri

Uri to tag for this slice.

@Nullable Duration ttl

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

ListBuilder

Added in 1.1.0-alpha02
public ListBuilder(@NonNull Context context, @NonNull 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
@NonNull Uri uri

Uri to tag for this slice.

long ttl

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

Public methods

addAction

Added in 1.1.0-alpha02
public @NonNull ListBuilder addAction(@NonNull 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 androidx.slice.widget.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 MODE_LARGE or 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 setPrimaryAction.

addGridRow

Added in 1.1.0-alpha02
public @NonNull ListBuilder addGridRow(@NonNull 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 will result in IllegalStateException when the slice is built.

addInputRange

Added in 1.1.0-alpha02
public @NonNull ListBuilder addInputRange(@NonNull ListBuilder.InputRangeBuilder b)

Add an input range row to the list builder.

If setValue is not between setMin and setMax, this will throw IllegalArgumentException.

addRange

Added in 1.1.0-alpha02
public @NonNull ListBuilder addRange(@NonNull ListBuilder.RangeBuilder rangeBuilder)

Add a range row to the list builder.

If setValue is not between 0 and setMax, this will throw IllegalArgumentException.

addRating

Added in 1.1.0-alpha02
public @NonNull ListBuilder addRating(@NonNull ListBuilder.RatingBuilder b)

Add an star rating row to the list builder.

If setValue is not between setMin and setMax, this will show all stars as unselected.

addRow

Added in 1.1.0-alpha02
public @NonNull ListBuilder addRow(@NonNull ListBuilder.RowBuilder builder)

Add a row to the list builder.

addSelection

Added in 1.1.0-alpha02
public @NonNull ListBuilder addSelection(@NonNull SelectionBuilder selectionBuilder)

Add a selection row to the list builder.

build

public @NonNull 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.

setAccentColor

Added in 1.1.0-alpha02
public @NonNull ListBuilder setAccentColor(@ColorInt int color)

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

setHeader

Added in 1.1.0-alpha02
public @NonNull ListBuilder setHeader(@NonNull 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 MODE_SMALL and MODE_SHORTCUT.

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

In MODE_SHORTCUT, the primary action set using setPrimaryAction will be used for the shortcut representation.

See also
setSummary

setHostExtras

Added in 1.1.0-alpha02
@RequiresApi(value = 21)
public @NonNull ListBuilder setHostExtras(@NonNull PersistableBundle extras)

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

Parameters
@NonNull PersistableBundle extras

The Bundle of extras to add to this slice.

setIsError

Added in 1.1.0-alpha02
public @NonNull 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.

setKeywords

Added in 1.1.0-alpha02
public @NonNull ListBuilder setKeywords(@NonNull Set<String> keywords)

Sets keywords to associate with this slice.

setLayoutDirection

Added in 1.1.0-alpha02
public @NonNull ListBuilder setLayoutDirection(int layoutDirection)

Sets the desired layout direction for this slice.

Parameters
int layoutDirection

the layout direction to set.

setSeeMoreAction

Added in 1.1.0-alpha02
public @NonNull ListBuilder setSeeMoreAction(@NonNull 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.

setSeeMoreAction

Added in 1.1.0-alpha02
public @NonNull ListBuilder setSeeMoreAction(@NonNull 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.

setSeeMoreRow

Added in 1.1.0-alpha02
public @NonNull ListBuilder setSeeMoreRow(@NonNull 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 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 RowBuilder normally.

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