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 Unit

open Boolean

open Boolean

open Boolean

open Int

open Int

open Int

open PointF?

open Int

open Int

open Int

open IntArray!

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

open IntArray!

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

open IntArray!

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

open IntArray!

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

open RecyclerView.LayoutParams!

open RecyclerView.LayoutParams!

open RecyclerView.LayoutParams!

open Int

open Int

Returns the current gap handling strategy for StaggeredGridLayoutManager.

open Int

open Boolean

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

open Int

open Int

Returns the number of spans laid out by StaggeredGridLayoutManager.

open Unit

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

open Boolean

open Unit

open Unit

open Unit

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

open Unit

open Unit

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

open Unit

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

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

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

open Unit

open Unit

open Unit

open Parcelable?

open Unit

open Int

open Unit
scrollToPosition(position: 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
setGapStrategy(gapStrategy: Int)

Sets the gap handling strategy for StaggeredGridLayoutManager.

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

open Unit
setOrientation(orientation: Int)

Sets the orientation of the layout.

open Unit
setReverseLayout(reverseLayout: Boolean)

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

open Unit
setSpanCount(spanCount: Int)

Sets the number of spans for the layout.

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

open Boolean

Inherited functions

Constants

GAP_HANDLING_LAZY

static val GAP_HANDLING_LAZY: Int

Deprecated: No longer supported.

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: RecyclerView.HORIZONTAL

VERTICAL

static val VERTICAL: Int
Value: RecyclerView.VERTICAL

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

assertNotInLayoutOrScroll

open fun assertNotInLayoutOrScroll(message: String!): Unit

canScrollHorizontally

open fun canScrollHorizontally(): Boolean

canScrollVertically

open fun canScrollVertically(): Boolean

checkLayoutParams

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

computeHorizontalScrollExtent

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

computeHorizontalScrollOffset

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

computeHorizontalScrollRange

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

computeScrollVectorForPosition

open fun computeScrollVectorForPosition(targetPosition: Int): PointF?

computeVerticalScrollExtent

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

computeVerticalScrollOffset

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

computeVerticalScrollRange

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

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.

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.

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.

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.

generateDefaultLayoutParams

open fun generateDefaultLayoutParams(): RecyclerView.LayoutParams!

generateLayoutParams

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

generateLayoutParams

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

getColumnCountForAccessibility

open fun getColumnCountForAccessibility(recycler: RecyclerView.Recycler, 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.

getOrientation

open fun getOrientation(): Int

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

getRowCountForAccessibility

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

getSpanCount

open fun getSpanCount(): Int

Returns the number of spans laid out by StaggeredGridLayoutManager.

Return
Int: Number of spans in the layout

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.

isAutoMeasureEnabled

open fun isAutoMeasureEnabled(): Boolean

offsetChildrenHorizontal

open fun offsetChildrenHorizontal(dx: Int): Unit

offsetChildrenVertical

open fun offsetChildrenVertical(dy: Int): Unit

onDetachedFromWindow

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

onFocusSearchFailed

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

onInitializeAccessibilityEvent

open fun onInitializeAccessibilityEvent(event: AccessibilityEvent): Unit

onInitializeAccessibilityNodeInfoForItem

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

onItemsAdded

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

onItemsChanged

open fun onItemsChanged(recyclerView: RecyclerView): Unit

onItemsMoved

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

onItemsRemoved

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

onItemsUpdated

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

onLayoutChildren

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

onLayoutCompleted

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

onRestoreInstanceState

open fun onRestoreInstanceState(state: Parcelable!): Unit

onSaveInstanceState

open fun onSaveInstanceState(): Parcelable?

onScrollStateChanged

open fun onScrollStateChanged(state: Int): Unit

scrollHorizontallyBy

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

scrollToPosition

open fun scrollToPosition(position: Int): Unit

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

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 .

setMeasuredDimension

open fun setMeasuredDimension(childrenBounds: Rect!, wSpec: Int, hSpec: Int): 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

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

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

smoothScrollToPosition

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

supportsPredictiveItemAnimations

open fun supportsPredictiveItemAnimations(): Boolean