Android APIs
public class

GridLayoutManager

extends LinearLayoutManager
java.lang.Object
   ↳ android.support.v7.widget.RecyclerView.LayoutManager
     ↳ android.support.v7.widget.LinearLayoutManager
       ↳ android.support.v7.widget.GridLayoutManager

Class Overview

A RecyclerView.LayoutManager implementations that lays out items in a grid.

By default, each item occupies 1 span. You can change it by providing a custom GridLayoutManager.SpanSizeLookup instance via setSpanSizeLookup(SpanSizeLookup).

Summary

Nested Classes
class GridLayoutManager.DefaultSpanSizeLookup Default implementation for GridLayoutManager.SpanSizeLookup
class GridLayoutManager.LayoutParams LayoutParams used by GridLayoutManager. 
class GridLayoutManager.SpanSizeLookup A helper class to provide the number of spans each item occupies. 
Constants
int DEFAULT_SPAN_COUNT
[Expand]
Inherited Constants
From class android.support.v7.widget.LinearLayoutManager
Public Constructors
GridLayoutManager(Context context, int spanCount)
Creates a vertical GridLayoutManager
GridLayoutManager(Context context, int spanCount, int orientation, boolean reverseLayout)
Public Methods
boolean checkLayoutParams(RecyclerView.LayoutParams lp)
Determines the validity of the supplied LayoutParams object.
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 getRowCountForAccessibility(RecyclerView.Recycler recycler, RecyclerView.State state)
Returns the number of rows for accessibility.
int getSpanCount()
Returns the number of spans laid out by this grid.
GridLayoutManager.SpanSizeLookup getSpanSizeLookup()
Returns the current GridLayoutManager.SpanSizeLookup used by the GridLayoutManager.
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 when notifyDataSetChanged() is triggered instead of giving detailed information on what has actually 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)
Called when items have been changed in the adapter.
void onLayoutChildren(RecyclerView.Recycler recycler, RecyclerView.State state)
Lay out all relevant child views from the given adapter.
void setSpanCount(int spanCount)
Sets the number of spans to be laid out.
void setSpanSizeLookup(GridLayoutManager.SpanSizeLookup spanSizeLookup)
Sets the source to get the number of spans occupied by each item in the adapter.
void setStackFromEnd(boolean stackFromEnd)
stackFromEnd is not supported by GridLayoutManager.
boolean supportsPredictiveItemAnimations()
Returns whether this LayoutManager supports automatic item animations.
[Expand]
Inherited Methods
From class android.support.v7.widget.LinearLayoutManager
From class android.support.v7.widget.RecyclerView.LayoutManager
From class java.lang.Object

Constants

public static final int DEFAULT_SPAN_COUNT

Constant Value: -1 (0xffffffff)

Public Constructors

public GridLayoutManager (Context context, int spanCount)

Creates a vertical GridLayoutManager

Parameters
context Current context, will be used to access resources.
spanCount The number of columns in the grid

public GridLayoutManager (Context context, int spanCount, int orientation, boolean reverseLayout)

Parameters
context Current context, will be used to access resources.
spanCount The number of columns or rows in the grid
orientation Layout orientation. Should be HORIZONTAL or VERTICAL.
reverseLayout When set to true, layouts from end to start.

Public Methods

public 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 LayoutParams object to check
Returns
  • true if this LayoutParams object is valid, false otherwise

public RecyclerView.LayoutParams generateDefaultLayoutParams ()

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

LayoutManagers will often want to use a custom LayoutParams type to store extra information specific to the layout. Client code should subclass RecyclerView.LayoutParams for this purpose.

Important: if you use your own custom LayoutParams type you must also override checkLayoutParams(LayoutParams), generateLayoutParams(android.view.ViewGroup.LayoutParams) and generateLayoutParams(android.content.Context, android.util.AttributeSet).

Returns
  • A new LayoutParams for a child view

public RecyclerView.LayoutParams generateLayoutParams (Context c, AttributeSet attrs)

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

Important: if you use your own custom LayoutParams type you must also override checkLayoutParams(LayoutParams), generateLayoutParams(android.view.ViewGroup.LayoutParams) and generateLayoutParams(android.content.Context, android.util.AttributeSet).

Parameters
c Context for obtaining styled attributes
attrs AttributeSet describing the supplied arguments
Returns
  • a new LayoutParams object

public RecyclerView.LayoutParams generateLayoutParams (ViewGroup.LayoutParams lp)

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

Important: if you use your own custom LayoutParams type you must also override checkLayoutParams(LayoutParams), generateLayoutParams(android.view.ViewGroup.LayoutParams) and generateLayoutParams(android.content.Context, android.util.AttributeSet).

Parameters
lp Source LayoutParams object to copy values from
Returns
  • a new LayoutParams object

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

Returns the number of columns for accessibility.

Default implementation returns the number of items in the adapter if LayoutManager supports horizontal scrolling or 1 if LayoutManager does not support horizontal scrolling.

Parameters
recycler The Recycler that can be used to convert view positions into adapter positions
state The current state of RecyclerView
Returns
  • The number of rows in LayoutManager for accessibility.

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

Returns the number of rows for accessibility.

Default implementation returns the number of items in the adapter if LayoutManager supports vertical scrolling or 1 if LayoutManager does not support vertical scrolling.

Parameters
recycler The Recycler that can be used to convert view positions into adapter positions
state The current state of RecyclerView
Returns
  • The number of rows in LayoutManager for accessibility.

public int getSpanCount ()

Returns the number of spans laid out by this grid.

Returns
  • The number of spans

public GridLayoutManager.SpanSizeLookup getSpanSizeLookup ()

Returns the current GridLayoutManager.SpanSizeLookup used by the GridLayoutManager.

Returns

public 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.

Default implementation adds basic positioning information about the item.

Parameters
recycler The Recycler that can be used to convert view positions into adapter positions
state The current state of RecyclerView
host The child for which accessibility node info should be populated
info The info to fill out about the item

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

Called when items have been added to the adapter. The LayoutManager may choose to requestLayout if the inserted items would require refreshing the currently visible set of child views. (e.g. currently empty space would be filled by appended items, etc.)

public void onItemsChanged (RecyclerView recyclerView)

Called when notifyDataSetChanged() is triggered instead of giving detailed information on what has actually changed.

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

Called when an item is moved withing the adapter.

Note that, an item may also change position in response to another ADD/REMOVE/MOVE operation. This callback is only called if and only if notifyItemMoved(int, int) is called.

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

Called when items have been removed from the adapter.

public void onItemsUpdated (RecyclerView recyclerView, int positionStart, int itemCount)

Called when items have been changed in the adapter.

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

Lay out all relevant child views from the given adapter. The LayoutManager is in charge of the behavior of item animations. By default, RecyclerView has a non-null ItemAnimator, and simple item animations are enabled. This means that add/remove operations on the adapter will result in animations to add new or appearing items, removed or disappearing items, and moved items. If a LayoutManager returns false from supportsPredictiveItemAnimations(), which is the default, and runs a normal layout operation during onLayoutChildren(Recycler, State), the RecyclerView will have enough information to run those animations in a simple way. For example, the default ItemAnimator, DefaultItemAnimator, will simple fade views in and out, whether they are actuall added/removed or whether they are moved on or off the screen due to other add/remove operations.

A LayoutManager wanting a better item animation experience, where items can be animated onto and off of the screen according to where the items exist when they are not on screen, then the LayoutManager should return true from supportsPredictiveItemAnimations() and add additional logic to onLayoutChildren(Recycler, State). Supporting predictive animations means that onLayoutChildren(Recycler, State) will be called twice; once as a "pre" layout step to determine where items would have been prior to a real layout, and again to do the "real" layout. In the pre-layout phase, items will remember their pre-layout positions to allow them to be laid out appropriately. Also, removed items will be returned from the scrap to help determine correct placement of other items. These removed items should not be added to the child list, but should be used to help calculate correct positioning of other views, including views that were not previously onscreen (referred to as APPEARING views), but whose pre-layout offscreen position can be determined given the extra information about the pre-layout removed views.

The second layout pass is the real layout in which only non-removed views will be used. The only additional requirement during this pass is, if supportsPredictiveItemAnimations() returns true, to note which views exist in the child list prior to layout and which are not there after layout (referred to as DISAPPEARING views), and to position/layout those views appropriately, without regard to the actual bounds of the RecyclerView. This allows the animation system to know the location to which to animate these disappearing views.

The default LayoutManager implementations for RecyclerView handle all of these requirements for animations already. Clients of RecyclerView can either use one of these layout managers directly or look at their implementations of onLayoutChildren() to see how they account for the APPEARING and DISAPPEARING views.

Parameters
recycler Recycler to use for fetching potentially cached views for a position
state Transient state of RecyclerView

public void setSpanCount (int spanCount)

Sets the number of spans to be laid out.

If getOrientation() is VERTICAL, this is the number of columns. If getOrientation() is HORIZONTAL, this is the number of rows.

Parameters
spanCount The total number of spans in the grid
See Also

public void setSpanSizeLookup (GridLayoutManager.SpanSizeLookup spanSizeLookup)

Sets the source to get the number of spans occupied by each item in the adapter.

Parameters
spanSizeLookup GridLayoutManager.SpanSizeLookup instance to be used to query number of spans occupied by each item

public void setStackFromEnd (boolean stackFromEnd)

stackFromEnd is not supported by GridLayoutManager. Consider using setReverseLayout(boolean).

public boolean supportsPredictiveItemAnimations ()

Returns whether this LayoutManager supports automatic item animations. A LayoutManager wishing to support item animations should obey certain rules as outlined in onLayoutChildren(Recycler, State). The default return value is false, so subclasses of LayoutManager will not get predictive item animations by default.

Whether item animations are enabled in a RecyclerView is determined both by the return value from this method and the ItemAnimator set on the RecyclerView itself. If the RecyclerView has a non-null ItemAnimator but this method returns false, then simple item animations will be enabled, in which views that are moving onto or off of the screen are simply faded in/out. If the RecyclerView has a non-null ItemAnimator and this method returns true, then there will be two calls to onLayoutChildren(Recycler, State) to setup up the information needed to more intelligently predict where appearing and disappearing views should be animated from/to.

Returns
  • true if predictive item animations should be enabled, false otherwise