Summary: Nested Classes | Constants | Ctors | Methods | Protected Methods | Inherited Methods

SelectionTracker

Kotlin |Java

public abstract class SelectionTracker
extends Object

java.lang.Object
↳	androidx.recyclerview.selection.SelectionTracker<K>

---

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 Collections-like methods.

Create an instance of SelectionTracker using SelectionTracker.Builder.

Inspecting the current selection

The underlying selection is described by the Selection class.

A live view of the current selection can be obtained using getSelection(). Changes made to the selection using SelectionTracker will be immediately reflected in this instance.

To obtain a stable snapshot of the selection use copySelection(MutableSelection).

Selection state for an individual item can be obtained using isSelected(Object).

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 SelectionTracker.SelectionPredicate.

Summary

Nested classes
class	SelectionTracker.Builder<K> Builder is the primary mechanism for create a SelectionTracker that can be used with your RecyclerView.
class	SelectionTracker.SelectionObserver<K> Observer class providing access to information about Selection state changes.
class	SelectionTracker.SelectionPredicate<K> Implement SelectionPredicate to control when items can be selected or unselected.

Constants
String	SELECTION_CHANGED_MARKER This value is included in the payload when SelectionTracker notifies RecyclerView of changes to selection.

Public constructors
SelectionTracker()

Public methods
abstract void	addObserver(SelectionObserver<K> observer) Adds observer to be notified when changes to selection occur.
abstract boolean	clearSelection() Clears both primary and provisional selections.
abstract void	copySelection(MutableSelection<K> dest) Updates dest to reflect the current selection.
abstract boolean	deselect(K key) Attempts to deselect an item.
abstract Selection<K>	getSelection() Returns a Selection object that provides a live view on the current selection.
abstract boolean	hasSelection()
abstract boolean	isSelected(K key)
abstract void	onRestoreInstanceState(Bundle state) Restores selection from previously saved state.
abstract void	onSaveInstanceState(Bundle state) Preserves selection, if any.
abstract boolean	select(K key) Attempts to select an item.
abstract boolean	setItemsSelected(Iterable<K> keys, boolean selected) Sets the selected state of the specified items if permitted after consulting SelectionPredicate.

Protected methods
abstract void	restoreSelection(Selection<K> selection) Restores the selected state of specified items.

Inherited methods
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class<?> getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait(long arg0, int arg1) final void wait(long arg0) final void wait()

Constants

SELECTION_CHANGED_MARKER

public static final String SELECTION_CHANGED_MARKER

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 Adapter#onBindViewHolder. 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.

Constant Value: "Selection-Changed"

Public constructors

SelectionTracker

public SelectionTracker ()

Public methods

addObserver

public abstract void addObserver (SelectionObserver<K> observer)

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 ActionMode.

Parameters
observer	SelectionObserver

clearSelection

public abstract boolean clearSelection ()

Clears both primary and provisional selections.

Returns
boolean	true if primary selection changed.

copySelection

public abstract void copySelection (MutableSelection<K> dest)

Updates dest to reflect the current selection.

Parameters
dest	MutableSelection

deselect

public abstract boolean deselect (K key)

Attempts to deselect an item.

Parameters
key	K

Returns
boolean	true if the item was deselected. False if the item could not be deselected, or was was already un-selected.

getSelection

public abstract Selection<K> getSelection ()

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

Returns
Selection<K>	The current selection.

See also:

• on how to get a snapshot of the selection that will not reflect future changes to selection.

hasSelection

public abstract boolean hasSelection ()

Returns
boolean	true if has a selection

isSelected

public abstract boolean isSelected (K key)

Parameters
key	K

Returns
boolean	true if the item specified by its id is selected. Shorthand for getSelection().contains(K).

onRestoreInstanceState

public abstract void onRestoreInstanceState (Bundle state)

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

Parameters
state	Bundle: Bundle instance supplied to onCreate.

onSaveInstanceState

public abstract void onSaveInstanceState (Bundle state)

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

Parameters
state	Bundle: Bundle instance supplied to onSaveInstanceState.

select

public abstract boolean select (K key)

Attempts to select an item.

Parameters
key	K

Returns
boolean	true if the item was selected. False if the item could not be selected, or was was already selected.

setItemsSelected

public abstract boolean setItemsSelected (Iterable<K> keys, 
                boolean selected)

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

Parameters
keys	Iterable
selected	boolean

Returns
boolean

Protected methods

restoreSelection

protected abstract void restoreSelection (Selection<K> selection)

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	Selection: selection being restored.

See also:

• details on selection state support.