Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

belongs to Maven artifact androidx.car:car:1.0.0-alpha5

PagedListView

public class PagedListView
extends FrameLayout

java.lang.Object
   ↳ 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

interface PagedListView.DividerVisibilityManager

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

@interface PagedListView.Gutter

The possible values for @{link #setGutter}. 

interface PagedListView.ItemCap

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

interface PagedListView.ItemPositionOffset

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

class PagedListView.OnScrollListener

Used to listen for PagedListView scroll events. 

Constants

int DEFAULT_MAX_CLICKS

Default maximum number of clicks allowed on a list

int UNLIMITED_PAGES

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

Inherited constants

Inherited fields

Public constructors

PagedListView(Context context)
PagedListView(Context context, AttributeSet attrs)
PagedListView(Context context, AttributeSet attrs, int defStyleAttrs)
PagedListView(Context context, AttributeSet attrs, int defStyleAttrs, int defStyleRes)

Public methods

void addItemDecoration(RecyclerView.ItemDecoration decor)

Adds an RecyclerView.ItemDecoration to this PagedListView.

void addOnItemTouchListener(RecyclerView.OnItemTouchListener touchListener)

Adds an RecyclerView.OnItemTouchListener to this PagedListView.

Adapter<? extends RecyclerView.ViewHolder> getAdapter()
int getMaxPages()

Returns the maximum number of pages allowed in the PagedListView.

int getPage(int position)

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

RecyclerView getRecyclerView()
int getRowsPerPage()

Gets the number of rows per page.

boolean isAtEnd()

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

boolean isAtStart()

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

void onLayout(boolean changed, int left, int top, int right, int bottom)
void onRestoreInstanceState(Parcelable state)
Parcelable onSaveInstanceState()
void pageDown()

Scrolls the contents of the RecyclerView down a page.

void pageUp()

Scrolls the contents of the RecyclerView up a page.

int positionOf(View v)

Returns the position of the given View in the list.

void removeItemDecoration(RecyclerView.ItemDecoration decor)

Removes the given RecyclerView.ItemDecoration from this PagedListView.

void removeOnItemTouchListener(RecyclerView.OnItemTouchListener touchListener)

Removes the given RecyclerView.OnItemTouchListener from the PagedListView.

void resetMaxPages()

Resets the maximum number of pages to be shown to be the default.

void resetScrollbarColor()

Resets the color of scrollbar to default.

void scrollToPosition(int position)

Scrolls to the given position in the PagedListView.

void setAdapter(Adapter<? extends RecyclerView.ViewHolder> adapter)

Sets the adapter for the list.

void setDayNightStyle(int dayNightStyle)

Sets how this PagedListView responds to day/night configuration changes.

void setDefaultMaxPages(int newDefault)

Sets the default number of pages that this PagedListView is limited to.

void setDividerVisibilityManager(PagedListView.DividerVisibilityManager dvm)

Sets PagedListView.DividerVisibilityManager on all DividerDecoration item decorations.

void setDownButtonIcon(Drawable icon)

Sets the icon to be used for the down button.

void setGutter(int gutter)

Set the gutter to the specified value.

void setGutterSize(int gutterSize)

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

void setItemSpacing(int itemSpacing)

Sets spacing between each item in the list.

void setListContentTopOffset(int offset)

Sets an offset above the first item in the PagedListView.

void setMaxPages(int maxPages)

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

void setOnScrollListener(PagedListView.OnScrollListener listener)

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

void setScrollBarContainerWidth(int width)

Sets the width of the container that holds the scrollbar.

void setScrollBarTopMargin(int topMargin)

Sets the top margin above the scroll bar.

void setScrollbarColor(int color)

Sets the color of scrollbar.

void setUpButtonIcon(Drawable icon)

Sets the icon to be used for the up button.

void snapToPosition(int position)

Snap to the given position.

Protected methods

void dispatchRestoreInstanceState(SparseArray<Parcelable> container)
void dispatchSaveInstanceState(SparseArray<Parcelable> container)
void onDetachedFromWindow()

Inherited methods

Constants

DEFAULT_MAX_CLICKS

public static final int DEFAULT_MAX_CLICKS

Default maximum number of clicks allowed on a list

Constant Value: 6 (0x00000006)

UNLIMITED_PAGES

public static final int UNLIMITED_PAGES

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

Constant Value: -1 (0xffffffff)

Public constructors

PagedListView

public PagedListView (Context context)

Parameters
context Context

PagedListView

public PagedListView (Context context, 
                AttributeSet attrs)

Parameters
context Context

attrs AttributeSet

PagedListView

public PagedListView (Context context, 
                AttributeSet attrs, 
                int defStyleAttrs)

Parameters
context Context

attrs AttributeSet

defStyleAttrs int

PagedListView

public PagedListView (Context context, 
                AttributeSet attrs, 
                int defStyleAttrs, 
                int defStyleRes)

Parameters
context Context

attrs AttributeSet

defStyleAttrs int

defStyleRes int

Public methods

addItemDecoration

public void addItemDecoration (RecyclerView.ItemDecoration decor)

Adds an RecyclerView.ItemDecoration to this PagedListView.

Parameters
decor RecyclerView.ItemDecoration: The decoration to add.

addOnItemTouchListener

public void addOnItemTouchListener (RecyclerView.OnItemTouchListener touchListener)

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

public Adapter<? extends RecyclerView.ViewHolder> getAdapter ()

Returns
Adapter<? extends RecyclerView.ViewHolder>

getMaxPages

public int getMaxPages ()

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.

Returns
int The maximum number of pages to be shown or UNLIMITED_PAGES if there is no limit.

getPage

public int getPage (int position)

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

Parameters
position int

Returns
int

getRecyclerView

public RecyclerView getRecyclerView ()

Returns
RecyclerView

getRowsPerPage

public int getRowsPerPage ()

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.

Returns
int

isAtEnd

public boolean isAtEnd ()

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

Returns
boolean

isAtStart

public boolean isAtStart ()

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

Returns
boolean

onLayout

public void onLayout (boolean changed, 
                int left, 
                int top, 
                int right, 
                int bottom)

Parameters
changed boolean

left int

top int

right int

bottom int

onRestoreInstanceState

public void onRestoreInstanceState (Parcelable state)

Parameters
state Parcelable

onSaveInstanceState

public Parcelable onSaveInstanceState ()

Returns
Parcelable

pageDown

public void pageDown ()

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

public void pageUp ()

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

public int positionOf (View v)

Returns the position of the given View in the list.

Parameters
v View: The View to check for.

Returns
int The position or -1 if the given View is null or not in the list.

removeItemDecoration

public void removeItemDecoration (RecyclerView.ItemDecoration decor)

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

public void removeOnItemTouchListener (RecyclerView.OnItemTouchListener touchListener)

Removes the given RecyclerView.OnItemTouchListener from the PagedListView.

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

resetMaxPages

public void resetMaxPages ()

Resets the maximum number of pages to be shown to be the default.

resetScrollbarColor

public void resetScrollbarColor ()

Resets the color of scrollbar to default.

scrollToPosition

public void scrollToPosition (int position)

Scrolls to the given position in the PagedListView.

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

setAdapter

public void setAdapter (Adapter<? extends RecyclerView.ViewHolder> adapter)

Sets the adapter for the list.

The given Adapter can implement PagedListView.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.

Parameters
adapter Adapter

setDayNightStyle

public void setDayNightStyle (int dayNightStyle)

Sets how this PagedListView responds to day/night configuration changes. By default, the PagedListView is darker in the day and lighter at night.

Parameters
dayNightStyle int: A value from DayNightStyle.

See also:

setDefaultMaxPages

public void setDefaultMaxPages (int newDefault)

Sets the default number of pages that this PagedListView is limited to.

Parameters
newDefault int: The default number of pages. Should be positive.

setDividerVisibilityManager

public void setDividerVisibilityManager (PagedListView.DividerVisibilityManager dvm)

Sets PagedListView.DividerVisibilityManager on all DividerDecoration item decorations.

Parameters
dvm PagedListView.DividerVisibilityManager: DividerVisibilityManager to be set.

setDownButtonIcon

public void setDownButtonIcon (Drawable icon)

Sets the icon to be used for the down button.

Parameters
icon Drawable

setGutter

public void setGutter (int gutter)

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 PagedListView.Gutter value that identifies which sides to apply the gutter to.

setGutterSize

public void setGutterSize (int gutterSize)

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

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

See also:

setItemSpacing

public void setItemSpacing (int itemSpacing)

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.

setListContentTopOffset

public void setListContentTopOffset (int offset)

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.

setMaxPages

public void setMaxPages (int maxPages)

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.

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

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

setOnScrollListener

public void setOnScrollListener (PagedListView.OnScrollListener listener)

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

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

setScrollBarContainerWidth

public void setScrollBarContainerWidth (int width)

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

public void setScrollBarTopMargin (int topMargin)

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

Parameters
topMargin int: The top margin.

setScrollbarColor

public void setScrollbarColor (int color)

Sets the color of scrollbar.

Custom color ignores DayNightStyle. Calling resetScrollbarColor() resets to default color.

Parameters
color int: Resource identifier of the color.

setUpButtonIcon

public void setUpButtonIcon (Drawable icon)

Sets the icon to be used for the up button.

Parameters
icon Drawable

snapToPosition

public void snapToPosition (int position)

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 void dispatchRestoreInstanceState (SparseArray<Parcelable> container)

Parameters
container SparseArray

dispatchSaveInstanceState

protected void dispatchSaveInstanceState (SparseArray<Parcelable> container)

Parameters
container SparseArray

onDetachedFromWindow

protected void onDetachedFromWindow ()