SelectionTracker
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 |
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 |
abstract
boolean
|
clearSelection()
Clears both primary and provisional selections. |
abstract
void
|
copySelection(MutableSelection<K> dest)
Updates |
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 | |
---|---|
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. |
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:
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.