# SelectionTracker.Builder

Artifact: [androidx.recyclerview:recyclerview-selection](https://developer.android.com/jetpack/androidx/releases/recyclerview) [View Source](https://cs.android.com/search?q=file:androidx/recyclerview/selection/SelectionTracker.java+class:androidx.recyclerview.selection.SelectionTracker.Builder) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

*** ** * ** ***


```
public final class SelectionTracker.Builder<K>
```

<br />

*** ** * ** ***

Builder is the primary mechanism for create a `https://developer.android.com/reference/androidx/recyclerview/selection/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**

`https://developer.android.com/reference/androidx/recyclerview/selection/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 `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionPredicates#createSelectSingleAnything()`. SelectionTrackertracker = 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: `https://developer.android.com/reference/android/os/Parcelable.html`, `https://developer.android.com/reference/java/lang/String.html`, and `https://developer.android.com/reference/java/lang/Long.html`.

`https://developer.android.com/reference/android/os/Parcelable.html`: Any Parcelable type can be used as the selection key. This is especially useful in conjunction with `https://developer.android.com/reference/android/net/Uri.html` 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.

`https://developer.android.com/reference/java/lang/String.html`: Use String when a string based stable identifier is available.

`https://developer.android.com/reference/java/lang/Long.html`: 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 `https://developer.android.com/reference/androidx/recyclerview/selection/StableIdKeyProvider` for details.

Usage:

```
     private SelectionTrackermTracker; 
     
     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); 
      }
```

| Parameters |
|---|---|
| `<K>` | Selection key type. Built in support is provided for `https://developer.android.com/reference/java/lang/String.html`, `https://developer.android.com/reference/java/lang/Long.html`, and `https://developer.android.com/reference/android/os/Parcelable.html`. `https://developer.android.com/reference/androidx/recyclerview/selection/StorageStrategy` provides factory methods for each type: `https://developer.android.com/reference/androidx/recyclerview/selection/StorageStrategy#createStringStorage()`, `https://developer.android.com/reference/androidx/recyclerview/selection/StorageStrategy#createParcelableStorage(java.lang.Class<K>)`, `https://developer.android.com/reference/androidx/recyclerview/selection/StorageStrategy#createLongStorage()` |

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#Builder(java.lang.String,androidx.recyclerview.widget.RecyclerView,androidx.recyclerview.selection.ItemKeyProvider<K>,androidx.recyclerview.selection.ItemDetailsLookup<K>,androidx.recyclerview.selection.StorageStrategy<K>)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html selectionId, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView recyclerView, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/ItemKeyProvider<K> keyProvider, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/ItemDetailsLookup<K> detailsLookup, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/StorageStrategy<K> storage )` Creates a new SelectionTracker.Builder useful for configuring and creating a new SelectionTracker for use with your `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView`. |

| ### Public methods |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker<K>` | `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#build()()` Prepares and returns a SelectionTracker. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withBandOverlay(int)(@https://developer.android.com/reference/androidx/annotation/DrawableRes int bandOverlayId)` Replaces default band overlay. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withBandPredicate(androidx.recyclerview.selection.BandPredicate)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/BandPredicate bandPredicate)` Replaces default band predicate. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withFocusDelegate(androidx.recyclerview.selection.FocusDelegate<K>)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/FocusDelegate<K> delegate)` Add focus delegate to interact with selection related focus changes. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `[withGestureTooltypes](https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withGestureTooltypes(int...))(@https://developer.android.com/reference/androidx/annotation/NonNull int[] toolTypes)` **This method is deprecated.** GestureSelection is best bound to `https://developer.android.com/reference/android/view/MotionEvent.html#TOOL_TYPE_FINGER`, and only that tool type. <br /> |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withOnContextClickListener(androidx.recyclerview.selection.OnContextClickListener)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/OnContextClickListener listener)` Adds a context click listener. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withOnDragInitiatedListener(androidx.recyclerview.selection.OnDragInitiatedListener)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/OnDragInitiatedListener listener)` Adds a drag initiated listener. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withOnItemActivatedListener(androidx.recyclerview.selection.OnItemActivatedListener<K>)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/OnItemActivatedListener<K> listener )` Adds an item activation listener. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withOperationMonitor(androidx.recyclerview.selection.OperationMonitor)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/OperationMonitor monitor)` Add operation monitor allowing access to information about active operations (like band selection and gesture selection). |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `[withPointerTooltypes](https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withPointerTooltypes(int...))(@https://developer.android.com/reference/androidx/annotation/NonNull int[] toolTypes)` **This method is deprecated.** PointerSelection is best bound to `https://developer.android.com/reference/android/view/MotionEvent.html#TOOL_TYPE_MOUSE`, and only that tool type. <br /> |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | `https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withSelectionPredicate(androidx.recyclerview.selection.SelectionTracker.SelectionPredicate<K>)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.SelectionPredicate<K> predicate )` Install selection predicate. |

## Public constructors

### Builder

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public Builder(
    @NonNull String selectionId,
    @NonNull RecyclerView recyclerView,
    @NonNull ItemKeyProvider<K> keyProvider,
    @NonNull ItemDetailsLookup<K> detailsLookup,
    @NonNull StorageStrategy<K> storage
)
```

Creates a new SelectionTracker.Builder useful for configuring and creating a new SelectionTracker for use with your `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html selectionId` | A unique string identifying this selection in the context of the activity or fragment. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView recyclerView` | the owning RecyclerView |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/ItemKeyProvider<K> keyProvider` | the source of selection keys |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/ItemDetailsLookup<K> detailsLookup` | the source of information about RecyclerView items. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/StorageStrategy<K> storage` | Strategy for type-safe storage of selection state in `https://developer.android.com/reference/android/os/Bundle.html`. |

## Public methods

### build

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public @NonNull SelectionTracker<K> build()
```

Prepares and returns a SelectionTracker.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker<K>` | this |

### withBandOverlay

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public @NonNull SelectionTracker.Builder<K> withBandOverlay(@DrawableRes int bandOverlayId)
```

Replaces default band overlay.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |

### withBandPredicate

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public @NonNull SelectionTracker.Builder<K> withBandPredicate(@NonNull BandPredicate bandPredicate)
```

Replaces default band predicate.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |

### withFocusDelegate

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public @NonNull SelectionTracker.Builder<K> withFocusDelegate(@NonNull FocusDelegate<K> delegate)
```

Add focus delegate to interact with selection related focus changes.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/FocusDelegate<K> delegate` | the delegate to be used |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |

### withGestureTooltypes

```
public @NonNull SelectionTracker.Builder<K> [withGestureTooltypes](https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withGestureTooltypes(int...))(@NonNull int[] toolTypes)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> GestureSelection is best bound to `https://developer.android.com/reference/android/view/MotionEvent.html#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: `https://developer.android.com/reference/android/view/MotionEvent.html#TOOL_TYPE_FINGER`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull int[] toolTypes` | the tool types to be used |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |

### withOnContextClickListener

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public @NonNull SelectionTracker.Builder<K> withOnContextClickListener(@NonNull OnContextClickListener listener)
```

Adds a context click listener. Respond to right-click.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/OnContextClickListener listener` | the listener to be used |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |

### withOnDragInitiatedListener

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public @NonNull SelectionTracker.Builder<K> withOnDragInitiatedListener(@NonNull OnDragInitiatedListener listener)
```

Adds a drag initiated listener. Add support for drag and drop.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/OnDragInitiatedListener listener` | the listener to be used |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |

### withOnItemActivatedListener

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public @NonNull SelectionTracker.Builder<K> withOnItemActivatedListener(
    @NonNull OnItemActivatedListener<K> listener
)
```

Adds an item activation listener. Respond to taps/enter/double-click on items.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/OnItemActivatedListener<K> listener` | the listener to be used |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |

### withOperationMonitor

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public @NonNull SelectionTracker.Builder<K> withOperationMonitor(@NonNull OperationMonitor monitor)
```

Add operation monitor allowing access to information about active operations (like band selection and gesture selection).

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/OperationMonitor monitor` | the monitor to be used |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |

### withPointerTooltypes

```
public @NonNull SelectionTracker.Builder<K> [withPointerTooltypes](https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder#withPointerTooltypes(int...))(@NonNull int[] toolTypes)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> PointerSelection is best bound to `https://developer.android.com/reference/android/view/MotionEvent.html#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: `https://developer.android.com/reference/android/view/MotionEvent.html#TOOL_TYPE_MOUSE`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull int[] toolTypes` | the tool types to be used |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |

### withSelectionPredicate

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public @NonNull SelectionTracker.Builder<K> withSelectionPredicate(
    @NonNull SelectionTracker.SelectionPredicate<K> predicate
)
```

Install selection predicate.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.SelectionPredicate<K> predicate` | the predicate to be used. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/selection/SelectionTracker.Builder<K>` | this |