Builder
class Builder<K : Any!>
kotlin.Any | |
↳ | androidx.recyclerview.selection.SelectionTracker.Builder |
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:
SelectionTracker<uri> tracker = new SelectionTracker.Builder<>( "my-uri-selection", recyclerView, new DemoStableIdProvider(recyclerView.getAdapter()), new MyDetailsLookup(recyclerView), StorageStrategy.createParcelableStorage(Uri.class)) .build(); </uri>
Restricting which items can be selected and limiting selection size
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 SelectionPredicates#createSelectSingleAnything()
. SelectionTracker tracker = new SelectionTracker.Builder<>( "my-string-selection", recyclerView, new DemoStableIdProvider(recyclerView.getAdapter()), new MyDetailsLookup(recyclerView), StorageStrategy.createStringStorage()) .withSelectionPredicate(SelectionPredicates#createSelectSingleAnything()) .build();
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: Parcelable
, String
, and Long
.
Parcelable
: Any Parcelable type can be used as the selection key. This is especially useful in conjunction with android.net.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.
Usage:
private SelectionTracker<uri> mTracker; public void onCreate(Bundle savedInstanceState) { // See above for details on constructing a SelectionTracker instance. if (savedInstanceState != null) { mTracker.onRestoreInstanceState(savedInstanceState); } } protected void onSaveInstanceState(Bundle outState) { super.onSaveInstanceState(outState); mTracker.onSaveInstanceState(outState); } </uri>
Summary
Public constructors | |
---|---|
<init>(@NonNull selectionId: String, @NonNull recyclerView: RecyclerView, @NonNull keyProvider: ItemKeyProvider<K>, @NonNull detailsLookup: ItemDetailsLookup<K>, @NonNull storage: StorageStrategy<K>) Creates a new SelectionTracker. |
Public methods | |
---|---|
SelectionTracker<K> |
build() Prepares and returns a SelectionTracker. |
SelectionTracker.Builder<K> |
withBandOverlay(@DrawableRes bandOverlayId: Int) Replaces default band overlay. |
SelectionTracker.Builder<K> |
withBandPredicate(@NonNull bandPredicate: BandPredicate) Replaces default band predicate. |
SelectionTracker.Builder<K> |
withFocusDelegate(@NonNull delegate: FocusDelegate<K>) Add focus delegate to interact with selection related focus changes. |
SelectionTracker.Builder<K> |
withGestureTooltypes(@NonNull vararg toolTypes: Int) Replaces default tap and gesture tool-types. |
SelectionTracker.Builder<K> |
withOnContextClickListener(@NonNull listener: OnContextClickListener) Adds a context click listener. |
SelectionTracker.Builder<K> |
withOnDragInitiatedListener(@NonNull listener: OnDragInitiatedListener) Adds a drag initiated listener. |
SelectionTracker.Builder<K> |
withOnItemActivatedListener(@NonNull listener: OnItemActivatedListener<K>) Adds an item activation listener. |
SelectionTracker.Builder<K> |
withOperationMonitor(@NonNull monitor: OperationMonitor) Add operation monitor allowing access to information about active operations (like band selection and gesture selection). |
SelectionTracker.Builder<K> |
withPointerTooltypes(@NonNull vararg toolTypes: Int) Replaces default pointer tool-types. |
SelectionTracker.Builder<K> |
withSelectionPredicate(@NonNull predicate: SelectionTracker.SelectionPredicate<K>) Install selection predicate. |
Public constructors
<init>
Builder(
@NonNull selectionId: String,
@NonNull recyclerView: RecyclerView,
@NonNull keyProvider: ItemKeyProvider<K>,
@NonNull detailsLookup: ItemDetailsLookup<K>,
@NonNull storage: StorageStrategy<K>)
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<K>: the source of selection keys |
detailsLookup |
ItemDetailsLookup<K>: the source of information about RecyclerView items. |
storage |
StorageStrategy<K>: Strategy for type-safe storage of selection state in Bundle . |
Public methods
build
@NonNull fun build(): SelectionTracker<K>
Prepares and returns a SelectionTracker.
Return | |
---|---|
SelectionTracker<K> |
this |
withBandOverlay
@NonNull fun withBandOverlay(@DrawableRes bandOverlayId: Int): SelectionTracker.Builder<K>
Replaces default band overlay.
Return | |
---|---|
SelectionTracker.Builder<K> |
this |
withBandPredicate
@NonNull fun withBandPredicate(@NonNull bandPredicate: BandPredicate): SelectionTracker.Builder<K>
Replaces default band predicate.
Return | |
---|---|
SelectionTracker.Builder<K> |
this |
withFocusDelegate
@NonNull fun withFocusDelegate(@NonNull delegate: FocusDelegate<K>): SelectionTracker.Builder<K>
Add focus delegate to interact with selection related focus changes.
Parameters | |
---|---|
delegate |
FocusDelegate<K>: the delegate to be used |
Return | |
---|---|
SelectionTracker.Builder<K> |
this |
withGestureTooltypes
@NonNull funwithGestureTooltypes(@NonNull vararg toolTypes: Int): SelectionTracker.Builder<K>
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 |
Return | |
---|---|
SelectionTracker.Builder<K> |
this |
withOnContextClickListener
@NonNull fun withOnContextClickListener(@NonNull listener: OnContextClickListener): SelectionTracker.Builder<K>
Adds a context click listener. Respond to right-click.
Parameters | |
---|---|
listener |
OnContextClickListener: the listener to be used |
Return | |
---|---|
SelectionTracker.Builder<K> |
this |
withOnDragInitiatedListener
@NonNull fun withOnDragInitiatedListener(@NonNull listener: OnDragInitiatedListener): SelectionTracker.Builder<K>
Adds a drag initiated listener. Add support for drag and drop.
Parameters | |
---|---|
listener |
OnDragInitiatedListener: the listener to be used |
Return | |
---|---|
SelectionTracker.Builder<K> |
this |
withOnItemActivatedListener
@NonNull fun withOnItemActivatedListener(@NonNull