androidx.recyclerview.selection

Kotlin |Java

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

ItemKeyProvider.Scope

Interfaces

`OnContextClickListener`	Register an OnContextClickListener to be notified when a context click occurs.
`OnDragInitiatedListener`	Register an OnDragInitiatedListener to be notified when user intent to perform drag and drop operations on an item or items has been detected.
`OnItemActivatedListener`	Register an OnItemActivatedListener to be notified when an item is activated (tapped or double clicked).
`OperationMonitor.OnChangeListener`	Listen to changes in operation status.

Classes

`BandPredicate`	Provides a means of controlling when and where band selection can be initiated.
`BandPredicate.EmptyArea`	A BandPredicate that allows initiation of band selection only in areas of RecyclerView that map to `NO_POSITION`.
`BandPredicate.NonDraggableArea`	A BandPredicate that allows initiation of band selection in any area that is not draggable as determined by consulting `inDragRegion`.
`FocusDelegate`	Override methods in this class to provide application specific behaviors related to focusing item.
`ItemDetailsLookup`	The Selection library calls `getItemDetails` when it needs access to information about the area and/or `ItemDetails` under a `MotionEvent`.
`ItemDetailsLookup.ItemDetails`	An ItemDetails implementation provides the selection library with access to information about a specific RecyclerView item.
`ItemKeyProvider`	Provides selection library access to stable selection keys identifying items presented by a `RecyclerView` instance.
`MutableSelection`	Subclass of `Selection` exposing public support for mutating the underlying selection data.
`OperationMonitor`	OperationMonitor provides a mechanism to coordinate application logic with ongoing user selection activities (such as active band selection and active gesture selection).
`Selection`	Object representing a "primary" selection and a "provisional" selection.
`SelectionPredicates`	Utility class for creating SelectionPredicate instances.
`SelectionTracker`	SelectionTracker provides support for managing a selection of items in a RecyclerView instance.
`SelectionTracker.Builder`	Builder is the primary mechanism for create a `SelectionTracker` that can be used with your RecyclerView.
`SelectionTracker.SelectionObserver`	Observer class providing access to information about Selection state changes.
`SelectionTracker.SelectionPredicate`	Implement SelectionPredicate to control when items can be selected or unselected.
`StableIdKeyProvider`	An `ItemKeyProvider` that provides stable ids by way of cached `RecyclerView.Adapter` stable ids.
`StorageStrategy`	Strategy for storing keys in saved state.