StaggeredGridLayoutManager

open class StaggeredGridLayoutManager : RecyclerView.LayoutManager, RecyclerView.SmoothScroller.ScrollVectorProvider
kotlin.Any
   ↳ androidx.recyclerview.widget.RecyclerView.LayoutManager
   ↳ androidx.recyclerview.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
open

LayoutParams used by StaggeredGridLayoutManager.

Constants
static Int

static Int

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

static Int

Does not do anything to hide gaps.

static Int

static Int

Public constructors
<init>(context: Context!, attrs: AttributeSet!, defStyleAttr: Int, defStyleRes: Int)

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

<init>(spanCount: Int, orientation: Int)

Creates a StaggeredGridLayoutManager with given parameters.

Public methods
open Int

open IntArray!

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

open Unit
onItemsAdded(recyclerView: RecyclerView, positionStart: Int, itemCount: Int)

open Int

open Int

open Unit

open Int

open Int

Returns the current gap handling strategy for StaggeredGridLayoutManager.

open Int

open Int

open Unit
scrollToPositionWithOffset(position: Int, offset: Int)

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

open Int

open Int

open Unit
onItemsRemoved(recyclerView: RecyclerView, positionStart: Int, itemCount: Int)

open IntArray!

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

open IntArray!

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

open Unit

open Unit

open Unit
scrollToPosition(position: Int)

open Int

open RecyclerView.LayoutParams!

open RecyclerView.LayoutParams!

open Boolean

open Boolean

open Unit
onInitializeAccessibilityNodeInfoForItem(recycler: RecyclerView.Recycler, state: RecyclerView.State, host: View, info: AccessibilityNodeInfoCompat)

open Unit

open Unit
setGapStrategy(gapStrategy: Int)

Sets the gap handling strategy for StaggeredGridLayoutManager.

open View?
onFocusSearchFailed(focused: View, direction: Int, recycler: RecyclerView.Recycler, state: RecyclerView.State)

open IntArray!

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

open Unit
smoothScrollToPosition(recyclerView: RecyclerView!, state: RecyclerView.State!, position: Int)

open Unit

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

open Boolean

open Boolean

open Unit
onItemsMoved(recyclerView: RecyclerView, from: Int, to: Int, itemCount: Int)

open Unit
setSpanCount(spanCount: Int)

Sets the number of spans for the layout.

open Parcelable?

open Unit

open Int

Returns the number of spans laid out by StaggeredGridLayoutManager.

open Unit

open Int

open PointF?

open Int

open RecyclerView.LayoutParams!

open Unit

open Unit
setOrientation(orientation: Int)

Sets the orientation of the layout.

open Boolean

open Unit
onItemsUpdated(recyclerView: RecyclerView, positionStart: Int, itemCount: Int, payload: Any?)

open Unit

open Boolean

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

open Unit

open Unit
setMeasuredDimension(childrenBounds: Rect!, wSpec: Int, hSpec: Int)

open Unit

open Unit
setReverseLayout(reverseLayout: Boolean)

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

open Unit

Inherited functions

Constants

GAP_HANDLING_LAZY

static val GAP_HANDLING_LAZY: Int
Value: 1

GAP_HANDLING_MOVE_ITEMS_BETWEEN_SPANS

static val GAP_HANDLING_MOVE_ITEMS_BETWEEN_SPANS: Int

When scroll state is changed to RecyclerView#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 
Value: 2

GAP_HANDLING_NONE

static val GAP_HANDLING_NONE: Int

Does not do anything to hide gaps.

Value: 0

HORIZONTAL

static val HORIZONTAL: Int
Value: 0

VERTICAL

static val VERTICAL: Int
Value: 1

Public constructors

<init>

StaggeredGridLayoutManager(context: Context!, attrs: AttributeSet!, defStyleAttr: Int, defStyleRes: Int)

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

<init>

StaggeredGridLayoutManager(spanCount: Int, orientation: Int)

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

computeVerticalScrollExtent

open fun computeVerticalScrollExtent(state: RecyclerView.State): Int

findLastCompletelyVisibleItemPositions

open fun findLastCompletelyVisibleItemPositions(into: IntArray!): IntArray!

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

Note that, this value is not affected by layout orientation or item order traversal. (#setReverseLayout(boolean)). Views are sorted by their positions in the adapter, not in the layout.

If RecyclerView has item decorators, they will be considered in calculations as well.

StaggeredGridLayoutManager may pre-cache some views that are not necessarily visible. Those views are ignored in this method.

Parameters
into IntArray!: An array to put the results into. If you don't provide any, LayoutManager will create a new one.
Return
IntArray!: The adapter position of the last fully visible item in each span. If a span does not have any items, RecyclerView#NO_POSITION is returned for that span.

onItemsAdded

open fun onItemsAdded(recyclerView: RecyclerView, positionStart: Int, itemCount: Int): Unit

computeVerticalScrollRange

open fun computeVerticalScrollRange(state: RecyclerView.State): Int

computeHorizontalScrollExtent

open fun computeHorizontalScrollExtent(state: RecyclerView.State): Int

onInitializeAccessibilityEvent

open fun onInitializeAccessibilityEvent(event: AccessibilityEvent): Unit

computeHorizontalScrollRange

open fun computeHorizontalScrollRange(state: RecyclerView.State): Int

getGapStrategy

open fun getGapStrategy(): Int

Returns the current gap handling strategy for StaggeredGridLayoutManager.

Staggered grid may have gaps in the layout due to changes in the adapter. To avoid gaps, StaggeredGridLayoutManager provides 2 options. Check #GAP_HANDLING_NONE and #GAP_HANDLING_MOVE_ITEMS_BETWEEN_SPANS for details.

By default, StaggeredGridLayoutManager uses #GAP_HANDLING_MOVE_ITEMS_BETWEEN_SPANS.

Return
Int: Current gap handling strategy.

scrollHorizontallyBy

open fun scrollHorizontallyBy(dx: Int, recycler: RecyclerView.Recycler!, state: RecyclerView.State!): Int

getRowCountForAccessibility

open fun getRowCountForAccessibility(recycler: RecyclerView.Recycler, state: RecyclerView.State): Int

scrollToPositionWithOffset

open fun scrollToPositionWithOffset(position: Int, offset: Int): Unit

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

Note that scroll position change will not be reflected until the next layout call.

If you are just trying to make a position visible, use #scrollToPosition(int).

Parameters
position Int: Index (starting at 0) of the reference item.
offset Int: The distance (in pixels) between the start edge of the item view and start edge of the RecyclerView.

scrollVerticallyBy

open fun scrollVerticallyBy(dy: Int, recycler: RecyclerView.Recycler!, state: RecyclerView.State!): Int

computeVerticalScrollOffset

open fun computeVerticalScrollOffset(state: RecyclerView.State): Int

onItemsRemoved

open fun onItemsRemoved(recyclerView: RecyclerView, positionStart: Int, itemCount: Int): Unit

findFirstCompletelyVisibleItemPositions

open fun findFirstCompletelyVisibleItemPositions(into: IntArray!): IntArray!

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

Note that, this value is not affected by layout orientation or item order traversal. (#setReverseLayout(boolean)). Views are sorted by their positions in the adapter, not in the layout.

If RecyclerView has item decorators, they will be considered in calculations as well.

StaggeredGridLayoutManager may pre-cache some views that are not necessarily visible. Those views are ignored in this method.

Parameters
into IntArray!: An array to put the results into. If you don't provide any, LayoutManager will create a new one.
Return
IntArray!: The adapter position of the first fully visible item in each span. If a span does not have any items, RecyclerView#NO_POSITION is returned for that span.

findLastVisibleItemPositions

open fun findLastVisibleItemPositions(into: IntArray!): IntArray!

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

Note that, this value is not affected by layout orientation or item order traversal. (#setReverseLayout(boolean)). Views are sorted by their positions in the adapter, not in the layout.

If RecyclerView has item decorators, they will be considered in calculations as well.

StaggeredGridLayoutManager may pre-cache some views that are not necessarily visible. Those views are ignored in this method.

Parameters
into IntArray!: An array to put the results into. If you don't provide any, LayoutManager will create a new one.
Return
IntArray!: The adapter position of the last visible item in each span. If a span does not have any items, RecyclerView#NO_POSITION is returned for that span.

offsetChildrenHorizontal

open fun offsetChildrenHorizontal(dx: Int): Unit

collectAdjacentPrefetchPositions

open fun collectAdjacentPrefetchPositions(dx: Int, dy: Int, state: RecyclerView.State!, layoutPrefetchRegistry: RecyclerView.LayoutManager.LayoutPrefetchRegistry!): Unit
Parameters
dx Int: X movement component.
dy Int: Y movement component.
state Int: State of RecyclerView
layoutPrefetchRegistry Int: PrefetchRegistry to add prefetch entries into.

scrollToPosition

open fun scrollToPosition(position: Int): Unit

computeHorizontalScrollOffset

open fun computeHorizontalScrollOffset(state: RecyclerView.State): Int

generateLayoutParams

open fun generateLayoutParams(c: Context!, attrs: AttributeSet!): RecyclerView.LayoutParams!

generateLayoutParams

open fun generateLayoutParams(lp: LayoutParams!): RecyclerView.LayoutParams!

isAutoMeasureEnabled

open fun isAutoMeasureEnabled(): Boolean

checkLayoutParams

open fun checkLayoutParams(lp: RecyclerView.LayoutParams!): Boolean

onInitializeAccessibilityNodeInfoForItem

open fun onInitializeAccessibilityNodeInfoForItem(recycler: RecyclerView.Recycler, state: RecyclerView.State, host: View, info: AccessibilityNodeInfoCompat): Unit

onLayoutCompleted

open fun onLayoutCompleted(state: RecyclerView.State!): Unit

setGapStrategy

open fun setGapStrategy(gapStrategy: Int): Unit

Sets the gap handling strategy for StaggeredGridLayoutManager. If the gapStrategy parameter is different than the current strategy, calling this method will trigger a layout request.

Parameters
gapStrategy Int: The new gap handling strategy. Should be #GAP_HANDLING_MOVE_ITEMS_BETWEEN_SPANS or .

onFocusSearchFailed

open fun onFocusSearchFailed(focused: View, direction: Int, recycler: RecyclerView.Recycler, state: RecyclerView.State): View?

findFirstVisibleItemPositions

open fun findFirstVisibleItemPositions(into: IntArray!): IntArray!

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

Note that, this value is not affected by layout orientation or item order traversal. (#setReverseLayout(boolean)). Views are sorted by their positions in the adapter, not in the layout.

If RecyclerView has item decorators, they will be considered in calculations as well.

StaggeredGridLayoutManager may pre-cache some views that are not necessarily visible. Those views are ignored in this method.

Parameters
into IntArray!: An array to put the results into. If you don't provide any, LayoutManager will create a new one.
Return
IntArray!: The adapter position of the first visible item in each span. If a span does not have any items, RecyclerView#NO_POSITION is returned for that span.

smoothScrollToPosition

open fun smoothScrollToPosition(recyclerView: RecyclerView!, state: RecyclerView.State!, position: Int): Unit

invalidateSpanAssignments

open fun invalidateSpanAssignments(): Unit

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

If you need to cancel current assignments, you can call this method which will clear all assignments and request a new layout.

canScrollVertically

open fun canScrollVertically(): Boolean

supportsPredictiveItemAnimations

open fun supportsPredictiveItemAnimations(): Boolean

onItemsMoved

open fun onItemsMoved(recyclerView: RecyclerView, from: Int, to: Int, itemCount: Int): Unit

setSpanCount

open fun setSpanCount(spanCount: Int): Unit

Sets the number of spans for the layout. This will invalidate all of the span assignments for Views.

Calling this method will automatically result in a new layout request unless the spanCount parameter is equal to current span count.

Parameters
spanCount Int: Number of spans to layout

onSaveInstanceState

open fun onSaveInstanceState(): Parcelable?

assertNotInLayoutOrScroll

open fun assertNotInLayoutOrScroll(message: String!): Unit

getSpanCount

open fun getSpanCount(): Int

Returns the number of spans laid out by StaggeredGridLayoutManager.

Return
Int: Number of spans in the layout

onDetachedFromWindow

open fun onDetachedFromWindow(view: RecyclerView!, recycler: RecyclerView.Recycler!): Unit

getOrientation

open fun getOrientation(): Int

computeScrollVectorForPosition

open fun computeScrollVectorForPosition(targetPosition: Int): PointF?

getColumnCountForAccessibility

open fun getColumnCountForAccessibility(recycler: RecyclerView.Recycler, state: RecyclerView.State): Int

generateDefaultLayoutParams

open fun generateDefaultLayoutParams(): RecyclerView.LayoutParams!

onItemsChanged

open fun onItemsChanged(recyclerView: RecyclerView): Unit

setOrientation

open fun setOrientation(orientation: Int): Unit

Sets the orientation of the layout. StaggeredGridLayoutManager will do its best to keep scroll position if this method is called after views are laid out.

Parameters
orientation Int: #HORIZONTAL or #VERTICAL

canScrollHorizontally

open fun canScrollHorizontally(): Boolean

onItemsUpdated

open fun onItemsUpdated(recyclerView: RecyclerView, positionStart: Int, itemCount: Int, payload: Any?): Unit

onRestoreInstanceState

open fun onRestoreInstanceState(state: Parcelable!): Unit

getReverseLayout

open fun getReverseLayout(): Boolean

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

Not that this value is not affected by RecyclerView's layout direction.

Return
Boolean: True if layout is reversed, false otherwise

offsetChildrenVertical

open fun offsetChildrenVertical(dy: Int): Unit

setMeasuredDimension

open fun setMeasuredDimension(childrenBounds: Rect!, wSpec: Int, hSpec: Int): Unit

onLayoutChildren

open fun onLayoutChildren(recycler: RecyclerView.Recycler!, state: RecyclerView.State!): Unit

setReverseLayout

open fun setReverseLayout(reverseLayout: Boolean): Unit

Sets whether LayoutManager should start laying out items from the end of the UI. The order items are traversed is not affected by this call.

For vertical layout, if it is set to true, first item will be at the bottom of the list.

For horizontal layouts, it depends on the layout direction. When set to true, If RecyclerView is LTR, than it will layout from RTL, if RecyclerView} is RTL, it will layout from LTR.

Parameters
reverseLayout Boolean: Whether layout should be in reverse or not

onScrollStateChanged

open fun onScrollStateChanged(state: Int): Unit