package

androidx.recyclerview.selection

Overview

A RecyclerView addon library providing support for item selection. The library provides support for both touch and mouse driven selection. Developers retain control over the visual representation, and the policies controlling selection behavior (like which items are eligible for selection, and how many items can be selected.)

Want to add selection support to your RecyclerView? Here's how you do it:

Determine which selection key type to use, then build your KeyProvider

Developers must decide on the key type used to identify selected items. Support is provided for three types: Parcelable, String, and Long.

See SelectionTracker.Builder for more detailed advice on which key type to use for your selection keys.

Implement ItemDetailsLookup

This class provides the selection library code necessary access to information about items associated with android.view.MotionEvent. This will likely depend on concrete RecyclerView.ViewHolder type employed by your application.

Update views used in RecyclerView to reflect selected state

When the user selects an item the library will record that in SelectionTracker then notify RecyclerView that the state of the item has changed. This will ultimately cause the value to be rebound by way of RecyclerView.Adapter#onBindViewHolder. The item must then be updated to reflect the new selection status. Without this the user will not *see* that the item has been selected.

  • In Adapter#onBindViewHolder, set the "activated" status on view. Note that the status should be "activated" not "selected". See View.html#setActivated for details.
  • Update the styling of the view to represent the activated status. This can be done with a color state list.

Use ActionMode when there is a selection

Register a SelectionTracker.SelectionObserver to be notified when selection changes. When a selection is first created, start ActionMode to represent this to the user, and provide selection specific actions.

Interpreted secondary actions: Drag and Drop, and Item Activation

At the end of the event processing pipeline the library may determine that the user is attempting to activate an item by tapping it, or is attempting to drag and drop an item or set of selected items. React to these interpretations by registering a respective listener. See SelectionTracker.Builder for details.

Assemble everything with SelectionTracker.Builder

Example usage (with Long selection keys): 

SelectionTracker tracker = new SelectionTracker.Builder<>(
        "my-selection-id",
        recyclerView,
        new StableIdKeyProvider(recyclerView),
        new MyDetailsLookup(recyclerView),
        StorageStrategy.createLongStorage())
        .build();

In order to build a SelectionTracker instance the supplied RecyclerView must be initialized with an Adapter. Given this fact, you will probably need to inject the SelectionTracker instance into your RecyclerView.Adapter after the Adapter is created, as it will be necessary to consult selected status using SelectionTracker from the onBindViewHolder method.

Include Selection in Activity lifecycle events

In order to preserve state, the author must include the selection library in the handling of Activity lifecycle events. See SelectionTracker#onSaveInstanceState and SelectionTracker#onRestoreInstanceState.

A unique selection id must be supplied to SelectionTracker.Builder constructor. This is necessary as an activity or fragment may have multiple distinct selectable lists that may both need to be persisted in saved state.

Interfaces

OnContextClickListenerRegister an OnContextClickListener to be notified when a context click occurs.
OnDragInitiatedListenerRegister an OnDragInitiatedListener to be notified when user intent to perform drag and drop operations on an item or items has been detected.
OnItemActivatedListener<K>Register an OnItemActivatedListener to be notified when an item is activated (tapped or double clicked).
OperationMonitor.OnChangeListenerListen to changes in operation status.
ResettableRepresents an object that can be reset and can advise on it's need to be reset.

Classes

AutoScrollerProvides support for auto-scrolling a view.
BandPredicateProvides a means of controlling when and where band selection can be initiated.
BandPredicate.EmptyAreaA BandPredicate that allows initiation of band selection only in areas of RecyclerView that map to RecyclerView.NO_POSITION.
BandPredicate.NonDraggableAreaA BandPredicate that allows initiation of band selection in any area that is not draggable as determined by consulting ItemDetailsLookup.ItemDetails.inDragRegion(MotionEvent).
DefaultSelectionTracker<K>SelectionTracker providing support for traditional multi-item selection on top of RecyclerView.
EventBridgeProvides the necessary glue to notify RecyclerView when selection data changes, and to notify SelectionTracker when the underlying RecyclerView.Adapter data changes.
FocusDelegate<K>Override methods in this class to provide application specific behaviors related to focusing item.
ItemDetailsLookup<K>The Selection library calls ItemDetailsLookup.getItemDetails(MotionEvent) when it needs access to information about the area and/or ItemDetailsLookup.ItemDetails under a MotionEvent.
ItemDetailsLookup.ItemDetails<K>An ItemDetails implementation provides the selection library with access to information about a specific RecyclerView item.
ItemKeyProvider<K>Provides selection library access to stable selection keys identifying items presented by a RecyclerView instance.
MutableSelection<K>Subclass of Selection exposing public support for mutating the underlying selection data.
OperationMonitorOperationMonitor provides a mechanism to coordinate application logic with ongoing user selection activities (such as active band selection and active gesture selection).
Selection<K>Object representing a "primary" selection and a "provisional" selection.
SelectionPredicatesUtility class for creating SelectionPredicate instances.
SelectionTracker<K>SelectionTracker provides support for managing a selection of items in a RecyclerView instance.
SelectionTracker.Builder<K>Builder is the primary mechanism for creating a SelectionTracker that can be used with your RecyclerView.
SelectionTracker.SelectionObserver<K>Observer class providing access to information about Selection state changes.
SelectionTracker.SelectionPredicate<K>Implement SelectionPredicate to control when items can be selected or unselected.
StableIdKeyProviderAn ItemKeyProvider that provides item keys by way of native stable ids.
StorageStrategy<K>Strategy for storing keys in saved state.

Annotation Types

ItemKeyProvider.Scope
Generated Fri, 13 Sep 2024 06:44:36 +0000 by Michael Jentsch - Privacy Policy - Legal Details