Stay organized with collections Save and categorize content based on your preferences.
added in version 22.1.0
belongs to Maven artifact com.android.support:recyclerview-v7:28.0.0-alpha1

StaggeredGridLayoutManager

public class StaggeredGridLayoutManager
extends RecyclerView.LayoutManager implements RecyclerView.SmoothScroller.ScrollVectorProvider

java.lang.Object
   ↳ android.support.v7.widget.RecyclerView.LayoutManager
     ↳ android.support.v7.widget.StaggeredGridLayoutManager


A LayoutManager that lays out children in a staggered grid formation. It supports horizontal & vertical layout as well as an ability to layout children in reverse.

Staggered grids are likely to have gaps at the edges of the layout. To avoid these gaps, StaggeredGridLayoutManager can offset spans independently or move items between spans. You can control this behavior via setGapStrategy(int).

Summary

Nested classes

class StaggeredGridLayoutManager.LayoutParams

LayoutParams used by StaggeredGridLayoutManager. 

Inherited XML attributes

From class android.support.v7.widget.RecyclerView.LayoutManager

Constants

int GAP_HANDLING_LAZY

This constant was deprecated in API level 22.1.0. No longer supported.

int GAP_HANDLING_MOVE_ITEMS_BETWEEN_SPANS

When scroll state is changed to SCROLL_STATE_IDLE, StaggeredGrid will check if there are gaps in the because of full span items.

int GAP_HANDLING_NONE

Does not do anything to hide gaps.

int HORIZONTAL

int VERTICAL

Public constructors

StaggeredGridLayoutManager(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

Constructor used when layout manager is set in XML by RecyclerView attribute "layoutManager".

StaggeredGridLayoutManager(int spanCount, int orientation)

Creates a StaggeredGridLayoutManager with given parameters.

Public methods

void assertNotInLayoutOrScroll(String message)

Checks if RecyclerView is in the middle of a layout or scroll and throws an IllegalStateException if it is.

boolean canScrollHorizontally()

Query if horizontal scrolling is currently supported.

boolean canScrollVertically()

Query if vertical scrolling is currently supported.

boolean checkLayoutParams(RecyclerView.LayoutParams lp)

Determines the validity of the supplied LayoutParams object.

int computeHorizontalScrollExtent(RecyclerView.State state)

Override this method if you want to support scroll bars.

int computeHorizontalScrollOffset(RecyclerView.State state)

Override this method if you want to support scroll bars.

int computeHorizontalScrollRange(RecyclerView.State state)

Override this method if you want to support scroll bars.

PointF computeScrollVectorForPosition(int targetPosition)

Should calculate the vector that points to the direction where the target position can be found.

int computeVerticalScrollExtent(RecyclerView.State state)

Override this method if you want to support scroll bars.

int computeVerticalScrollOffset(RecyclerView.State state)

Override this method if you want to support scroll bars.

int computeVerticalScrollRange(RecyclerView.State state)

Override this method if you want to support scroll bars.

int[] findFirstCompletelyVisibleItemPositions(int[] into)

Returns the adapter position of the first completely visible view for each span.

int[] findFirstVisibleItemPositions(int[] into)

Returns the adapter position of the first visible view for each span.

int[] findLastCompletelyVisibleItemPositions(int[] into)

Returns the adapter position of the last completely visible view for each span.

int[] findLastVisibleItemPositions(int[] into)

Returns the adapter position of the last visible view for each span.

RecyclerView.LayoutParams generateDefaultLayoutParams()

Create a default LayoutParams object for a child of the RecyclerView.

RecyclerView.LayoutParams generateLayoutParams(Context c, AttributeSet attrs)

Create a LayoutParams object suitable for this LayoutManager from an inflated layout resource.

RecyclerView.LayoutParams generateLayoutParams(ViewGroup.LayoutParams lp)

Create a LayoutParams object suitable for this LayoutManager, copying relevant values from the supplied LayoutParams object if possible.

int getColumnCountForAccessibility(RecyclerView.Recycler recycler, RecyclerView.State state)

Returns the number of columns for accessibility.

int getGapStrategy()

Returns the current gap handling strategy for StaggeredGridLayoutManager.

int getOrientation()
boolean getReverseLayout()

Returns whether views are laid out in reverse order or not.

int getRowCountForAccessibility(RecyclerView.Recycler recycler, RecyclerView.State state)

Returns the number of rows for accessibility.

int getSpanCount()

Returns the number of spans laid out by StaggeredGridLayoutManager.

void invalidateSpanAssignments()

For consistency, StaggeredGridLayoutManager keeps a mapping between spans and items.

boolean isAutoMeasureEnabled()

Returns whether the measuring pass of layout should use the AutoMeasure mechanism of RecyclerView or if it should be done by the LayoutManager's implementation of onMeasure(Recycler, State, int, int).

void offsetChildrenHorizontal(int dx)

Offset all child views attached to the parent RecyclerView by dx pixels along the horizontal axis.

void offsetChildrenVertical(int dy)

Offset all child views attached to the parent RecyclerView by dy pixels along the vertical axis.

void onDetachedFromWindow(RecyclerView view, RecyclerView.Recycler recycler)

Called when this LayoutManager is detached from its parent RecyclerView or when its parent RecyclerView is detached from its window.

View onFocusSearchFailed(View focused, int direction, RecyclerView.Recycler recycler, RecyclerView.State state)

Called when searching for a focusable view in the given direction has failed for the current content of the RecyclerView.

void onInitializeAccessibilityEvent(AccessibilityEvent event)
void onInitializeAccessibilityNodeInfoForItem(RecyclerView.Recycler recycler, RecyclerView.State state, View host, AccessibilityNodeInfoCompat info)

Called by the AccessibilityDelegate when the accessibility information for a specific item should be populated.

void onItemsAdded(RecyclerView recyclerView, int positionStart, int itemCount)

Called when items have been added to the adapter.

void onItemsChanged(RecyclerView recyclerView)

Called in response to a call to notifyDataSetChanged() or swapAdapter(Adapter, boolean) ()} and signals that the the entire data set has changed.

void onItemsMoved(RecyclerView recyclerView, int from, int to, int itemCount)

Called when an item is moved withing the adapter.

void onItemsRemoved(RecyclerView recyclerView, int positionStart, int itemCount)

Called when items have been removed from the adapter.

void onItemsUpdated(RecyclerView recyclerView, int positionStart, int itemCount, Object payload)

Called when items have been changed in the adapter and with optional payload.

void onLayoutChildren(RecyclerView.Recycler recycler, RecyclerView.State state)

Lay out all relevant child views from the given adapter.

void onLayoutCompleted(RecyclerView.State state)

Called after a full layout calculation is finished.

void onRestoreInstanceState(Parcelable state)
Parcelable onSaveInstanceState()

Called when the LayoutManager should save its state.

void onScrollStateChanged(int state)

RecyclerView calls this method to notify LayoutManager that scroll state has changed.

int scrollHorizontallyBy(int dx, RecyclerView.Recycler recycler, RecyclerView.State state)

Scroll horizontally by dx pixels in screen coordinates and return the distance traveled.

void scrollToPosition(int position)

Scroll to the specified adapter position.

void scrollToPositionWithOffset(int position, int offset)

Scroll to the specified adapter position with the given offset from layout start.

int scrollVerticallyBy(int dy, RecyclerView.Recycler recycler, RecyclerView.State state)

Scroll vertically by dy pixels in screen coordinates and return the distance traveled.

void setGapStrategy(int gapStrategy)

Sets the gap handling strategy for StaggeredGridLayoutManager.

void setMeasuredDimension(Rect childrenBounds, int wSpec, int hSpec)

Sets the measured dimensions from the given bounding box of the children and the measurement specs that were passed into onMeasure(int, int).

void setOrientation(int orientation)

Sets the orientation of the layout.

void setReverseLayout(boolean reverseLayout)

Sets whether LayoutManager should start laying out items from the end of the UI.

void setSpanCount(int spanCount)

Sets the number of spans for the layout.

void smoothScrollToPosition(RecyclerView recyclerView, RecyclerView.State state, int position)

Smooth scroll to the specified adapter position.

boolean supportsPredictiveItemAnimations()

Returns whether this LayoutManager supports "predictive item animations".

Inherited methods

From class android.support.v7.widget.RecyclerView.LayoutManager
From class java.lang.Object
From interface android.support.v7.widget.RecyclerView.SmoothScroller.ScrollVectorProvider

Constants

GAP_HANDLING_LAZY

added in version 22.1.0
int GAP_HANDLING_LAZY

This constant was deprecated in API level 22.1.0.
No longer supported.

Constant Value: 1 (0x00000001)

GAP_HANDLING_MOVE_ITEMS_BETWEEN_SPANS

added in version 22.1.0
int GAP_HANDLING_MOVE_ITEMS_BETWEEN_SPANS

When scroll state is changed to SCROLL_STATE_IDLE, StaggeredGrid will check if there are gaps in the because of full span items. If it finds, it will re-layout and move items to correct positions with animations.

For example, if LayoutManager ends up with the following layout due to adapter changes:

 AAA
 _BC
 DDD
 

It will animate to the following state:

 AAA
 BC_
 DDD
 

Constant Value: 2 (0x00000002)

GAP_HANDLING_NONE

added in version 22.1.0
int GAP_HANDLING_NONE

Does not do anything to hide gaps.

Constant Value: 0 (0x00000000)

HORIZONTAL

added in version 22.1.0
int HORIZONTAL

Constant Value: 0 (0x00000000)

VERTICAL

added in version 22.1.0
int VERTICAL

Constant Value: 1 (0x00000001)

Public constructors

StaggeredGridLayoutManager

added in version 24.1.0
StaggeredGridLayoutManager (Context context, 
                AttributeSet attrs, 
                int defStyleAttr, 
                int defStyleRes)

Constructor used when layout manager is set in XML by RecyclerView attribute "layoutManager". Defaults to single column and vertical.

Parameters
context Context

attrs AttributeSet

defStyleAttr int

defStyleRes int

StaggeredGridLayoutManager

added in version 22.1.0
StaggeredGridLayoutManager (int spanCount, 
                int orientation)

Creates a StaggeredGridLayoutManager with given parameters.

Parameters
spanCount int: If orientation is vertical, spanCount is number of columns. If orientation is horizontal, spanCount is number of rows.

orientation int: VERTICAL or HORIZONTAL

Public methods

assertNotInLayoutOrScroll

added in version 22.1.0
void assertNotInLayoutOrScroll (String message)

Checks if RecyclerView is in the middle of a layout or scroll and throws an IllegalStateException if it is.

Parameters
message String: The message for the exception. Can be null.

canScrollHorizontally

added in version 22.1.0
boolean canScrollHorizontally ()

Query if horizontal scrolling is currently supported. The default implementation returns false.

Returns
boolean True if this LayoutManager can scroll the current contents horizontally

canScrollVertically

added in version 22.1.0
boolean canScrollVertically ()

Query if vertical scrolling is currently supported. The default implementation returns false.

Returns
boolean True if this LayoutManager can scroll the current contents vertically

checkLayoutParams

added in version 22.1.0
boolean checkLayoutParams (RecyclerView.LayoutParams lp)

Determines the validity of the supplied LayoutParams object.

This should check to make sure that the object is of the correct type and all values are within acceptable ranges. The default implementation returns true for non-null params.

Parameters
lp RecyclerView.LayoutParams: LayoutParams object to check

Returns
boolean true if this LayoutParams object is valid, false otherwise

computeHorizontalScrollExtent

added in version 22.1.0
int computeHorizontalScrollExtent (RecyclerView.State state)

Override this method if you want to support scroll bars.

Read