Android APIs
public class

GridLayout

extends ViewGroup
java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.support.v7.widget.GridLayout

Class Overview

A layout that places its children in a rectangular grid.

The grid is composed of a set of infinitely thin lines that separate the viewing area into cells. Throughout the API, grid lines are referenced by grid indices. A grid with N columns has N + 1 grid indices that run from 0 through N inclusive. Regardless of how GridLayout is configured, grid index 0 is fixed to the leading edge of the container and grid index N is fixed to its trailing edge (after padding is taken into account).

Row and Column Specs

Children occupy one or more contiguous cells, as defined by their rowSpec and columnSpec layout parameters. Each spec defines the set of rows or columns that are to be occupied; and how children should be aligned within the resulting group of cells. Although cells do not normally overlap in a GridLayout, GridLayout does not prevent children being defined to occupy the same cell or group of cells. In this case however, there is no guarantee that children will not themselves overlap after the layout operation completes.

Default Cell Assignment

If a child does not specify the row and column indices of the cell it wishes to occupy, GridLayout assigns cell locations automatically using its: orientation, rowCount and columnCount properties.

Space

Space between children may be specified either by using instances of the dedicated Space view or by setting the leftMargin, topMargin, rightMargin and bottomMargin layout parameters. When the useDefaultMargins property is set, default margins around children are automatically allocated based on the prevailing UI style guide for the platform. Each of the margins so defined may be independently overridden by an assignment to the appropriate layout parameter. Default values will generally produce a reasonable spacing between components but values may change between different releases of the platform.

Excess Space Distribution

GridLayout's distribution of excess space is based on priority rather than weight.

A child's ability to stretch is inferred from the alignment properties of its row and column groups (which are typically set by setting the gravity property of the child's layout parameters). If alignment was defined along a given axis then the component is taken as flexible in that direction. If no alignment was set, the component is instead assumed to be inflexible.

Multiple components in the same row or column group are considered to act in parallel. Such a group is flexible only if all of the components within it are flexible. Row and column groups that sit either side of a common boundary are instead considered to act in series. The composite group made of these two elements is flexible if one of its elements is flexible.

To make a column stretch, make sure all of the components inside it define a gravity. To prevent a column from stretching, ensure that one of the components in the column does not define a gravity.

When the principle of flexibility does not provide complete disambiguation, GridLayout's algorithms favour rows and columns that are closer to its right and bottom edges.

Interpretation of GONE

For layout purposes, GridLayout treats views whose visibility status is GONE, as having zero width and height. This is subtly different from the policy of ignoring views that are marked as GONE outright. If, for example, a gone-marked view was alone in a column, that column would itself collapse to zero width if and only if no gravity was defined on the view. If gravity was defined, then the gone-marked view has no effect on the layout and the container should be laid out as if the view had never been added to it. These statements apply equally to rows as well as columns, and to groups of rows or columns.
Limitations
GridLayout does not provide support for the principle of weight, as defined in weight. In general, it is not therefore possible to configure a GridLayout to distribute excess space between multiple components.

Some common use-cases may nevertheless be accommodated as follows. To place equal amounts of space around a component in a cell group; use CENTER alignment (or gravity). For complete control over excess space distribution in a row or column; use a LinearLayout subview to hold the components in the associated cell group. When using either of these techniques, bear in mind that cell groups may be defined to overlap.

See GridLayout.LayoutParams for a full description of the layout parameters used by GridLayout.

Summary

Nested Classes
class GridLayout.Alignment Alignments specify where a view should be placed within a cell group and what size it should be. 
class GridLayout.LayoutParams Layout information associated with each of the children of a GridLayout. 
class GridLayout.Spec A Spec defines the horizontal or vertical characteristics of a group of cells. 
XML Attributes
Attribute Name Related Method Description
android:alignmentMode setAlignmentMode(int) When set to alignMargins, causes alignment to take place between the outer boundary of a view, as defined by its margins. 
android:columnCount setColumnCount(int) The maxmimum number of columns to create when automatically positioning children. 
android:columnOrderPreserved setColumnOrderPreserved(boolean) When set to true, forces column boundaries to appear in the same order as column indices. 
android:orientation setOrientation(int) The orientation property is not used during layout. 
android:rowCount setRowCount(int) The maxmimum number of rows to create when automatically positioning children. 
android:rowOrderPreserved setRowOrderPreserved(boolean) When set to true, forces row boundaries to appear in the same order as row indices. 
android:useDefaultMargins setUseDefaultMargins(boolean) When set to true, tells GridLayout to use default margins when none are specified in a view's layout parameters. 
[Expand]
Inherited XML Attributes
From class android.view.ViewGroup
From class android.view.View
Constants
int ALIGN_BOUNDS This constant is an alignmentMode.
int ALIGN_MARGINS This constant is an alignmentMode.
int HORIZONTAL The horizontal orientation.
int UNDEFINED The constant used to indicate that a value is undefined.
int VERTICAL The vertical orientation.
[Expand]
Inherited Constants
From class android.view.ViewGroup
From class android.view.View
Fields
public static final GridLayout.Alignment BASELINE Indicates that a view should be aligned with the baselines of the other views in its cell group.
public static final GridLayout.Alignment BOTTOM Indicates that a view should be aligned with the bottom edges of the other views in its cell group.
public static final GridLayout.Alignment CENTER Indicates that a view should be centered with the other views in its cell group.
public static final GridLayout.Alignment END Indicates that a view should be aligned with the end edges of the other views in its cell group.
public static final GridLayout.Alignment FILL Indicates that a view should expanded to fit the boundaries of its cell group.
public static final GridLayout.Alignment LEFT Indicates that a view should be aligned with the left edges of the other views in its cell group.
public static final GridLayout.Alignment RIGHT Indicates that a view should be aligned with the right edges of the other views in its cell group.
public static final GridLayout.Alignment START Indicates that a view should be aligned with the start edges of the other views in its cell group.
public static final GridLayout.Alignment TOP Indicates that a view should be aligned with the top edges of the other views in its cell group.
[Expand]
Inherited Fields
From class android.view.View
Public Constructors
GridLayout(Context context, AttributeSet attrs, int defStyle)
GridLayout(Context context, AttributeSet attrs)
GridLayout(Context context)
Public Methods
GridLayout.LayoutParams generateLayoutParams(AttributeSet attrs)
Returns a new set of layout parameters based on the supplied attributes set.
int getAlignmentMode()
Returns the alignment mode.
int getColumnCount()
Returns the current number of columns.
int getOrientation()
Returns the current orientation.
Printer getPrinter()
Return the printer that will log diagnostics from this layout.
int getRowCount()
Returns the current number of rows.
boolean getUseDefaultMargins()
Returns whether or not this GridLayout will allocate default margins when no corresponding layout parameters are defined.
boolean isColumnOrderPreserved()
Returns whether or not column boundaries are ordered by their grid indices.
boolean isRowOrderPreserved()
Returns whether or not row boundaries are ordered by their grid indices.
void requestLayout()
Call this when something has changed which has invalidated the layout of this view.
void setAlignmentMode(int alignmentMode)
Sets the alignment mode to be used for all of the alignments between the children of this container.
void setColumnCount(int columnCount)
ColumnCount is used only to generate default column/column indices when they are not specified by a component's layout parameters.
void setColumnOrderPreserved(boolean columnOrderPreserved)
When this property is true, GridLayout is forced to place the column boundaries so that their associated grid indices are in ascending order in the view.
void setOrientation(int orientation)
GridLayout uses the orientation property for two purposes:
  • To control the 'direction' in which default row/column indices are generated when they are not specified in a component's layout parameters.
void setPrinter(Printer printer)
Set the printer that will log diagnostics from this layout.
void setRowCount(int rowCount)
RowCount is used only to generate default row/column indices when they are not specified by a component's layout parameters.
void setRowOrderPreserved(boolean rowOrderPreserved)
When this property is true, GridLayout is forced to place the row boundaries so that their associated grid indices are in ascending order in the view.
void setUseDefaultMargins(boolean useDefaultMargins)
When true, GridLayout allocates default margins around children based on the child's visual characteristics.
static GridLayout.Spec spec(int start, GridLayout.Alignment alignment)
Return a Spec, spec, where:
  • spec.span = [start, start + 1]
  • spec.alignment = alignment

To leave the start index undefined, use the value UNDEFINED.

static GridLayout.Spec spec(int start, int size)
Return a Spec, spec, where:
  • spec.span = [start, start + size]

To leave the start index undefined, use the value UNDEFINED.

static GridLayout.Spec spec(int start, int size, GridLayout.Alignment alignment)
Return a Spec, spec, where:
  • spec.span = [start, start + size]
  • spec.alignment = alignment

To leave the start index undefined, use the value UNDEFINED.

static GridLayout.Spec spec(int start)
Return a Spec, spec, where:
  • spec.span = [start, start + 1]

To leave the start index undefined, use the value UNDEFINED.

Protected Methods
boolean checkLayoutParams(ViewGroup.LayoutParams p)
GridLayout.LayoutParams generateDefaultLayoutParams()
Returns a set of default layout parameters.
GridLayout.LayoutParams generateLayoutParams(ViewGroup.LayoutParams p)
Returns a safe set of layout parameters based on the supplied layout params.
void onLayout(boolean changed, int left, int top, int right, int bottom)
Called from layout when this view should assign a size and position to each of its children.
void onMeasure(int widthSpec, int heightSpec)

Measure the view and its content to determine the measured width and the measured height.

[Expand]
Inherited Methods
From class android.view.ViewGroup
From class android.view.View
From class java.lang.Object
From interface android.graphics.drawable.Drawable.Callback
From interface android.view.KeyEvent.Callback
From interface android.view.ViewManager
From interface android.view.ViewParent
From interface android.view.accessibility.AccessibilityEventSource

XML Attributes

android:alignmentMode

When set to alignMargins, causes alignment to take place between the outer boundary of a view, as defined by its margins. When set to alignBounds, causes alignment to take place between the edges of the view. The default is alignMargins. See setAlignmentMode(int).

Must be one of the following constant values.

ConstantValueDescription
alignBounds0 Align the bounds of the children. See ALIGN_BOUNDS.
alignMargins1 Align the margins of the children. See ALIGN_MARGINS.

This corresponds to the global attribute resource symbol alignmentMode.

Related Methods

android:columnCount

The maxmimum number of columns to create when automatically positioning children.

Must be an integer value, such as "100".

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol columnCount.

Related Methods

android:columnOrderPreserved

When set to true, forces column boundaries to appear in the same order as column indices. The default is true. See setColumnOrderPreserved(boolean).

Must be a boolean value, either "true" or "false".

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol columnOrderPreserved.

android:orientation

The orientation property is not used during layout. It is only used to allocate row and column parameters when they are not specified by its children's layout paramters. GridLayout works like LinearLayout in this case; putting all the components either in a single row or in a single column - depending on the value of this flag. In the horizontal case, a columnCount property may be additionally supplied to force new rows to be created when a row is full. The rowCount attribute may be used similarly in the vertical case. The default is horizontal.

Must be one of the following constant values.

ConstantValueDescription
horizontal0 Defines an horizontal widget.
vertical1 Defines a vertical widget.

This corresponds to the global attribute resource symbol orientation.

Related Methods

android:rowCount

The maxmimum number of rows to create when automatically positioning children.

Must be an integer value, such as "100".

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol rowCount.

Related Methods

android:rowOrderPreserved

When set to true, forces row boundaries to appear in the same order as row indices. The default is true. See setRowOrderPreserved(boolean).

Must be a boolean value, either "true" or "false".

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol rowOrderPreserved.

android:useDefaultMargins

When set to true, tells GridLayout to use default margins when none are specified in a view's layout parameters. The default value is false. See setUseDefaultMargins(boolean).

Must be a boolean value, either "true" or "false".

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol useDefaultMargins.

Constants

public static final int ALIGN_BOUNDS

This constant is an alignmentMode. When the alignmentMode is set to ALIGN_BOUNDS, alignment is made between the edges of each component's raw view boundary: i.e. the area delimited by the component's: top, left, bottom and right properties.

For example, when GridLayout is in ALIGN_BOUNDS mode, children that belong to a row group that uses TOP alignment will all return the same value when their getTop() method is called.

Constant Value: 0 (0x00000000)

public static final int ALIGN_MARGINS

This constant is an alignmentMode. When the alignmentMode is set to ALIGN_MARGINS, the bounds of each view are extended outwards, according to their margins, before the edges of the resulting rectangle are aligned.

For example, when GridLayout is in ALIGN_MARGINS mode, the quantity top - layoutParams.topMargin is the same for all children that belong to a row group that uses TOP alignment.

Constant Value: 1 (0x00000001)

public static final int HORIZONTAL

The horizontal orientation.

Constant Value: 0 (0x00000000)

public static final int UNDEFINED

The constant used to indicate that a value is undefined. Fields can use this value to indicate that their values have not yet been set. Similarly, methods can return this value to indicate that there is no suitable value that the implementation can return. The value used for the constant (currently MIN_VALUE) is intended to avoid confusion between valid values whose sign may not be known.

Constant Value: -2147483648 (0x80000000)

public static final int VERTICAL

The vertical orientation.

Constant Value: 1 (0x00000001)

Fields

public static final GridLayout.Alignment BASELINE

Indicates that a view should be aligned with the baselines of the other views in its cell group. This constant may only be used as an alignment in rowSpecs.

See Also

public static final GridLayout.Alignment BOTTOM

Indicates that a view should be aligned with the bottom edges of the other views in its cell group.

public static final GridLayout.Alignment CENTER

Indicates that a view should be centered with the other views in its cell group. This constant may be used in both rowSpecs and columnSpecs.

public static final GridLayout.Alignment END

Indicates that a view should be aligned with the end edges of the other views in its cell group.

public static final GridLayout.Alignment FILL

Indicates that a view should expanded to fit the boundaries of its cell group. This constant may be used in both rowSpecs and columnSpecs.

public static final GridLayout.Alignment LEFT

Indicates that a view should be aligned with the left edges of the other views in its cell group.

public static final GridLayout.Alignment RIGHT

Indicates that a view should be aligned with the right edges of the other views in its cell group.

public static final GridLayout.Alignment START

Indicates that a view should be aligned with the start edges of the other views in its cell group.

public static final GridLayout.Alignment TOP

Indicates that a view should be aligned with the top edges of the other views in its cell group.

Public Constructors

public GridLayout (Context context, AttributeSet attrs, int defStyle)

public GridLayout (Context context, AttributeSet attrs)

public GridLayout (Context context)

Public Methods

public GridLayout.LayoutParams generateLayoutParams (AttributeSet attrs)

Returns a new set of layout parameters based on the supplied attributes set.

Parameters
attrs the attributes to build the layout parameters from
Returns

public int getAlignmentMode ()

Returns the alignment mode.

Related XML Attributes
Returns

public int getColumnCount ()

Returns the current number of columns. This is either the last value that was set with setColumnCount(int) or, if no such value was set, the maximum value of each the upper bounds defined in columnSpec.

Related XML Attributes
Returns
  • the current number of columns

public int getOrientation ()

Returns the current orientation.

Related XML Attributes
Returns

public Printer getPrinter ()

Return the printer that will log diagnostics from this layout.

Returns
  • the printer associated with this view

public int getRowCount ()

Returns the current number of rows. This is either the last value that was set with setRowCount(int) or, if no such value was set, the maximum value of each the upper bounds defined in rowSpec.

Related XML Attributes
Returns
  • the current number of rows

public boolean getUseDefaultMargins ()

Returns whether or not this GridLayout will allocate default margins when no corresponding layout parameters are defined.

Related XML Attributes
Returns
  • true if default margins should be allocated

public boolean isColumnOrderPreserved ()

Returns whether or not column boundaries are ordered by their grid indices.

Related XML Attributes
Returns
  • true if column boundaries must appear in the order of their indices, false otherwise

public boolean isRowOrderPreserved ()

Returns whether or not row boundaries are ordered by their grid indices.

Related XML Attributes
Returns
  • true if row boundaries must appear in the order of their indices, false otherwise

public void requestLayout ()

Call this when something has changed which has invalidated the layout of this view. This will schedule a layout pass of the view tree. This should not be called while the view hierarchy is currently in a layout pass (isInLayout(). If layout is happening, the request may be honored at the end of the current layout pass (and then layout will run again) or after the current frame is drawn and the next layout occurs.

Subclasses which override this method should call the superclass method to handle possible request-during-layout errors correctly.

public void setAlignmentMode (int alignmentMode)

Sets the alignment mode to be used for all of the alignments between the children of this container.

The default value of this property is ALIGN_MARGINS.

Related XML Attributes
Parameters
alignmentMode either ALIGN_BOUNDS or ALIGN_MARGINS

public void setColumnCount (int columnCount)

ColumnCount is used only to generate default column/column indices when they are not specified by a component's layout parameters.

Related XML Attributes
Parameters
columnCount the number of columns.

public void setColumnOrderPreserved (boolean columnOrderPreserved)

When this property is true, GridLayout is forced to place the column boundaries so that their associated grid indices are in ascending order in the view.

When this property is false GridLayout is at liberty to place the horizontal column boundaries in whatever order best fits the given constraints.

The default value of this property is true.

Related XML Attributes
Parameters
columnOrderPreserved use true to force GridLayout to respect the order of column boundaries.

public void setOrientation (int orientation)

GridLayout uses the orientation property for two purposes:

  • To control the 'direction' in which default row/column indices are generated when they are not specified in a component's layout parameters.
  • To control which axis should be processed first during the layout operation: when orientation is HORIZONTAL the horizontal axis is laid out first.
The order in which axes are laid out is important if, for example, the height of one of GridLayout's children is dependent on its width - and its width is, in turn, dependent on the widths of other components.

If your layout contains a TextView (or derivative: Button, EditText, CheckBox, etc.) which is in multi-line mode (the default) it is normally best to leave GridLayout's orientation as HORIZONTAL - because TextView is capable of deriving its height for a given width, but not the other way around.

Other than the effects above, orientation does not affect the actual layout operation of GridLayout, so it's fine to leave GridLayout in HORIZONTAL mode even if the height of the intended layout greatly exceeds its width.

The default value of this property is HORIZONTAL.

Related XML Attributes
Parameters
orientation either HORIZONTAL or VERTICAL
See Also

public void setPrinter (Printer printer)

Set the printer that will log diagnostics from this layout. The default value is created by LogPrinter.

Parameters
printer the printer associated with this layout
See Also

public void setRowCount (int rowCount)

RowCount is used only to generate default row/column indices when they are not specified by a component's layout parameters.

Related XML Attributes
Parameters
rowCount the number of rows

public void setRowOrderPreserved (boolean rowOrderPreserved)

When this property is true, GridLayout is forced to place the row boundaries so that their associated grid indices are in ascending order in the view.

When this property is false GridLayout is at liberty to place the vertical row boundaries in whatever order best fits the given constraints.

The default value of this property is true.

Related XML Attributes
Parameters
rowOrderPreserved true to force GridLayout to respect the order of row boundaries

public void setUseDefaultMargins (boolean useDefaultMargins)

When true, GridLayout allocates default margins around children based on the child's visual characteristics. Each of the margins so defined may be independently overridden by an assignment to the appropriate layout parameter.

When false, the default value of all margins is zero.

When setting to true, consider setting the value of the alignmentMode property to ALIGN_BOUNDS.

The default value of this property is false.

Related XML Attributes
Parameters
useDefaultMargins use true to make GridLayout allocate default margins

public static GridLayout.Spec spec (int start, GridLayout.Alignment alignment)

Return a Spec, spec, where:

  • spec.span = [start, start + 1]
  • spec.alignment = alignment

To leave the start index undefined, use the value UNDEFINED.

Parameters
start the start index
alignment the alignment

public static GridLayout.Spec spec (int start, int size)

Return a Spec, spec, where:

  • spec.span = [start, start + size]

To leave the start index undefined, use the value UNDEFINED.

Parameters
start the start
size the size

public static GridLayout.Spec spec (int start, int size, GridLayout.Alignment alignment)

Return a Spec, spec, where:

  • spec.span = [start, start + size]
  • spec.alignment = alignment

To leave the start index undefined, use the value UNDEFINED.

Parameters
start the start
size the size
alignment the alignment

public static GridLayout.Spec spec (int start)

Return a Spec, spec, where:

  • spec.span = [start, start + 1]

To leave the start index undefined, use the value UNDEFINED.

Parameters
start the start index
See Also

Protected Methods

protected boolean checkLayoutParams (ViewGroup.LayoutParams p)

protected GridLayout.LayoutParams generateDefaultLayoutParams ()

Returns a set of default layout parameters. These parameters are requested when the View passed to addView(View) has no layout parameters already set. If null is returned, an exception is thrown from addView.

Returns
  • a set of default layout parameters or null

protected GridLayout.LayoutParams generateLayoutParams (ViewGroup.LayoutParams p)

Returns a safe set of layout parameters based on the supplied layout params. When a ViewGroup is passed a View whose layout params do not pass the test of checkLayoutParams(android.view.ViewGroup.LayoutParams), this method is invoked. This method should return a new set of layout params suitable for this ViewGroup, possibly by copying the appropriate attributes from the specified set of layout params.

Parameters
p The layout parameters to convert into a suitable set of layout parameters for this ViewGroup.
Returns

protected void onLayout (boolean changed, int left, int top, int right, int bottom)

Called from layout when this view should assign a size and position to each of its children. Derived classes with children should override this method and call layout on each of their children.

Parameters
changed This is a new size or position for this view
left Left position, relative to parent
top Top position, relative to parent
right Right position, relative to parent
bottom Bottom position, relative to parent

protected void onMeasure (int widthSpec, int heightSpec)

Measure the view and its content to determine the measured width and the measured height. This method is invoked by measure(int, int) and should be overriden by subclasses to provide accurate and efficient measurement of their contents.

CONTRACT: When overriding this method, you must call setMeasuredDimension(int, int) to store the measured width and height of this view. Failure to do so will trigger an IllegalStateException, thrown by measure(int, int). Calling the superclass' onMeasure(int, int) is a valid use.

The base class implementation of measure defaults to the background size, unless a larger size is allowed by the MeasureSpec. Subclasses should override onMeasure(int, int) to provide better measurements of their content.

If this method is overridden, it is the subclass's responsibility to make sure the measured height and width are at least the view's minimum height and width (getSuggestedMinimumHeight() and getSuggestedMinimumWidth()).

Parameters
widthSpec horizontal space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.
heightSpec vertical space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.