Register now for Android Dev Summit 2019!

PagedListView

open class PagedListView : FrameLayout
kotlin.Any
   ↳ android.view.View
   ↳ android.view.ViewGroup
   ↳ android.widget.FrameLayout
   ↳ androidx.car.widget.PagedListView

View that wraps a RecyclerView and a scroll bar that has page up and down arrows. Interaction with this view is similar to a RecyclerView as it takes the same adapter.

By default, this PagedListView utilizes a vertical LinearLayoutManager to display its items.

Summary

Nested classes

abstract

Interface for controlling visibility of item dividers for individual items based on the item's position.

The possible values for @{link #setGutter}.

abstract

Interface for a RecyclerView.Adapter to cap the number of items.

abstract

Interface for a RecyclerView.Adapter to set the position offset for the adapter to load the data.

abstract

Used to listen for PagedListView scroll events.

Constants

static Int

Value to pass to setMaxPages(int) to indicate there is no restriction on the maximum number of pages to show.

Public constructors

<init>(context: Context!)

<init>(context: Context!, attrs: AttributeSet!)

<init>(context: Context!, attrs: AttributeSet!, defStyleAttrs: Int)

<init>(context: Context!, attrs: AttributeSet!, defStyleAttrs: Int, defStyleRes: Int)

Public methods

open Unit

Adds an RecyclerView.ItemDecoration to this PagedListView.

open Unit

Adds an RecyclerView.OnItemTouchListener to this PagedListView.

open RecyclerView.Adapter<out RecyclerView.ViewHolder!>?

open Int

Returns the bottom offset of the list that was set by setListContentBottomOffset(int).

open Int

Returns the top offset of the list that was set by setListContentTopOffset(int).

open Int

Returns the maximum number of pages allowed in the PagedListView.

open Int
getPage(position: Int)

Returns the page the given position is on, starting with page 0.

open RecyclerView

open Int

Gets the number of rows per page.

open Unit

Hide the Alpha Jump Overlay.

open Boolean

Returns true if the Alpha Jump Overlay is shown.

open Boolean

Returns true if the RecyclerView is completely displaying the last item.

open Boolean

Returns true if the RecyclerView is completely displaying the first item.

open Boolean

Returns true if the scroll bar thumb is visible

open Unit
onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int)

open Unit

open Parcelable!

open Unit

Scrolls the contents of the RecyclerView down a page.

open Unit

Scrolls the contents of the RecyclerView up a page.

open Int
positionOf(@Nullable v: View?)

Returns the position of the given View in the list.

open Unit

Removes the given RecyclerView.ItemDecoration from this PagedListView.

open Unit

Removes the given RecyclerView.OnItemTouchListener from the PagedListView.

open Unit
scrollToPosition(position: Int)

Scrolls to the given position in the PagedListView.

open Unit

Sets the adapter for the list.

open Unit
setDividerColor(@ColorRes dividerColor: Int)

Sets the color that should be used for the dividers in the PagedListView.

open Unit

Sets DividerVisibilityManager on all DividerDecoration item decorations.

open Unit

Sets the icon to be used for the down button.

open Unit
setGutter(gutter: Int)

Set the gutter to the specified value.

open Unit
setGutterSize(gutterSize: Int)

Sets the size of the gutter that appears at the start, end or both sizes of the items in the PagedListView.

open Unit
setItemSpacing(itemSpacing: Int)

Sets spacing between each item in the list.

open Unit

Sets an offset after the last item in the PagedListView.

open Unit

Sets an offset above the first item in the PagedListView.

open Unit
setMaxPages(maxPages: Int)

Sets the maximum number of the pages that can be shown in the PagedListView.

open Unit

Sets the OnScrollListener that will be notified of scroll events within the PagedListView.

open Unit

Sets the width of the container that holds the scrollbar.

open Unit

Sets the top margin above the scroll bar.

open Unit

Set the visibility of scroll bar thumb in the scroll bar, the default visibility is true.

open Unit

Sets the icon to be used for the up button.

open Unit

Show the Alpha Jump Overlay.

open Unit
snapToPosition(position: Int)

Snap to the given position.

Protected methods

open Unit

open Unit

open Unit

Constants

UNLIMITED_PAGES

static val UNLIMITED_PAGES: Int

Value to pass to setMaxPages(int) to indicate there is no restriction on the maximum number of pages to show.

Value: -1

Public constructors

<init>

PagedListView(context: Context!)

<init>

PagedListView(context: Context!, attrs: AttributeSet!)

<init>

PagedListView(context: Context!, attrs: AttributeSet!, defStyleAttrs: Int)

<init>

PagedListView(context: Context!, attrs: AttributeSet!, defStyleAttrs: Int, defStyleRes: Int)

Public methods

addItemDecoration

open fun addItemDecoration(@NonNull decor: RecyclerView.ItemDecoration): Unit

Adds an RecyclerView.ItemDecoration to this PagedListView.

Parameters
decor RecyclerView.ItemDecoration: The decoration to add.

addOnItemTouchListener

open fun addOnItemTouchListener(@NonNull touchListener: RecyclerView.OnItemTouchListener): Unit

Adds an RecyclerView.OnItemTouchListener to this PagedListView.

The listener will function the same as the listener for a regular RecyclerView.

Parameters
touchListener RecyclerView.OnItemTouchListener: The touch listener to add.

getAdapter

@Nullable open fun getAdapter(): RecyclerView.Adapter<out RecyclerView.ViewHolder!>?

getListContentBottomOffset

open fun getListContentBottomOffset(): Int

Returns the bottom offset of the list that was set by setListContentBottomOffset(int). If no top offset was set, 0 is returned.

Return
Int: The bottom offset that was set or 0 if none was set.

getListContentTopOffset

open fun getListContentTopOffset(): Int

Returns the top offset of the list that was set by setListContentTopOffset(int). If no top offset was set, 0 is returned.

Return
Int: The top offset that was set or 0 if none was set.

getMaxPages

open fun getMaxPages(): Int

Returns the maximum number of pages allowed in the PagedListView. This number is set by setMaxPages(int). If that method has not been called, then this value should match the default value.

Return
Int: The maximum number of pages to be shown or UNLIMITED_PAGES if there is no limit.

getPage

open fun getPage(position: Int): Int

Returns the page the given position is on, starting with page 0.

getRecyclerView

@NonNull open fun getRecyclerView(): RecyclerView

getRowsPerPage

open fun getRowsPerPage(): Int

Gets the number of rows per page. Default value of mRowsPerPage is -1. If the first child of PagedLayoutManager is null or the height of the first child is 0, it will return 1.

hideAlphaJump

open fun hideAlphaJump(): Unit

Hide the Alpha Jump Overlay.

isAlphaJumpShown

open fun isAlphaJumpShown(): Boolean

Returns true if the Alpha Jump Overlay is shown.

isAtEnd

open fun isAtEnd(): Boolean

Returns true if the RecyclerView is completely displaying the last item.

isAtStart

open fun isAtStart(): Boolean

Returns true if the RecyclerView is completely displaying the first item.

isScrollbarThumbEnabled

open fun isScrollbarThumbEnabled(): Boolean

Returns true if the scroll bar thumb is visible

onLayout

open fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int): Unit

onRestoreInstanceState

open fun onRestoreInstanceState(state: Parcelable!): Unit

onSaveInstanceState

open fun onSaveInstanceState(): Parcelable!

pageDown

open fun pageDown(): Unit

Scrolls the contents of the RecyclerView down a page. A page is defined as the height of the PagedListView.

This method will attempt to bring the last item in the list as the first item. If the current first item in the list is taller than the PagedListView, then it will be scrolled the length of a page, but not snapped to.

pageUp

open fun pageUp(): Unit

Scrolls the contents of the RecyclerView up a page. A page is defined as the height of the PagedListView.

The resulting first item in the list will be snapped to so that it is completely visible. If this is not possible due to the first item being taller than the containing PagedListView, then the snapping will not occur.

positionOf

open fun positionOf(@Nullable v: View?): Int

Returns the position of the given View in the list.

Parameters
v View?: The View to check for.
Return
Int: The position or -1 if the given View is null or not in the list.

removeItemDecoration

open fun removeItemDecoration(@NonNull decor: RecyclerView.ItemDecoration): Unit

Removes the given RecyclerView.ItemDecoration from this PagedListView.

The decoration will function the same as the item decoration for a RecyclerView.

Parameters
decor RecyclerView.ItemDecoration: The decoration to remove.

removeOnItemTouchListener

open fun removeOnItemTouchListener(@NonNull touchListener: RecyclerView.OnItemTouchListener): Unit

Removes the given RecyclerView.OnItemTouchListener from the PagedListView.

Parameters
touchListener RecyclerView.OnItemTouchListener: The touch listener to remove.

scrollToPosition

open fun scrollToPosition(position: Int): Unit

Scrolls to the given position in the PagedListView.

Parameters
position Int: The position in the list to scroll to.

setAdapter

open fun setAdapter(@NonNull adapter: RecyclerView.Adapter<out RecyclerView.ViewHolder!>): Unit

Sets the adapter for the list.

The given Adapter can implement ItemCap if it wishes to control the behavior of a max number of items. Otherwise, methods in the PagedListView to limit the content, such as setMaxPages(int), will do nothing.

setDividerColor

open fun setDividerColor(@ColorRes dividerColor: Int): Unit

Sets the color that should be used for the dividers in the PagedListView.

Parameters
dividerColor Int: The resource identifier for the divider color.

setDividerVisibilityManager

open fun setDividerVisibilityManager(dvm: PagedListView.DividerVisibilityManager!): Unit

Sets DividerVisibilityManager on all DividerDecoration item decorations.

Parameters
dvm PagedListView.DividerVisibilityManager!: DividerVisibilityManager to be set.

setDownButtonIcon

open fun setDownButtonIcon(icon: Drawable!): Unit

Sets the icon to be used for the down button.

setGutter

open fun setGutter(gutter: Int): Unit

Set the gutter to the specified value.

The gutter is the space to the start/end of the list view items and will be equal in size to the scroll bars. By default, there is a gutter to both the left and right of the list view items, to account for the scroll bar.

Parameters
gutter Int: A Gutter value that identifies which sides to apply the gutter to.

setGutterSize

open fun setGutterSize(gutterSize: Int): Unit

Sets the size of the gutter that appears at the start, end or both sizes of the items in the PagedListView.

Note, that if the gutter size given is smaller than the width of the scroll bar container set via setScrollBarContainerWidth(int), then the container width will be used as the gutter at the start. This ensures the scroll bar is never overlapped.

Parameters
gutterSize Int: The size of the gutter in pixels.

See Also

setItemSpacing

open fun setItemSpacing(itemSpacing: Int): Unit

Sets spacing between each item in the list. The spacing will not be added before the first item and after the last.

Parameters
itemSpacing Int: the spacing between each item.

setListContentBottomOffset

open fun setListContentBottomOffset(@Px offset: Int): Unit

Sets an offset after the last item in the PagedListView. This offset is scrollable with the contents of the list.

Parameters
offset Int: The bottom offset to add in pixels R.attr#listContentBottomOffset

setListContentTopOffset

open fun setListContentTopOffset(@Px offset: Int): Unit

Sets an offset above the first item in the PagedListView. This offset is scrollable with the contents of the list.

Parameters
offset Int: The top offset to add in pixels. R.attr#listContentTopOffset

setMaxPages

open fun setMaxPages(maxPages: Int): Unit

Sets the maximum number of the pages that can be shown in the PagedListView. The size of a page is defined as the number of items that fit completely on the screen at once.

Passing UNLIMITED_PAGES will remove any restrictions on a maximum number of pages. By default, there is no restriction on the number of pages.

Note that for any restriction on maximum pages to work, the adapter passed to this PagedListView needs to implement ItemCap.

Parameters
maxPages Int: The maximum number of pages that fit on the screen. Should be positive or UNLIMITED_PAGES.

setOnScrollListener

open fun setOnScrollListener(listener: PagedListView.OnScrollListener!): Unit

Sets the OnScrollListener that will be notified of scroll events within the PagedListView.

Parameters
listener PagedListView.OnScrollListener!: The scroll listener to set.

setScrollBarContainerWidth

open fun setScrollBarContainerWidth(width: Int): Unit

Sets the width of the container that holds the scrollbar. The scrollbar will be centered within this width.

Parameters
width Int: The width of the scrollbar container.

setScrollBarTopMargin

open fun setScrollBarTopMargin(topMargin: Int): Unit

Sets the top margin above the scroll bar. By default, this margin is 0.

Parameters
topMargin Int: The top margin.

setScrollbarThumbEnabled

open fun setScrollbarThumbEnabled(show: Boolean): Unit

Set the visibility of scroll bar thumb in the scroll bar, the default visibility is true.

Parameters
show Boolean: Whether to show the scrollbar thumb or not.

setUpButtonIcon

open fun setUpButtonIcon(icon: Drawable!): Unit

Sets the icon to be used for the up button.

showAlphaJump

open fun showAlphaJump(): Unit

Show the Alpha Jump Overlay.

snapToPosition

open fun snapToPosition(position: Int): Unit

Snap to the given position. This method will snap instantly to a position that's "close" to the given position and then animate a short decelerate to indicate the direction that the snap happened.

Parameters
position Int: The position in the list to scroll to.

Protected methods

dispatchRestoreInstanceState

protected open fun dispatchRestoreInstanceState(container: SparseArray<Parcelable!>!): Unit

dispatchSaveInstanceState

protected open fun dispatchSaveInstanceState(container: SparseArray<Parcelable!>!): Unit

onDetachedFromWindow

protected open fun onDetachedFromWindow(): Unit