SelectionTracker.Builder
public
static
final
class
SelectionTracker.Builder
extends Object
java.lang.Object | |
↳ | androidx.recyclerview.selection.SelectionTracker.Builder<K> |
Builder is the primary mechanism for create a SelectionTracker
that
can be used with your RecyclerView. Once installed, users will be able to create and
manipulate selection using a variety of intuitive techniques like tap, gesture,
and mouse lasso.
Example usage:
SelectionTrackertracker = new SelectionTracker.Builder<>( "my-uri-selection", recyclerView, new DemoStableIdProvider(recyclerView.getAdapter()), new MyDetailsLookup(recyclerView), StorageStrategy.createParcelableStorage(Uri.class)) .build();
Restricting which items can be selected and limiting selection size
SelectionTracker.SelectionPredicate
provides a mechanism to restrict which Items can be selected,
to limit the number of items that can be selected, as well as allowing the selection
code to be placed into "single select" mode, which as the name indicates, constrains
the selection size to a single item.
Configuring the tracker for single single selection support can be done
by supplying
Retaining state across Android lifecycle events
Support for storage/persistence of selection must be configured and invoked manually
owing to its reliance on Activity lifecycle events.
Failure to include support for selection storage will result in the active selection
being lost when the Activity receives a configuration change (e.g. rotation)
or when the application process is destroyed by the OS to reclaim resources.
Key Type
Developers must decide on the key type used to identify selected items. Support
is provided for three types:
Usage:
SelectionPredicates.createSelectSingleAnything()
.
SelectionTrackerParcelable
, String
, and Long
.
Parcelable
: Any Parcelable type can be used as the selection key. This is especially
useful in conjunction with Uri
as the Android URI implementation is both
parcelable and makes for a natural stable selection key for values represented by
the Android Content Provider framework. If items in your view are associated with
stable content://
uris, you should use Uri for your key type.
String
: Use String when a string based stable identifier is available.
Long
: Use Long when RecyclerView's long stable ids are
already in use. It comes with some limitations, however, as access to stable ids
at runtime is limited. Band selection support is not available when using the default
long key storage implementation. See StableIdKeyProvider
for details.
private SelectionTracker
Summary
Public constructors | |
---|---|
Builder(String selectionId, RecyclerView recyclerView, ItemKeyProvider<K> keyProvider, ItemDetailsLookup<K> detailsLookup, StorageStrategy<K> storage)
Creates a new SelectionTracker.Builder useful for configuring and creating
a new SelectionTracker for use with your |
Public methods | |
---|---|
SelectionTracker<K>
|
build()
Prepares and returns a SelectionTracker. |
Builder<K>
|
withBandOverlay(int bandOverlayId)
Replaces default band overlay. |
Builder<K>
|
withBandPredicate(BandPredicate bandPredicate)
Replaces default band predicate. |
Builder<K>
|
withFocusDelegate(FocusDelegate<K> delegate)
Add focus delegate to interact with selection related focus changes. |
Builder<K>
|
withGestureTooltypes(int... toolTypes)
This method is deprecated.
GestureSelection is best bound to |
Builder<K>
|
withOnContextClickListener(OnContextClickListener listener)
Adds a context click listener. |
Builder<K>
|
withOnDragInitiatedListener(OnDragInitiatedListener listener)
Adds a drag initiated listener. |
Builder<K>
|
withOnItemActivatedListener(OnItemActivatedListener<K> listener)
Adds an item activation listener. |
Builder<K>
|
withOperationMonitor(OperationMonitor monitor)
Add operation monitor allowing access to information about active operations (like band selection and gesture selection). |
Builder<K>
|
withPointerTooltypes(int... toolTypes)
This method is deprecated.
PointerSelection is best bound to |
Builder<K>
|
withSelectionPredicate(SelectionPredicate<K> predicate)
Install selection predicate. |
Inherited methods | |
---|---|
Public constructors
Builder
public Builder (String selectionId, RecyclerView recyclerView, ItemKeyProvider<K> keyProvider, ItemDetailsLookup<K> detailsLookup, StorageStrategy<K> storage)
Creates a new SelectionTracker.Builder useful for configuring and creating
a new SelectionTracker for use with your RecyclerView
.
Parameters | |
---|---|
selectionId |
String : A unique string identifying this selection in the context
of the activity or fragment. |
recyclerView |
RecyclerView : the owning RecyclerView |
keyProvider |
ItemKeyProvider : the source of selection keys |
detailsLookup |
ItemDetailsLookup : the source of information about RecyclerView items. |
storage |
StorageStrategy : Strategy for type-safe storage of selection state in
Bundle .
|
Public methods
build
public SelectionTracker<K> build ()
Prepares and returns a SelectionTracker.
Returns | |
---|---|
SelectionTracker<K> |
this |
withBandOverlay
public Builder<K> withBandOverlay (int bandOverlayId)
Replaces default band overlay.
Parameters | |
---|---|
bandOverlayId |
int |
Returns | |
---|---|
Builder<K> |
this |
withBandPredicate
public Builder<K> withBandPredicate (BandPredicate bandPredicate)
Replaces default band predicate.
Parameters | |
---|---|
bandPredicate |
BandPredicate |
Returns | |
---|---|
Builder<K> |
this |
withFocusDelegate
public Builder<K> withFocusDelegate (FocusDelegate<K> delegate)
Add focus delegate to interact with selection related focus changes.
Parameters | |
---|---|
delegate |
FocusDelegate : the delegate to be used |
Returns | |
---|---|
Builder<K> |
this |
withGestureTooltypes
public Builder<K> withGestureTooltypes (int... toolTypes)
This method is deprecated.
GestureSelection is best bound to MotionEvent.TOOL_TYPE_FINGER
,
and only that tool type. This method will be removed in a future release.
Replaces default tap and gesture tool-types. Defaults are:
MotionEvent.TOOL_TYPE_FINGER
.
Parameters | |
---|---|
toolTypes |
int : the tool types to be used |
Returns | |
---|---|
Builder<K> |
this |
withOnContextClickListener
public Builder<K> withOnContextClickListener (OnContextClickListener listener)
Adds a context click listener. Respond to right-click.
Parameters | |
---|---|
listener |
OnContextClickListener : the listener to be used |
Returns | |
---|---|
Builder<K> |
this |
withOnDragInitiatedListener
public Builder<K> withOnDragInitiatedListener (OnDragInitiatedListener listener)
Adds a drag initiated listener. Add support for drag and drop.
Parameters | |
---|---|
listener |
OnDragInitiatedListener : the listener to be used |
Returns | |
---|---|
Builder<K> |
this |
withOnItemActivatedListener
public Builder<K> withOnItemActivatedListener (OnItemActivatedListener<K> listener)
Adds an item activation listener. Respond to taps/enter/double-click on items.
Parameters | |
---|---|
listener |
OnItemActivatedListener : the listener to be used |
Returns | |
---|---|
Builder<K> |
this |
withOperationMonitor
public Builder<K> withOperationMonitor (OperationMonitor monitor)
Add operation monitor allowing access to information about active operations (like band selection and gesture selection).
Parameters | |
---|---|
monitor |
OperationMonitor : the monitor to be used |
Returns | |
---|---|
Builder<K> |
this |
withPointerTooltypes
public Builder<K> withPointerTooltypes (int... toolTypes)
This method is deprecated.
PointerSelection is best bound to MotionEvent.TOOL_TYPE_MOUSE
,
and only that tool type. This method will be removed in a future release.
Replaces default pointer tool-types. Pointer tools
are associated with band selection, and certain
drag and drop behaviors. Defaults are:
MotionEvent.TOOL_TYPE_MOUSE
.
Parameters | |
---|---|
toolTypes |
int : the tool types to be used |
Returns | |
---|---|
Builder<K> |
this |
withSelectionPredicate
public Builder<K> withSelectionPredicate (SelectionPredicate<K> predicate)
Install selection predicate.
Parameters | |
---|---|
predicate |
SelectionPredicate : the predicate to be used. |
Returns | |
---|---|
Builder<K> |
this |