Overview

Builder is the primary mechanism for creating a SelectionTracker that can be used with your RecyclerView. Once installed, users will be able to create and manipulate a selection of items in a RecyclerView instance using a variety of intuitive techniques like tap, gesture, and mouse-based band selection (aka 'lasso').

Building a bare-bones instance:

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

Restricting which items can be selected and limiting selection size

SelectionTracker.SelectionPredicate and SelectionTracker.Builder together provide a mechanism for restricting which items can be selected and limiting selection size. Use SelectionPredicates.createSelectSingleAnything() for single-selection, or write your own SelectionTracker.SelectionPredicate if other constraints are required. SelectionTracker tracker = new SelectionTracker.Builder<>( "my-string-selection", recyclerView, new YourItemKeyProvider(recyclerView.getAdapter()), new YourItemDetailsLookup(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 selection being lost when the Activity receives a configuration change (e.g. rotation), or when the application is paused or stopped. For this reason StorageStrategy is a required argument to obtain a SelectionTracker.Builder instance.

Key Type

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

Parcelable: Any Parcelable type can be used as the selection key. This is especially useful in conjunction with 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.

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

java.lang.Long: Use Long when a project is already employing RecyclerView's built-in support for stable ids. In this case you may choose to use StableIdKeyProvider to supply selection keys to the SelectionTracker based on data already accessible in RecyclerView and it's Adapter. See StableIdKeyProvider for important details and limitations (and a suggestion that you might just want to write your own ItemKeyProvider. It's easy!) See the "Gotchas" selection below for details on selection size limits.

Usage:

 private SelectionTracker mTracker;

 public void onCreate(Bundle savedInstanceState) {
 if (savedInstanceState != null) {
 mTracker.onRestoreInstanceState(savedInstanceState);
 }
 }

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

Summary

Constructors

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

Parameters:

selectionId: A unique string identifying this selection in the context of the activity or fragment.
recyclerView: the owning RecyclerView
keyProvider: the source of selection keys
detailsLookup: the source of information about RecyclerView items.
storage: Strategy for type-safe storage of selection state in .

Methods

Install selection predicate.

Parameters:

predicate: the predicate to be used.

Returns:

this

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

Parameters:

monitor: the monitor to be used

Returns:

this

Add focus delegate to interact with selection related focus changes.

Parameters:

delegate: the delegate to be used

Returns:

this

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

Parameters:

listener: the listener to be used

Returns:

this

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

Parameters:

listener: the listener to be used

Returns:

this

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

Parameters:

listener: the listener to be used

Returns:

this

Deprecated: GestureSelection is best bound to MotionEvent, and only that tool type. This method will be removed in a future release.

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

Parameters:

toolTypes: the tool types to be used

Returns:

this

Replaces default band overlay.

Returns:

this

Replaces default band predicate.

Returns:

this

Deprecated: PointerSelection is best bound to MotionEvent, and only that tool type. This method will be removed in a future release.

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

Parameters:

toolTypes: the tool types to be used

Returns:

this

Prepares and returns a SelectionTracker.

Returns:

this