LoadStateAdapter

Kotlin |Java

public abstract class LoadStateAdapter<VH extends RecyclerView.ViewHolder> extends RecyclerView.Adapter

Object
↳	RecyclerView.Adapter
	↳	LoadStateAdapter

Adapter for displaying a RecyclerView item based on LoadState, such as a loading spinner, or a retry error button.

By default will use one shared view type for all items.

By default, both LoadState.Loading and LoadState.Error are presented as adapter items, other states are not. To configure this, override displayLoadStateAsItem.

To present this Adapter as a header and or footer alongside your PagingDataAdapter, see PagingDataAdapter.withLoadStateHeaderAndFooter, or use ConcatAdapter directly to concatenate Adapters.

class LoadStateViewHolder(
    parent: ViewGroup,
    retry: () -> Unit
) : RecyclerView.ViewHolder(
    LayoutInflater.from(parent.context)
        .inflate(R.layout.load_state_item, parent, false)
) {
    private val progressBar: ProgressBar = itemView.findViewById(R.id.progress_bar)
    private val errorMsg: TextView = itemView.findViewById(R.id.error_msg)
    private val retry: Button = itemView.findViewById<Button>(R.id.retry_button)
        .also { it.setOnClickListener { retry.invoke() } }

    fun bind(loadState: LoadState) {
        if (loadState is LoadState.Error) {
            errorMsg.text = loadState.error.localizedMessage
        }
        progressBar.visibility = toVisibility(loadState is LoadState.Loading)
        retry.visibility = toVisibility(loadState !is LoadState.Loading)
        errorMsg.visibility = toVisibility(loadState !is LoadState.Loading)
    }

    private fun toVisibility(constraint: Boolean): Int = if (constraint) {
        View.VISIBLE
    } else {
        View.GONE
    }
}

/**
 * Adapter which displays a loading spinner when `state = LoadState.Loading`, and an error
 * message and retry button when `state is LoadState.Error`.
 */
class MyLoadStateAdapter(
    private val retry: () -> Unit
) : LoadStateAdapter<LoadStateViewHolder>() {

    override fun onCreateViewHolder(parent: ViewGroup, loadState: LoadState) =
        LoadStateViewHolder(parent, retry)

    override fun onBindViewHolder(holder: LoadStateViewHolder, loadState: LoadState) =
        holder.bind(loadState)
}

See also
`withLoadStateHeaderAndFooter`
`withLoadStateHeader`
`withLoadStateFooter`

Summary

Public fields
`final @NonNull LoadState`	`loadState` LoadState to present in the adapter.

Public constructors
`<VH extends RecyclerView.ViewHolder> LoadStateAdapter()`

Public methods
`boolean`	`displayLoadStateAsItem(@NonNull LoadState loadState)` Returns true if the LoadState should be displayed as a list item when active.
`final int`	`getItemCount()` Returns the total number of items in the data set held by the adapter.
`final int`	`getItemViewType(int position)` Return the view type of the item at `position` for the purposes of view recycling.
`int`	`getStateViewType(@NonNull LoadState loadState)` Override this method to use different view types per LoadState.
`final void`	`onBindViewHolder(@NonNull VH holder, int position)` Called by RecyclerView to display the data at the specified position.
`abstract void`	`onBindViewHolder(@NonNull VH holder, @NonNull LoadState loadState)` Called to bind the passed LoadState to the ViewHolder.
`final @NonNull VH`	`onCreateViewHolder(@NonNull ViewGroup parent, int viewType)` Called when RecyclerView needs a new `ViewHolder` of the given type to represent an item.
`abstract @NonNull VH`	`onCreateViewHolder(@NonNull ViewGroup parent, @NonNull LoadState loadState)` Called to create a ViewHolder for the given LoadState.

Inherited methods

From class RecyclerView.Adapter

`final void`	`bindViewHolder(@NonNull VH holder, int position)`
`boolean`	`canRestoreState()`
`final @NonNull VH`	`createViewHolder(@NonNull ViewGroup parent, int viewType)`
`int`	`findRelativeAdapterPositionIn( @NonNull RecyclerView.Adapter<@NonNull RecyclerView.ViewHolder> adapter, @NonNull RecyclerView.ViewHolder viewHolder, int localPosition )`
`long`	`getItemId(int position)`
`final @NonNull RecyclerView.Adapter.StateRestorationPolicy`	`getStateRestorationPolicy()`
`final boolean`	`hasObservers()`
`final boolean`	`hasStableIds()`
`final void`	`notifyDataSetChanged()`
`final void`	`notifyItemChanged(int position)`
`final void`	`notifyItemChanged(int position, @Nullable Object payload)`
`final void`	`notifyItemInserted(int position)`
`final void`	`notifyItemMoved(int fromPosition, int toPosition)`
`final void`	`notifyItemRangeChanged(int positionStart, int itemCount)`
`final void`	`notifyItemRangeChanged( int positionStart, int itemCount, @Nullable Object payload )`
`final void`	`notifyItemRangeInserted(int positionStart, int itemCount)`
`final void`	`notifyItemRangeRemoved(int positionStart, int itemCount)`
`final void`	`notifyItemRemoved(int position)`
`void`	`onAttachedToRecyclerView(@NonNull RecyclerView recyclerView)`
`void`	`onBindViewHolder( @NonNull VH holder, int position, @NonNull List<@NonNull Object> payloads )`
`void`	`onDetachedFromRecyclerView(@NonNull RecyclerView recyclerView)`
`boolean`	`onFailedToRecycleView(@NonNull VH holder)`
`void`	`onViewAttachedToWindow(@NonNull VH holder)`
`void`	`onViewDetachedFromWindow(@NonNull VH holder)`
`void`	`onViewRecycled(@NonNull VH holder)`
`void`	`registerAdapterDataObserver( @NonNull RecyclerView.AdapterDataObserver observer )`
`void`	`setHasStableIds(boolean hasStableIds)`
`void`	`setStateRestorationPolicy( @NonNull RecyclerView.Adapter.StateRestorationPolicy strategy )`
`void`	`unregisterAdapterDataObserver( @NonNull RecyclerView.AdapterDataObserver observer )`

Public fields

loadState

@NonNull
public final @NonNull LoadState loadState

LoadState to present in the adapter.

Changing this property will immediately notify the Adapter to change the item it's presenting.

Public constructors

LoadStateAdapter

public final <VH extends RecyclerView.ViewHolder> LoadStateAdapter()

Public methods

displayLoadStateAsItem

@NonNull
public boolean displayLoadStateAsItem(@NonNull LoadState loadState)

Returns true if the LoadState should be displayed as a list item when active.

By default, LoadState.Loading and LoadState.Error present as list items, others do not.

getItemCount

@NonNull
public final 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.

getItemViewType

@NonNull
public final 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
`int position`	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.

getStateViewType

@NonNull
public int getStateViewType(@NonNull LoadState loadState)

Override this method to use different view types per LoadState.

By default, this LoadStateAdapter only uses a single view type.

@NonNull
public final void onBindViewHolder(@NonNull VH holder, int position)

Called by RecyclerView to display the data at the specified position. This method should update the contents of the itemView to reflect the item at the given position.

Note that unlike android.widget.ListView, RecyclerView will not call this method again if the position of the item changes in the data set unless the item itself is invalidated or the new position cannot be determined. For this reason, you should only use the position parameter while acquiring the related data item inside this method and should not keep a copy of it. If you need the position of an item later on (e.g. in a click listener), use getBindingAdapterPosition which will have the updated adapter position. Override onBindViewHolder instead if Adapter can handle efficient partial bind.

Parameters
`@NonNull VH holder`	The ViewHolder which should be updated to represent the contents of the item at the given position in the data set.
`int position`	The position of the item within the adapter's data set.

@NonNull
public abstract void onBindViewHolder(@NonNull VH holder, @NonNull LoadState loadState)

Called to bind the passed LoadState to the ViewHolder.

Parameters
`@NonNull LoadState loadState`	LoadState to display.

See also
`getItemViewType`
`displayLoadStateAsItem`

onCreateViewHolder

@NonNull
public final VH onCreateViewHolder(@NonNull ViewGroup parent, int viewType)

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

This new ViewHolder should be constructed with a new View that can represent the items of the given type. You can either create a new View manually or inflate it from an XML layout file.

The new ViewHolder will be used to display items of the adapter using onBindViewHolder. Since it will be re-used to display different items in the data set, it is a good idea to cache references to sub views of the View to avoid unnecessary findViewById calls.

Parameters
`@NonNull ViewGroup parent`	The ViewGroup into which the new View will be added after it is bound to an adapter position.
`int viewType`	The view type of the new View.

Returns
`VH`	A new ViewHolder that holds a View of the given view type.

See also
`getItemViewType`	#getItemViewType(int)
`onBindViewHolder`	#onBindViewHolder(ViewHolder, int)

onCreateViewHolder

@NonNull
public abstract VH onCreateViewHolder(@NonNull ViewGroup parent, @NonNull LoadState loadState)

Called to create a ViewHolder for the given LoadState.

Parameters
`@NonNull ViewGroup parent`	The ViewGroup into which the new View will be added after it is bound to an adapter position.
`@NonNull LoadState loadState`	The LoadState to be initially presented by the new ViewHolder.

See also
`getItemViewType`
`displayLoadStateAsItem`