Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.
added in version 1.0.0
belongs to Maven artifact androidx.recyclerview:recyclerview-selection:1.1.0-alpha01

SelectionTracker.Builder

public static final class SelectionTracker.Builder
extends Object

java.lang.Object
   ↳ androidx.recyclerview.selection.SelectionTracker.Builder<K>


Builder is the primary mechanism for create a SelectionTracker that can be used with your RecyclerView. Once installed, users will be able to create and manipulate selection using a variety of intuitive techniques like tap, gesture, and mouse lasso.

Example usage:

SelectionTracker tracker = new SelectionTracker.Builder<>(
        "my-uri-selection",
        recyclerView,
        new DemoStableIdProvider(recyclerView.getAdapter()),
        new MyDetailsLookup(recyclerView),
        StorageStrategy.createParcelableStorage(Uri.class))
        .build();

Restricting which items can be selected and limiting selection size

SelectionTracker.SelectionPredicate provides a mechanism to restrict which Items can be selected, to limit the number of items that can be selected, as well as allowing the selection code to be placed into "single select" mode, which as the name indicates, constrains the selection size to a single item.

Configuring the tracker for single single selection support can be done by supplying SelectionPredicates.createSelectSingleAnything(). SelectionTracker tracker = new SelectionTracker.Builder<>( "my-string-selection", recyclerView, new DemoStableIdProvider(recyclerView.getAdapter()), new MyDetailsLookup(recyclerView), StorageStrategy.createStringStorage()) .withSelectionPredicate(SelectionPredicates#createSelectSingleAnything()) .build();

Retaining state across Android lifecycle events

Support for storage/persistence of selection must be configured and invoked manually owing to its reliance on Activity lifecycle events. Failure to include support for selection storage will result in the active selection being lost when the Activity receives a configuration change (e.g. rotation) or when the application process is destroyed by the OS to reclaim resources.

Key Type

Developers must decide on the key type used to identify selected items. Support is provided for three types: Parcelable, String, and Long.

Parcelable: Any Parcelable type can be used as the selection key. This is especially useful in conjunction with Uri as the Android URI implementation is both parcelable and makes for a natural stable selection key for values represented by the Android Content Provider framework. If items in your view are associated with stable content:// uris, you should use Uri for your key type.

String: Use String when a string based stable identifier is available.

Long: Use Long when RecyclerView's long stable ids are already in use. It comes with some limitations, however, as access to stable ids at runtime is limited. Band selection support is not available when using the default long key storage implementation. See StableIdKeyProvider for details.

Usage:

 private SelectionTracker mTracker;

 public void onCreate(Bundle savedInstanceState) {
   // See above for details on constructing a SelectionTracker instance.

   if (savedInstanceState != null) {
      mTracker.onRestoreInstanceState(savedInstanceState);
   }
 }

 protected void onSaveInstanceState(Bundle outState) {
     super.onSaveInstanceState(outState);
     mTracker.onSaveInstanceState(outState);
 }
 

Summary

Public constructors

SelectionTracker.Builder(String selectionId, RecyclerView recyclerView, ItemKeyProvider<K> keyProvider, ItemDetailsLookup<K> detailsLookup, StorageStrategy<K> storage)

Creates a new SelectionTracker.Builder useful for configuring and creating a new SelectionTracker for use with your RecyclerView.

Public methods

SelectionTracker<K> build()

Prepares and returns a SelectionTracker.

Builder<K> withBandOverlay(int bandOverlayId)

Replaces default band overlay.

Builder<K> withBandPredicate(BandPredicate bandPredicate)

Replaces default band predicate.

Builder<K> withFocusDelegate(FocusDelegate<K> delegate)

Add focus delegate to interact with selection related focus changes.

Builder<K> withGestureTooltypes(int... toolTypes)

Replaces default tap and gesture tool-types.

Builder<K> withOnContextClickListener(OnContextClickListener listener)

Adds a context click listener.

Builder<K> withOnDragInitiatedListener(OnDragInitiatedListener listener)

Adds a drag initiated listener.

Builder<K> withOnItemActivatedListener(OnItemActivatedListener<K> listener)

Adds an item activation listener.

Builder<K> withOperationMonitor(OperationMonitor monitor)

Add operation monitor allowing access to information about active operations (like band selection and gesture selection).

Builder<K> withPointerTooltypes(int... toolTypes)

Replaces default pointer tool-types.

Builder<K> withSelectionPredicate(SelectionPredicate<K> predicate)

Install selection predicate.

Inherited methods

Public constructors

SelectionTracker.Builder

added in version 1.0.0
public SelectionTracker.Builder (String selectionId, 
                RecyclerView recyclerView, 
                ItemKeyProvider<K> keyProvider, 
                ItemDetailsLookup<K> detailsLookup, 
                StorageStrategy<K> storage)

Creates a new SelectionTracker.Builder useful for configuring and creating a new SelectionTracker for use with your RecyclerView.

Parameters
selectionId String: A unique string identifying this selection in the context of the activity or fragment.

recyclerView RecyclerView: the owning RecyclerView

keyProvider ItemKeyProvider: the source of selection keys

detailsLookup ItemDetailsLookup: the source of information about RecyclerView items.

storage StorageStrategy: Strategy for type-safe storage of selection state in Bundle.

Public methods

build

added in version 1.0.0
public SelectionTracker<K> build ()

Prepares and returns a SelectionTracker.

Returns
SelectionTracker<K> this

withBandOverlay

added in version 1.0.0
public Builder<K> withBandOverlay (int bandOverlayId)

Replaces default band overlay.

Returns
Builder<K> this

withBandPredicate

added in version 1.0.0
public Builder<K> withBandPredicate (BandPredicate bandPredicate)

Replaces default band predicate.

Returns
Builder<K> this

withFocusDelegate

added in version 1.0.0
public Builder<K> withFocusDelegate (FocusDelegate<K> delegate)

Add focus delegate to interact with selection related focus changes.

Parameters
delegate FocusDelegate: the delegate to be used

Returns
Builder<K> this

withGestureTooltypes

added in version 1.0.0
public Builder<K> withGestureTooltypes (int... toolTypes)

Replaces default tap and gesture tool-types. Defaults are: MotionEvent.TOOL_TYPE_FINGER and MotionEvent.TOOL_TYPE_UNKNOWN.

Parameters
toolTypes int: the tool types to be used

Returns
Builder<K> this

withOnContextClickListener

added in version 1.0.0
public Builder<K> withOnContextClickListener (OnContextClickListener listener)

Adds a context click listener. Respond to right-click.

Parameters
listener OnContextClickListener: the listener to be used

Returns
Builder<K> this

withOnDragInitiatedListener

added in version 1.0.0
public Builder<K> withOnDragInitiatedListener (OnDragInitiatedListener listener)

Adds a drag initiated listener. Add support for drag and drop.

Parameters
listener OnDragInitiatedListener: the listener to be used

Returns
Builder<K> this

withOnItemActivatedListener

added in version 1.0.0
public Builder<K> withOnItemActivatedListener (OnItemActivatedListener<K> listener)

Adds an item activation listener. Respond to taps/enter/double-click on items.

Parameters
listener OnItemActivatedListener: the listener to be used

Returns
Builder<K> this

withOperationMonitor

added in version 1.0.0
public Builder<K> withOperationMonitor (OperationMonitor monitor)

Add operation monitor allowing access to information about active operations (like band selection and gesture selection).

Parameters
monitor OperationMonitor: the monitor to be used

Returns
Builder<K> this

withPointerTooltypes

added in version 1.0.0
public Builder<K> withPointerTooltypes (int... toolTypes)

Replaces default pointer tool-types. Pointer tools are associated with band selection, and certain drag and drop behaviors. Defaults are: MotionEvent.TOOL_TYPE_MOUSE.

Parameters
toolTypes int: the tool types to be used

Returns
Builder<K> this

withSelectionPredicate

added in version 1.0.0
public Builder<K> withSelectionPredicate (SelectionPredicate<K> predicate)

Install selection predicate.

Parameters
predicate SelectionPredicate: the predicate to be used.

Returns
Builder<K> this