Overview

An ItemDetails implementation provides the selection library with access to information about a specific RecyclerView item. This class is a key component in controling the behaviors of the selection library in the context of a specific activity.

Selection Hotspot

This is an optional feature identifying an area within a view that is single-tap to select. Ordinarily a single tap on an item when there is no existing selection will result in that item being activated. If the tap occurs within the "selection hotspot" the item will instead be selected.

See OnItemActivatedListener for details on handling item activation.

Drag Region

The selection library provides support for mouse driven band selection. The "lasso" typically associated with mouse selection can be started only in an empty area of the RecyclerView (an area where the item position == RecyclerView#NO_POSITION, or where RecyclerView#findChildViewUnder returns null). But in many instances the item views presented by RecyclerView will contain areas that may be perceived by the user as being empty. The user may expect to be able to initiate band selection in these empty areas.

The "drag region" concept exists in large part to accommodate this user expectation. Drag region is the content in an item view that the user doesn't otherwise perceive to be empty or part of the background of recycler view. Take for example a traditional single column layout where the view layout width is "match_parent":

 -------------------------------------------------------
 | [icon]  A string label.   ...empty space...         |
 -------------------------------------------------------
   < ---  drag region  --> < --treated as background-->

Further more, within a drag region, a mouse click and drag will immediately initiate drag and drop (if supported by your configuration).

As user expectations around touch and mouse input differ substantially, "drag region" has no effect on handling of touch input.

Summary

Constructors

Methods

Returns the adapter position of the item. See

Returns:

the position of an item.

Returns:

true if the item has a selection key.

Returns:

the selection key of an item.

Areas are often included in a view that behave similar to checkboxes, such as the icon to the left of an email message. "selection hotspot" provides a mechanism to identify such regions, and for the library to directly translate taps in these regions into a change in selection state.

Returns:

true if the event is in an area of the item that should be directly interpreted as a user wishing to select the item. This is useful for checkboxes and other UI affordances focused on enabling selection.

"Item Drag Region" identifies areas of an item that are not considered when the library evaluates whether or not to initiate band-selection for mouse input. The drag region will usually correspond to an area of an item that represents user visible content. Mouse driven band selection operations are only ever initiated in non-drag-regions. This is a consideration as many layouts may not include empty space between RecyclerView items where band selection can be initiated.

For example. You may present a single column list of contact names in a RecyclerView instance in which the individual view items expand to fill all available space. But within the expanded view item after the contact name there may be empty space that a user would reasonably expect to initiate band selection. When a MotionEvent occurs in such an area, you should return identify this as NOT in a drag region.

Further more, within a drag region, a mouse click and drag will immediately initiate drag and drop (if supported by your configuration).

Returns:

true if the item is in an area of the item that can result in dragging the item. List items frequently have a white area that is not draggable allowing mouse driven band selection to be initiated in that area.