SectionedItemTemplate.Builder

public final class SectionedItemTemplate.Builder

A builder that constructs SectionedItemTemplate instances.

Upon building, this class validates the following:

Summary

Public constructors

Create a new SectionedItemTemplate builder.

Create a new SectionedItemTemplate builder, copying the values from an existing instance.

Public methods
@NonNull SectionedItemTemplate.Builder

Adds a single Action to this template, appending to the existing list of actions.
@NonNull SectionedItemTemplate.Builder

Adds a single Section to this template, appending to the existing list of sections.
@NonNull SectionedItemTemplate

Constructs a new SectionedItemTemplate from the current state of this builder, throwing exceptions for any invalid state.
@NonNull SectionedItemTemplate.Builder

Removes all actions in this template.
@NonNull SectionedItemTemplate.Builder

Removes all sections from this template.
@NonNull SectionedItemTemplate.Builder

Sets the actions that show up alongside the sections of this template (as opposed to the actions in the header), overwriting any other previously set actions from addAction or setActions.
@NonNull SectionedItemTemplate.Builder
@CanIgnoreReturnValue
setAlphabeticalIndexingAllowed(boolean alphabeticalIndexingAllowed)

This method is deprecated.

use setAlphabeticalIndexingStrategy instead.
@NonNull SectionedItemTemplate.Builder
@CanIgnoreReturnValue
setAlphabeticalIndexingStrategy(int alphabeticalIndexingStrategy)

Sets how this list can be indexed alphabetically.
@NonNull SectionedItemTemplate.Builder

Sets or clears the optional header for this template.
@NonNull SectionedItemTemplate.Builder
@CanIgnoreReturnValue
setLoading(boolean isLoading)

Sets whether or not this template is in a loading state.
@NonNull SectionedItemTemplate.Builder
@CanIgnoreReturnValue
setScrollStatePersistenceStrategy(int scrollStatePersistenceStrategy)

Set how to handle a user's scroll position when this template is used as a refresh of another SectionedItemTemplate.
@NonNull SectionedItemTemplate.Builder

Sets or clears a search header on this template, enabling search input mode.
@NonNull SectionedItemTemplate.Builder

Sets the sections in this template, overwriting any other previously set sections.

Public constructors

Builder

Added in 1.7.0
public Builder()

Create a new SectionedItemTemplate builder.

Builder

Added in 1.7.0
public Builder(@NonNull SectionedItemTemplate template)

Create a new SectionedItemTemplate builder, copying the values from an existing instance.

Public methods

addAction

Added in 1.7.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder addAction(@NonNull Action action)

Adds a single Action to this template, appending to the existing list of actions. All actions must conform to the ACTIONS_CONSTRAINTS_FAB constraints.

Note: Starting in Car API 9, for media apps (apps with MEDIA_TEMPLATES), a maximum of 1 action can be set, as the host reserves space to render a persistent media entry point or miniplayer. If extra actions are sent by a media app, the host will drop the extra action.

addSection

Added in 1.7.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder addSection(@NonNull Section<@NonNull ?> section)

Adds a single Section to this template, appending to the existing list of sections. Only sections listed in Builder can be added.

See also
SectionedItemTemplate.Builder

for a list of allowed section types

build

Added in 1.7.0
public @NonNull SectionedItemTemplate build()

Constructs a new SectionedItemTemplate from the current state of this builder, throwing exceptions for any invalid state.

See also
SectionedItemTemplate.Builder

for the list of validation logic

clearActions

Added in 1.7.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder clearActions()

Removes all actions in this template.

clearSections

Added in 1.7.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder clearSections()

Removes all sections from this template.

setActions

Added in 1.7.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setActions(@NonNull List<Action> actions)

Sets the actions that show up alongside the sections of this template (as opposed to the actions in the header), overwriting any other previously set actions from addAction or setActions. All actions must conform to the ACTIONS_CONSTRAINTS_FAB constraints.

Note: Starting in Car API 9, for media apps (apps with MEDIA_TEMPLATES), a maximum of 1 action can be set, as the host reserves space to render a persistent media entry point or miniplayer. If extra actions are sent by a media app, the host will drop the extra action.

setAlphabeticalIndexingAllowed

Added in 1.7.0
Deprecated in 1.8.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setAlphabeticalIndexingAllowed(boolean alphabeticalIndexingAllowed)

Sets whether this list can be indexed alphabetically, by item title. By default, this is false.

"Indexing" refers to the process of examining list contents (e.g. item titles) to sort, partition, or filter a list. Indexing is generally used for features called "Accelerators", which allow a user to quickly find a particular Item in a long list.

For example, a media app may, by default, show a user's playlists sorted by date created. If the app provides these playlists via the SectionedItemTemplate and enables isAlphabeticalIndexingAllowed, the user will be able to jump to their playlists that start with the letter "H". When this happens, the list is reconstructed and sorted alphabetically, then shown to the user, jumping down to the letter "H".

Individual items may be excluded from the list by setting their #isIndexable field to false.

setAlphabeticalIndexingStrategy

Added in 1.8.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setAlphabeticalIndexingStrategy(int alphabeticalIndexingStrategy)

Sets how this list can be indexed alphabetically. By default, this is ALPHABETICAL_INDEXING_DISABLED.

"Indexing" refers to the process of examining list contents (e.g. item titles) to sort, partition, or filter a list. Indexing is generally used for features called "Accelerators", which allow a user to quickly find a particular Item in a long list.

For example, a media app may, by default, provide a user's playlists sorted by date created in addSection. If setAlphabeticalIndexingStrategy is set to a non-disabled value, the user will be able to jump to their playlists that start with the letter "H". When this happens, the list is reconstructed and sorted alphabetically, then shown to the user, jumping down to the letter "H".

Individual items may be excluded from the reconstructed list by setting their #isIndexable field to false.

setHeader

Added in 1.7.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setHeader(@Nullable Header header)

Sets or clears the optional header for this template.

Note that only one of Header or SearchHeader can be set on this template at the same time. Otherwise, an exception will be thrown on build invocation.

setLoading

Added in 1.7.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setLoading(boolean isLoading)

Sets whether or not this template is in a loading state. If passed true, sections cannot be added to the template. By default, this is false.

setScrollStatePersistenceStrategy

Added in 1.8.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setScrollStatePersistenceStrategy(int scrollStatePersistenceStrategy)

Set how to handle a user's scroll position when this template is used as a refresh of another SectionedItemTemplate.

For example, if a user is currently scrolled down to item 10 in an existing SectionedItemTemplate, setting this field to SCROLL_STATE_PRESERVE_INDEX would cause the user to be shown item 10 from this template. Alternatively, SCROLL_STATE_RESET_TO_TOP would cause the user to be reset to the top of this template.

By default, this is set to SCROLL_STATE_RESET_TO_TOP.

setSearchHeader

Added in 1.9.0-alpha02
@ExperimentalCarApi
@RequiresCarApi(value = 9)
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setSearchHeader(@Nullable SearchHeader searchHeader)

Sets or clears a search header on this template, enabling search input mode.

Note that only one of Header or SearchHeader can be set on this template at the same time. Otherwise, an exception will be thrown on build invocation.

setSections

Added in 1.7.0
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setSections(@NonNull List<Section<@NonNull ?>> sections)

Sets the sections in this template, overwriting any other previously set sections. Only sections listed in Builder can be added.

See also
SectionedItemTemplate.Builder

for a list of allowed section types