# SelectionTracker

Artifact: [androidx.recyclerview:recyclerview-selection](https://developer.android.com/jetpack/androidx/releases/recyclerview) [View Source](https://cs.android.com/search?q=file:androidx/recyclerview/selection/SelectionTracker.java+class:androidx.recyclerview.selection.SelectionTracker) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

*** ** * ** ***

<br />

```
abstract class SelectionTracker<K>
```

<br />

*** ** * ** ***

SelectionTracker provides support for managing a selection of items in a RecyclerView instance.

This class provides support for managing a "primary" set of selected items, in addition to a "provisional" set of selected items using conventional `https://developer.android.com/reference/java/util/Collections.html`-like methods.

Create an instance of SelectionTracker using `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.Builder`.

**Inspecting the current selection**

The underlying selection is described by the `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/Selection` class.

A live view of the current selection can be obtained using `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#getSelection()`. Changes made to the selection using SelectionTracker will be immediately reflected in this instance.

To obtain a stable snapshot of the selection use `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#copySelection(androidx.recyclerview.selection.MutableSelection<K>)`.

Selection state for an individual item can be obtained using `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#isSelected(K)`.

**Provisional Selection**

Provisional selection exists to address issues where a transitory selection might momentarily intersect with a previously established selection resulting in a some or all of the established selection being erased. Such situations may arise when band selection is being performed in "additive" mode (e.g. SHIFT or CTRL is pressed on the keyboard prior to mouse down), or when there's an active gesture selection (which can be initiated by long pressing an unselected item while there is an existing selection).

A provisional selection can be abandoned, or merged into the primary selection.

**Enforcing selection policies**

Which items can be selected by the user is a matter of policy in an Application. Developers supply these policies by way of `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.SelectionPredicate`.

| Parameters |
|---|---|
| `<K>` | Selection key type. @see `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/StorageStrategy` for supported types. |

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.Builder<K>` 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. |
| `abstract class https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.SelectionObserver<K>` Observer class providing access to information about Selection state changes. |
| `abstract class https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.SelectionPredicate<K>` Implement SelectionPredicate to control when items can be selected or unselected. |

| ### Constants |
|---|---|
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html!` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#SELECTION_CHANGED_MARKER() = "Selection-Changed"` This value is included in the payload when SelectionTracker notifies RecyclerView of changes to selection. |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#SelectionTracker()()` |

| ### Public functions |
|---|---|
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#addObserver(androidx.recyclerview.selection.SelectionTracker.SelectionObserver<K>)(observer: https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker.SelectionObserver<K!>)` Adds `observer` to be notified when changes to selection occur. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#clearSelection()()` Clears both primary and provisional selections. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#copySelection(androidx.recyclerview.selection.MutableSelection<K>)(dest: https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/MutableSelection<K!>)` Updates `dest` to reflect the current selection. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#deselect(K)(key: K)` Attempts to deselect an item. |
| `abstract https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/Selection<K!>` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#getSelection()()` Returns a Selection object that provides a live view on the current selection. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#hasSelection()()` |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#isSelected(K)(key: K?)` |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#onRestoreInstanceState(android.os.Bundle)(state: https://developer.android.com/reference/android/os/Bundle.html?)` Restores selection from previously saved state. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#onSaveInstanceState(android.os.Bundle)(state: https://developer.android.com/reference/android/os/Bundle.html)` Preserves selection, if any. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#select(K)(key: K)` Attempts to select an item. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#setItemsSelected(java.lang.Iterable<K>,boolean)(keys: (https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-mutable-iterable/index.html)https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-iterable/index.html<K!>, selected: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Sets the selected state of the specified items if permitted after consulting SelectionPredicate. |

| ### Protected functions |
|---|---|
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#restoreSelection(androidx.recyclerview.selection.Selection<K>)(selection: https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/Selection<K!>)` Restores the selected state of specified items. |

## Constants

### SELECTION_CHANGED_MARKER

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
const val SELECTION_CHANGED_MARKER = "Selection-Changed": String!
```

This value is included in the payload when SelectionTracker notifies RecyclerView of changes to selection. Look for this value in the `payload` Object argument supplied to `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.Adapter#onBindViewHolder(VH,int)`. If present the call is occurring in response to a selection state change. This would be a good opportunity to animate changes between unselected and selected state. When state is being restored, this argument will not be present.

## Public constructors

### SelectionTracker

Added in 1.0.0

```
SelectionTracker()
```

## Public functions

### addObserver

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.1.0)

```
abstract fun addObserver(observer: SelectionTracker.SelectionObserver<K!>): Unit
```

Adds `observer` to be notified when changes to selection occur.

Use an observer to track attributes about the selection and update the UI to reflect the state of the selection. For example, an author may use an observer to control the enabled status of menu items, or to initiate `https://developer.android.com/reference/android/view/ActionMode.html`.

### clearSelection

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun clearSelection(): Boolean
```

Clears both primary and provisional selections.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if primary selection changed. |

### copySelection

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun copySelection(dest: MutableSelection<K!>): Unit
```

Updates `dest` to reflect the current selection.

### deselect

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun deselect(key: K): Boolean
```

Attempts to deselect an item.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if the item was deselected. False if the item could not be deselected, or was was already un-selected. |

### getSelection

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun getSelection(): Selection<K!>
```

Returns a Selection object that provides a live view on the current selection.

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/Selection<K!>` | The current selection. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/SelectionTracker#copySelection(androidx.recyclerview.selection.MutableSelection<K>)` | on how to get a snapshot of the selection that will not reflect future changes to selection. |

### hasSelection

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun hasSelection(): Boolean
```

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if has a selection |

### isSelected

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun isSelected(key: K?): Boolean
```

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if the item specified by its id is selected. Shorthand for `getSelection().contains(K)`. |

### onRestoreInstanceState

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun onRestoreInstanceState(state: Bundle?): Unit
```

Restores selection from previously saved state. Call this method from Activity#onCreate.

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/android/os/Bundle.html?` | Bundle instance supplied to onCreate. |

### onSaveInstanceState

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun onSaveInstanceState(state: Bundle): Unit
```

Preserves selection, if any. Call this method from Activity#onSaveInstanceState

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/android/os/Bundle.html` | Bundle instance supplied to onSaveInstanceState. |

### select

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun select(key: K): Boolean
```

Attempts to select an item.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if the item was selected. False if the item could not be selected, or was was already selected. |

### setItemsSelected

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
abstract fun setItemsSelected(keys: (Mutable)Iterable<K!>, selected: Boolean): Boolean
```

Sets the selected state of the specified items if permitted after consulting SelectionPredicate.

## Protected functions

### restoreSelection

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
protected abstract fun restoreSelection(selection: Selection<K!>): Unit
```

Restores the selected state of specified items. Used in cases such as restore the selection after rotation etc. Provisional selection is not restored.

This affords clients the ability to restore selection from selection saved in Activity state.

| Parameters |
|---|---|
| `selection: https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/Selection<K!>` | selection being restored. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/selection/StorageStrategy` | details on selection state support. |