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

static Int

Does not do anything to hide gaps.

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.

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 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 Unit

open Int

open Int

Returns the current gap handling strategy for StaggeredGridLayoutManager.

open Int

open Int

open IntArray!

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

open Unit

open Unit
scrollToPosition(position: Int)

open RecyclerView.LayoutParams!

open RecyclerView.LayoutParams!

open Unit

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

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 Unit
onItemsMoved(recyclerView: RecyclerView, from: Int, to: Int, itemCount: Int)

open Int

open Unit

open Unit
setOrientation(orientation: Int)

Sets the orientation of the layout.

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

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
setReverseLayout(reverseLayout: Boolean)

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

open Unit

open Int

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 Unit
onItemsRemoved(recyclerView: RecyclerView, positionStart: Int, itemCount: Int)

open IntArray!

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

open Int

open Boolean

open Boolean

open Unit

open Unit
setGapStrategy(gapStrategy: Int)

Sets the gap handling strategy for StaggeredGridLayoutManager.

open IntArray!

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

open Boolean

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 RecyclerView.LayoutParams!

open Boolean

open Unit

open Unit

Inherited functions

Constants

HORIZONTAL

static val HORIZONTAL: Int
Value: RecyclerView.HORIZONTAL

VERTICAL

static val VERTICAL: Int
Value: RecyclerView.VERTICAL

GAP_HANDLING_NONE

static val GAP_HANDLING_NONE: Int

Does not do anything to hide gaps.

Value: 0

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

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

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

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

scrollVerticallyBy

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

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

scrollToPosition

open fun scrollToPosition(position: Int): Unit

generateLayoutParams

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

generateLayoutParams

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

onInitializeAccessibilityNodeInfoForItem

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

onFocusSearchFailed

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

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.

supportsPredictiveItemAnimations

open fun supportsPredictiveItemAnimations(): Boolean

onItemsMoved

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

getColumnCountForAccessibility

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

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

onItemsUpdated

open fun onItemsUpdated(recyclerView: RecyclerView, positionStart: Int, itemCount: Int, payload: Any?): 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

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

computeVerticalScrollExtent

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

computeHorizontalScrollExtent

open fun computeHorizontalScrollExtent(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.

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.

computeHorizontalScrollOffset

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

isAutoMeasureEnabled

open fun isAutoMeasureEnabled(): Boolean

checkLayoutParams

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

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 .

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.

canScrollVertically

open fun canScrollVertically(): Boolean

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?

generateDefaultLayoutParams

open fun generateDefaultLayoutParams(): RecyclerView.LayoutParams!

canScrollHorizontally

open fun canScrollHorizontally(): Boolean

onRestoreInstanceState

open fun onRestoreInstanceState(state: Parcelable!): Unit

onLayoutChildren

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