RecyclerView.Adapter

public static abstract class RecyclerView.Adapter
extends Object

java.lang.Object
   ↳ androidx.recyclerview.widget.RecyclerView.Adapter<VH extends androidx.recyclerview.widget.RecyclerView.ViewHolder>


Base class for an Adapter

Adapters provide a binding from an app-specific data set to views that are displayed within a RecyclerView.

Summary

Nested classes

enum RecyclerView.Adapter.StateRestorationPolicy

Defines how this Adapter wants to restore its state after a view reconstruction (e.g. 

Public constructors

Adapter()

Public methods

final void bindViewHolder(VH holder, int position)

This method internally calls onBindViewHolder(ViewHolder, int) to update the RecyclerView.ViewHolder contents with the item at the given position and also sets up some private fields to be used by RecyclerView.

final VH createViewHolder(ViewGroup parent, int viewType)

This method calls onCreateViewHolder(ViewGroup, int) to create a new RecyclerView.ViewHolder and initializes some private fields to be used by RecyclerView.

int findRelativeAdapterPositionIn(Adapter<? extends RecyclerView.ViewHolder> adapter, RecyclerView.ViewHolder viewHolder, int localPosition)

Returns the position of the given RecyclerView.ViewHolder in the given RecyclerView.Adapter.

abstract int getItemCount()

Returns the total number of items in the data set held by the adapter.

long getItemId(int position)

Return the stable ID for the item at position.

int getItemViewType(int position)

Return the view type of the item at position for the purposes of view recycling.

final RecyclerView.Adapter.StateRestorationPolicy getStateRestorationPolicy()

Returns when this Adapter wants to restore the state.

final boolean hasObservers()

Returns true if one or more observers are attached to this adapter.

final boolean hasStableIds()

Returns true if this adapter publishes a unique long value that can act as a key for the item at a given position in the data set.

final void notifyDataSetChanged()

Notify any registered observers that the data set has changed.

final void notifyItemChanged(int position, Object payload)

Notify any registered observers that the item at position has changed with an optional payload object.

final void notifyItemChanged(int position)

Notify any registered observers that the item at position has changed.

final void notifyItemInserted(int position)

Notify any registered observers that the item reflected at position has been newly inserted.

final void notifyItemMoved(int fromPosition, int toPosition)

Notify any registered observers that the item reflected at fromPosition has been moved to toPosition.

final void notifyItemRangeChanged(int positionStart, int itemCount, Object payload)

Notify any registered observers that the itemCount items starting at position positionStart have changed.

final void notifyItemRangeChanged(int positionStart, int itemCount)

Notify any registered observers that the itemCount items starting at position positionStart have changed.

final void notifyItemRangeInserted(int positionStart, int itemCount)

Notify any registered observers that the currently reflected itemCount items starting at positionStart have been newly inserted.

final void notifyItemRangeRemoved(int positionStart, int itemCount)

Notify any registered observers that the itemCount items previously located at positionStart have been removed from the data set.

final void notifyItemRemoved(int position)

Notify any registered observers that the item previously located at position has been removed from the data set.

void onAttachedToRecyclerView(RecyclerView recyclerView)

Called by RecyclerView when it starts observing this Adapter.

abstract void onBindViewHolder(VH holder, int position)

Called by RecyclerView to display the data at the specified position.

void onBindViewHolder(VH holder, int position, List<Object> payloads)

Called by RecyclerView to display the data at the specified position.

abstract VH onCreateViewHolder(ViewGroup parent, int viewType)

Called when RecyclerView needs a new RecyclerView.ViewHolder of the given type to represent an item.

void onDetachedFromRecyclerView(RecyclerView recyclerView)

Called by RecyclerView when it stops observing this Adapter.

boolean onFailedToRecycleView(VH holder)

Called by the RecyclerView if a ViewHolder created by this Adapter cannot be recycled due to its transient state.

void onViewAttachedToWindow(VH holder)

Called when a view created by this adapter has been attached to a window.

void onViewDetachedFromWindow(VH holder)

Called when a view created by this adapter has been detached from its window.

void onViewRecycled(VH holder)

Called when a view created by this adapter has been recycled.

void registerAdapterDataObserver(RecyclerView.AdapterDataObserver observer)

Register a new observer to listen for data changes.

void setHasStableIds(boolean hasStableIds)

Indicates whether each item in the data set can be represented with a unique identifier of type Long.

void setStateRestorationPolicy(RecyclerView.Adapter.StateRestorationPolicy strategy)

Sets the state restoration strategy for the Adapter.

void unregisterAdapterDataObserver(RecyclerView.AdapterDataObserver observer)

Unregister an observer currently listening for data changes.

Inherited methods

Public constructors

Adapter

public Adapter ()

Public methods

bindViewHolder

public final void bindViewHolder (VH holder, 
                int position)

This method internally calls onBindViewHolder(ViewHolder, int) to update the RecyclerView.ViewHolder contents with the item at the given position and also sets up some private fields to be used by RecyclerView. Adapters that merge other adapters should use bindViewHolder(ViewHolder, int) when calling nested adapters so that RecyclerView can track which adapter bound the RecyclerView.ViewHolder to return the correct position from RecyclerView.ViewHolder.getBindingAdapterPosition() method. They should also override the findRelativeAdapterPositionIn(Adapter, ViewHolder, int) method.

Parameters
holder VH: The view holder whose contents should be updated

position int: The position of the holder with respect to this adapter

createViewHolder

public final VH createViewHolder (ViewGroup parent, 
                int viewType)

This method calls onCreateViewHolder(ViewGroup, int) to create a new RecyclerView.ViewHolder and initializes some private fields to be used by RecyclerView.

Parameters
parent ViewGroup

viewType int

Returns
VH

findRelativeAdapterPositionIn

public int findRelativeAdapterPositionIn (Adapter<? extends RecyclerView.ViewHolder> adapter, 
                RecyclerView.ViewHolder viewHolder, 
                int localPosition)

Returns the position of the given RecyclerView.ViewHolder in the given RecyclerView.Adapter. If the given RecyclerView.Adapter is not part of this RecyclerView.Adapter, RecyclerView.NO_POSITION is returned.

Parameters
adapter Adapter: The adapter which is a sub adapter of this adapter or itself.

viewHolder RecyclerView.ViewHolder: The ViewHolder whose local position in the given adapter will be returned.

localPosition int: The position of the given RecyclerView.ViewHolder in this RecyclerView.Adapter.

Returns
int The local position of the given RecyclerView.ViewHolder in this RecyclerView.Adapter or RecyclerView.NO_POSITION if the RecyclerView.ViewHolder is not bound to an item or the given RecyclerView.Adapter is not part of this Adapter (if this Adapter merges other adapters).

getItemCount

public abstract int getItemCount ()

Returns the total number of items in the data set held by the adapter.

Returns
int The total number of items in this adapter.

getItemId

public long getItemId (int position)

Return the stable ID for the item at position. If hasStableIds() would return false this method should return RecyclerView.NO_ID. The default implementation of this method returns RecyclerView.NO_ID.

Parameters
position int: Adapter position to query

Returns
long the stable ID of the item at position

getItemViewType

public int getItemViewType (int position)

Return the view type of the item at position for the purposes of view recycling.

The default implementation of this method returns 0, making the assumption of a single view type for the adapter. Unlike ListView adapters, types need not be contiguous. Consider using id resources to uniquely identify item view types.

Parameters
position int: position to query

Returns
int integer value identifying the type of the view needed to represent the item at position. Type codes need not be contiguous.

getStateRestorationPolicy

public final RecyclerView.Adapter.StateRestorationPolicy getStateRestorationPolicy ()

Returns when this Adapter wants to restore the state.

Returns
RecyclerView.Adapter.StateRestorationPolicy The current RecyclerView.Adapter.StateRestorationPolicy for this Adapter. Defaults to RecyclerView.Adapter.StateRestorationPolicy.ALLOW.

hasObservers

public final boolean hasObservers ()

Returns true if one or more observers are attached to this adapter.

Returns
boolean true if this adapter has observers

hasStableIds

public final boolean hasStableIds ()

Returns true if this adapter publishes a unique long value that can act as a key for the item at a given position in the data set. If that item is relocated in the data set, the ID returned for that item should be the same.

Returns
boolean true if this adapter's items have stable IDs

notifyDataSetChanged

public final void notifyDataSetChanged ()

Notify any registered observers that the data set has changed.

There are two different classes of data change events, item changes and structural changes. Item changes are when a single item has its data updated but no positional changes have occurred. Structural changes are when items are inserted, removed or moved within the data set.

This event does not specify what about the data set has changed, forcing any observers to assume that all existing items and structure may no longer be valid. LayoutManagers will be forced to fully rebind and relayout all visible views.

RecyclerView will attempt to synthesize visible structural change events for adapters that report that they have stable IDs when this method is used. This can help for the purposes of animation and visual object persistence but individual item views will still need to be rebound and relaid out.

If you are writing an adapter it will always be more efficient to use the more specific change events if you can. Rely on notifyDataSetChanged() as a last resort.

notifyItemChanged

public final void notifyItemChanged (int position, 
                Object payload)

Notify any registered observers that the item at position has changed with an optional payload object.

This is an item change event, not a structural change event. It indicates that any reflection of the data at position is out of date and should be updated. The item at position retains the same identity.

Client can optionally pass a payload for partial change. These payloads will be merged and may be passed to adapter's onBindViewHolder(ViewHolder, int, List) if the item is already represented by a ViewHolder and it will be rebound to the same ViewHolder. A notifyItemRangeChanged() with null payload will clear all existing payloads on that item and prevent future payload until onBindViewHolder(ViewHolder, int, List) is called. Adapter should not assume that the payload will always be passed to onBindViewHolder(), e.g. when the view is not attached, the payload will be simply dropped.

Parameters
position int: Position of the item that has changed

payload Object: Optional parameter, use null to identify a "full" update

notifyItemChanged

public final void notifyItemChanged (int position)

Notify any registered observers that the item at position has changed. Equivalent to calling notifyItemChanged(position, null);.

This is an item change event, not a structural change event. It indicates that any reflection of the data at position is out of date and should be updated. The item at position retains the same identity.

Parameters
position int: Position of the item that has changed

notifyItemInserted

public final void notifyItemInserted (int position)

Notify any registered observers that the item reflected at position has been newly inserted. The item previously at position is now at position position + 1.

This is a structural change event. Representations of other existing items in the data set are still considered up to date and will not be rebound, though their positions may be altered.

Parameters
position int: Position of the newly inserted item in the data set

notifyItemMoved

public final void notifyItemMoved (int fromPosition, 
                int toPosition)

Notify any registered observers that the item refl