---

A RecyclerView addon library providing support for item selection. The library provides support for both touch and mouse driven selection. Developers retain control over the visual representation, and the policies controlling selection behavior (like which items are eligible for selection, and how many items can be selected.)

Want to add selection support to your RecyclerView? Here's how you do it:

Determine which selection key type to use, then build your KeyProvider

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

See SelectionTracker.Builder for more detailed advice on which key type to use for your selection keys.

Implement ItemDetailsLookup

This class provides the selection library code necessary access to information about items associated with android.view.MotionEvent. This will likely depend on concrete RecyclerView.ViewHolder type employed by your application.

Update views used in RecyclerView to reflect selected state

When the user selects an item the library will record that in SelectionTracker then notify RecyclerView that the state of the item has changed. This will ultimately cause the value to be rebound by way of RecyclerView.Adapter#onBindViewHolder. The item must then be updated to reflect the new selection status. Without this the user will not *see* that the item has been selected.

• In Adapter#onBindViewHolder, set the "activated" status on view. Note that the status should be "activated" not "selected". See View.html#setActivated for details.
• Update the styling of the view to represent the activated status. This can be done with a color state list.

Use ActionMode when there is a selection

Register a androidx.recyclerview.selection.SelectionTracker.SelectionObserver to be notified when selection changes. When a selection is first created, start ActionMode to represent this to the user, and provide selection specific actions.

Interpreted secondary actions: Drag and Drop, and Item Activation

At the end of the event processing pipeline the library may determine that the user is attempting to activate an item by tapping it, or is attempting to drag and drop an item or set of selected items. React to these interpretations by registering a respective listener. See SelectionTracker.Builder for details.

Assemble everything with SelectionTracker.Builder

Example usage (with Long selection keys):

SelectionTrackertracker = new SelectionTracker.Builder<>(
       "my-selection-id",
       recyclerView,
       new StableIdKeyProvider(recyclerView),
       new MyDetailsLookup(recyclerView),
       StorageStrategy.createLongStorage())
       .build();

In order to build a SelectionTracker instance the supplied RecyclerView must be initialized with an Adapter. Given this fact, you will probably need to inject the SelectionTracker instance into your RecyclerView.Adapter after the Adapter is created, as it will be necessary to consult selected status using SelectionTracker from the onBindViewHolder method.

Include Selection in Activity lifecycle events

In order to preserve state, the author must include the selection library in the handling of Activity lifecycle events. See SelectionTracker#onSaveInstanceState and SelectionTracker#onRestoreInstanceState.

A unique selection id must be supplied to SelectionTracker.Builder constructor. This is necessary as an activity or fragment may have multiple distinct selectable lists that may both need to be persisted in saved state.

Annotations

Interfaces

Classes