Save the date! Android Dev Summit is coming to Sunnyvale, CA on Oct 23-24, 2019.

SelectionTracker

abstract class SelectionTracker<K : Any!>
kotlin.Any
   ↳ androidx.recyclerview.selection.SelectionTracker

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 java.util.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 SelectionPredicate.

Summary

Nested classes
abstract

Observer class providing access to information about Selection state changes.

abstract

Implement SelectionPredicate to control when items can be selected or unselected.

Builder is the primary mechanism for create a SelectionTracker that can be used with your RecyclerView.

Constants
static String

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

Public constructors

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

Public methods
abstract Boolean

abstract Unit
copySelection(@NonNull dest: MutableSelection<K>)

Updates dest to reflect the current selection.

abstract Boolean

Clears both primary and provisional selections.

abstract Unit
onSaveInstanceState(@NonNull state: Bundle)

Preserves selection, if any.

abstract Boolean
isSelected(@Nullable key: K?)

abstract Boolean
deselect(@NonNull key: K)

Attempts to deselect an item.

abstract Unit
onRestoreInstanceState(@Nullable state: Bundle?)

Restores selection from previously saved state.

abstract Unit

Adds observer to be notified when changes to selection occur.

abstract Boolean
select(@NonNull key: K)

Attempts to select an item.

abstract Boolean
setItemsSelected(@NonNull keys: MutableIterable<K>, selected: Boolean)

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

abstract Selection<K>!

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

Protected methods
abstract Unit
restoreSelection(@NonNull selection: Selection<K>)

Restores the selected state of specified items.

Constants

SELECTION_CHANGED_MARKER

static val SELECTION_CHANGED_MARKER: 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 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.

Value: "Selection-Changed"

Public constructors

<init>

SelectionTracker()

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 java.util.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 SelectionPredicate.

Public methods

hasSelection

abstract fun hasSelection(): Boolean
Return
Boolean: true if has a selection

copySelection

abstract fun copySelection(@NonNull dest: MutableSelection<K>): Unit

Updates dest to reflect the current selection.

clearSelection

abstract fun clearSelection(): Boolean

Clears both primary and provisional selections.

Return
Boolean: true if primary selection changed.

onSaveInstanceState

abstract fun onSaveInstanceState(@NonNull state: Bundle): Unit

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

Parameters
state Bundle: Bundle instance supplied to onSaveInstanceState.

isSelected

abstract fun isSelected(@Nullable key: K?): Boolean
Return
Boolean: true if the item specified by its id is selected. Shorthand for getSelection().contains(K).

deselect

abstract fun deselect(@NonNull key: K): Boolean

Attempts to deselect an item.

Return
Boolean: true if the item was deselected. False if the item could not be deselected, or was was already un-selected.

onRestoreInstanceState

abstract fun onRestoreInstanceState(@Nullable state: Bundle?): Unit

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

Parameters
state Bundle?: Bundle instance supplied to onCreate.

addObserver

abstract fun addObserver(observer: SelectionTracker.SelectionObserver<Any!>!): 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 android.view.ActionMode.

select

abstract fun select(@NonNull key: K): Boolean

Attempts to select an item.

Return
Boolean: true if the item was selected. False if the item could not be selected, or was was already selected.

setItemsSelected

abstract fun setItemsSelected(@NonNull keys: MutableIterable<K>, selected: Boolean): Boolean

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

getSelection

abstract fun getSelection(): Selection<K>!

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

Return
Selection<K>!: The current selection.

Protected methods

restoreSelection

protected abstract fun restoreSelection(@NonNull 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 Selection<K>: selection being restored.

See Also