# androidx.recyclerview.selection

*** ** * ** ***

A `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/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: `https://developer.android.com/reference/android/os/Parcelable.html`, `https://developer.android.com/reference/java/lang/String.html`, and `https://developer.android.com/reference/java/lang/Long.html`.

See `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.Builder` for more detailed advice on which key type to use for your selection keys.

**Implement `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/ItemDetailsLookup`**

This class provides the selection library code necessary access to information about items associated with `https://developer.android.com/reference/android/view/MotionEvent.html`. This will likely depend on concrete `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/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 `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker` then notify RecyclerView that the state of the item has changed. This will ultimately cause the value to be rebound by way of `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.Adapter#onBindViewHolder(VH,int)`. 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](https://developer.android.com/reference/android/view/View.html#setActivated(boolean)) for details.
- Update the styling of the view to represent the activated status. This can be done with a [color state list](https://developer.android.com/guide/topics/resources/color-list-resource.html).

**Use `https://developer.android.com/reference/kotlin/androidx/appcompat/view/ActionMode` when there is a selection**

Register a `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.SelectionObserver` to be notified when selection changes. When a selection is first created, start `https://developer.android.com/reference/kotlin/androidx/appcompat/view/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 `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.Builder` for details.

**Assemble everything with `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.Builder`**

Example usage (with `Long` selection keys):

```kotlin
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 `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/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.

## Interfaces

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/OnContextClickListener` | Register an OnContextClickListener to be notified when a context click occurs. |
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/OnDragInitiatedListener` | Register an OnDragInitiatedListener to be notified when user intent to perform drag and drop operations on an item or items has been detected. |
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/OnItemActivatedListener` | Register an OnItemActivatedListener to be notified when an item is activated (tapped or double clicked). |
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/OperationMonitor.OnChangeListener` | Listen to changes in operation status. |

## Classes

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

## Annotations

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/ItemKeyProvider.Scope` |   |