Added in API level 14

GridLayout


open class GridLayout : ViewGroup
kotlin.Any
   ↳ android.view.View
   ↳ android.view.ViewGroup
   ↳ android.widget.GridLayout

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

As of API 21, GridLayout's distribution of excess space accomodates the principle of weight. In the event that no weights are specified, the previous conventions are respected and columns and rows are taken as flexible if their views specify some form of alignment within their groups.

The flexibility of a view is therefore influenced by its alignment which is, in turn, typically defined by setting the gravity property of the child's layout parameters. If either a weight or alignment were defined along a given axis then the component is taken as flexible in that direction. If no weight or 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 weight or a gravity. To prevent a column from stretching, ensure that one of the components in the column does not define a weight or 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. To be more precise, GridLayout treats each of its layout parameters as a constraint in the a set of variables that define the grid-lines along a given axis. During layout, GridLayout solves the constraints so as to return the unique solution to those constraints for which all variables are less-than-or-equal-to the corresponding value in any other valid solution.

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. GONE views are taken to have zero weight during excess space distribution.

These statements apply equally to rows as well as columns, and to groups of rows or columns.

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

Summary

Nested classes
abstract

Alignments specify where a view should be placed within a cell group and what size it should be.

open

Layout information associated with each of the children of a GridLayout.

open

A Spec defines the horizontal or vertical characteristics of a group of cells.

XML attributes
android:columnCount The maximum number of columns to create when automatically positioning children.
android:columnOrderPreserved When set to true, forces column boundaries to appear in the same order as column indices.
android:orientation The orientation property is not used during layout.
android:rowCount The maximum number of rows to create when automatically positioning children.
android:rowOrderPreserved When set to true, forces row boundaries to appear in the same order as row indices.
android:useDefaultMargins When set to true, tells GridLayout to use default margins when none are specified in a view's layout parameters.
Inherited XML attributes
Constants
static Int

This constant is an alignmentMode.

static Int

This constant is an alignmentMode.

static Int

The horizontal orientation.

static Int

The constant used to indicate that a value is undefined.

static Int

The vertical orientation.

Inherited constants
Public constructors
GridLayout(context: Context!)

GridLayout(context: Context!, attrs: AttributeSet!)

GridLayout(context: Context!, attrs: AttributeSet!, defStyleAttr: Int)

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

Public methods
open GridLayout.LayoutParams!

open CharSequence!

open Int

Returns the alignment mode.

open Int

Returns the current number of columns.

open Int

Returns the current orientation.

open Int

Returns the current number of rows.

open Boolean

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

open Boolean

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

open Boolean

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

open Unit
onViewAdded(child: View!)

open Unit

open Unit

open Unit
setAlignmentMode(alignmentMode: Int)

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

open Unit
setColumnCount(columnCount: Int)

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

open Unit
setColumnOrderPreserved(columnOrderPreserved: Boolean)

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.

open Unit
setOrientation(orientation: Int)

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.

open Unit
setRowCount(rowCount: Int)

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

open Unit
setRowOrderPreserved(rowOrderPreserved: Boolean)

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.

open Unit
setUseDefaultMargins(useDefaultMargins: Boolean)

When true, GridLayout allocates default margins around children based on the child's visual characteristics.

open static GridLayout.Spec!
spec(start: Int, size: Int, alignment: GridLayout.Alignment!, weight: Float)

Return a Spec, spec, where:

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

open static GridLayout.Spec!
spec(start: Int, alignment: GridLayout.Alignment!, weight: Float)

Equivalent to: spec(start, 1, alignment, weight).

open static GridLayout.Spec!
spec(start: Int, size: Int, weight: Float)

Equivalent to: spec(start, 1, default_alignment, weight) - where default_alignment is specified in android.widget.GridLayout.LayoutParams.

open static GridLayout.Spec!
spec(start: Int, weight: Float)

Equivalent to: spec(start, 1, weight).

open static GridLayout.Spec!
spec(start: Int, size: Int, alignment: GridLayout.Alignment!)

Equivalent to: spec(start, size, alignment, 0f).

open static GridLayout.Spec!
spec(start: Int, alignment: GridLayout.Alignment!)

Return a Spec, spec, where:

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

open static GridLayout.Spec!
spec(start: Int, size: Int)

Return a Spec, spec, where:

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

open static GridLayout.Spec!
spec(start: Int)

Return a Spec, spec, where:

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

Protected methods
open Boolean

open GridLayout.LayoutParams!

open GridLayout.LayoutParams!

open Unit
onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int)

Called from layout when this view should assign a size and position to each of its children.

open Unit
onMeasure(widthSpec: Int, heightSpec: Int)

Inherited functions
Properties
static GridLayout.Alignment!

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

static GridLayout.Alignment!

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

static GridLayout.Alignment!

Indicates that a view should be centered with the other views in its cell group.

static GridLayout.Alignment!

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

static GridLayout.Alignment!

Indicates that a view should expanded to fit the boundaries of its cell group.

static GridLayout.Alignment!

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

static GridLayout.Alignment!

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

static GridLayout.Alignment!

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

static GridLayout.Alignment!

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

Inherited properties

XML attributes

android:columnCount

android:columnCount
The maximum number of columns to create when automatically positioning children.

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

android:columnOrderPreserved

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

May be a boolean value, such as "true" or "false".

android:orientation

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.

Constant Value Description
horizontal 0 Defines an horizontal widget.
vertical 1 Defines a vertical widget.

android:rowCount

android:rowCount
The maximum number of rows to create when automatically positioning children.

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

android:rowOrderPreserved

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

May be a boolean value, such as "true" or "false".

android:useDefaultMargins

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 android.widget.GridLayout#setUseDefaultMargins(boolean).

May be a boolean value, such as "true" or "false".

Constants

ALIGN_BOUNDS

Added in API level 14
static val ALIGN_BOUNDS: Int

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 android.view.View#getTop() method is called.

Value: 0

ALIGN_MARGINS

Added in API level 14
static val ALIGN_MARGINS: Int

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.

Value: 1

HORIZONTAL

Added in API level 14
static val HORIZONTAL: Int

The horizontal orientation.

Value: 0

UNDEFINED

Added in API level 14
static val UNDEFINED: Int

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 Integer#MIN_VALUE) is intended to avoid confusion between valid values whose sign may not be known.

Value: -2147483648

VERTICAL

Added in API level 14
static val VERTICAL: Int

The vertical orientation.

Value: 1

Public constructors

GridLayout

Added in API level 14
GridLayout(context: Context!)

GridLayout

Added in API level 14
GridLayout(
    context: Context!,
    attrs: AttributeSet!)

GridLayout

Added in API level 14
GridLayout(
    context: Context!,
    attrs: AttributeSet!,
    defStyleAttr: Int)

GridLayout

Added in API level 21
GridLayout(
    context: Context!,
    attrs: AttributeSet!,
    defStyleAttr: Int,
    defStyleRes: Int)

Public methods

generateLayoutParams

Added in API level 14
open fun generateLayoutParams(attrs: AttributeSet!): GridLayout.LayoutParams!
Parameters
attrs AttributeSet!: the attributes to build the layout parameters from
Return
GridLayout.LayoutParams! an instance of android.view.ViewGroup.LayoutParams or one of its descendants

getAccessibilityClassName

Added in API level 23
open fun getAccessibilityClassName(): CharSequence!

getAlignmentMode

Added in API level 14
open fun getAlignmentMode(): Int

Returns the alignment mode.

Return
Int the alignment mode; either ALIGN_BOUNDS or ALIGN_MARGINS Value is android.widget.GridLayout#ALIGN_BOUNDS, or android.widget.GridLayout#ALIGN_MARGINS

getColumnCount

Added in API level 14
open fun getColumnCount(): Int

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 LayoutParams#columnSpec.

Return
Int the current number of columns

getOrientation

Added in API level 14
open fun getOrientation(): Int

Returns the current orientation.

Return
Int either HORIZONTAL or VERTICAL Value is android.widget.GridLayout#HORIZONTAL, or android.widget.GridLayout#VERTICAL

getRowCount

Added in API level 14
open fun getRowCount(): Int

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 LayoutParams#rowSpec.

Return
Int the current number of rows

getUseDefaultMargins

Added in API level 14
open fun getUseDefaultMargins(): Boolean

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

Return
Boolean true if default margins should be allocated

isColumnOrderPreserved

Added in API level 14
open fun isColumnOrderPreserved(): Boolean

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

Return
Boolean true if column boundaries must appear in the order of their indices, false otherwise

isRowOrderPreserved

Added in API level 14
open fun isRowOrderPreserved(): Boolean

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

Return
Boolean true if row boundaries must appear in the order of their indices, false otherwise

onViewAdded

Added in API level 23
open fun onViewAdded(child: View!): Unit
Parameters
child View!: the added child view

onViewRemoved

Added in API level 23
open fun onViewRemoved(child: View!): Unit
Parameters
child View!: the removed child view

requestLayout

Added in API level 14
open fun requestLayout(): Unit

setAlignmentMode

Added in API level 14
open fun setAlignmentMode(alignmentMode: Int): Unit

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.

Parameters
alignmentMode Int: either ALIGN_BOUNDS or ALIGN_MARGINS Value is android.widget.GridLayout#ALIGN_BOUNDS, or android.widget.GridLayout#ALIGN_MARGINS

setColumnCount

Added in API level 14
open fun setColumnCount(columnCount: Int): Unit

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

Parameters
columnCount Int: the number of columns.

setColumnOrderPreserved

Added in API level 14
open fun setColumnOrderPreserved(columnOrderPreserved: Boolean): Unit

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.

Parameters
columnOrderPreserved Boolean: use true to force GridLayout to respect the order of column boundaries.

setOrientation

Added in API level 14
open fun setOrientation(orientation: Int): Unit

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.

Parameters
orientation Int: either HORIZONTAL or VERTICAL Value is android.widget.GridLayout#HORIZONTAL, or android.widget.GridLayout#VERTICAL

setRowCount

Added in API level 14
open fun setRowCount(rowCount: Int): Unit

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

Parameters
rowCount Int: the number of rows

setRowOrderPreserved

Added in API level 14
open fun setRowOrderPreserved(rowOrderPreserved: Boolean): Unit

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.

Parameters
rowOrderPreserved Boolean: true to force GridLayout to respect the order of row boundaries

setUseDefaultMargins

Added in API level 14
open fun setUseDefaultMargins(useDefaultMargins: Boolean): Unit

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.

Parameters
useDefaultMargins Boolean: use true to make GridLayout allocate default margins

spec

Added in API level 21
open static fun spec(
    start: Int,
    size: Int,
    alignment: GridLayout.Alignment!,
    weight: Float
): GridLayout.Spec!

Return a Spec, spec, where:

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

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

Parameters
start Int: the start
size Int: the size
alignment GridLayout.Alignment!: the alignment
weight Float: the weight

spec

Added in API level 21
open static fun spec(
    start: Int,
    alignment: GridLayout.Alignment!,
    weight: Float
): GridLayout.Spec!

Equivalent to: spec(start, 1, alignment, weight).

Parameters
start Int: the start
alignment GridLayout.Alignment!: the alignment
weight Float: the weight

spec

Added in API level 21
open static fun spec(
    start: Int,
    size: Int,
    weight: Float
): GridLayout.Spec!

Equivalent to: spec(start, 1, default_alignment, weight) - where default_alignment is specified in android.widget.GridLayout.LayoutParams.

Parameters
start Int: the start
size Int: the size
weight Float: the weight

spec

Added in API level 21
open static fun spec(
    start: Int,
    weight: Float
): GridLayout.Spec!

Equivalent to: spec(start, 1, weight).

Parameters
start Int: the start
weight Float: the weight

spec

Added in API level 14
open static fun spec(
    start: Int,
    size: Int,
    alignment: GridLayout.Alignment!
): GridLayout.Spec!

Equivalent to: spec(start, size, alignment, 0f).

Parameters
start Int: the start
size Int: the size
alignment GridLayout.Alignment!: the alignment

spec

Added in API level 14
open static fun spec(
    start: Int,
    alignment: GridLayout.Alignment!
): GridLayout.Spec!

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 Int: the start index
alignment GridLayout.Alignment!: the alignment

spec

Added in API level 14
open static fun spec(
    start: Int,
    size: Int
): GridLayout.Spec!

Return a Spec, spec, where:

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

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

Parameters
start Int: the start
size Int: the size

spec

Added in API level 14
open static fun spec(start: Int): GridLayout.Spec!

Return a Spec, spec, where:

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

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

Parameters
start Int: the start index

See Also

Protected methods

checkLayoutParams

Added in API level 14
protected open fun checkLayoutParams(p: ViewGroup.LayoutParams!): Boolean

generateDefaultLayoutParams

Added in API level 14
protected open fun generateDefaultLayoutParams(): GridLayout.LayoutParams!
Return
GridLayout.LayoutParams! a set of default layout parameters or null

generateLayoutParams

Added in API level 14
protected open fun generateLayoutParams(lp: ViewGroup.LayoutParams!): GridLayout.LayoutParams!
Parameters
p The layout parameters to convert into a suitable set of layout parameters for this ViewGroup.
Return
GridLayout.LayoutParams! an instance of android.view.ViewGroup.LayoutParams or one of its descendants

onLayout

Added in API level 14
protected open fun onLayout(
    changed: Boolean,
    left: Int,
    top: Int,
    right: Int,
    bottom: Int
): Unit

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 Boolean: This is a new size or position for this view
left Int: Left position, relative to parent
top Int: Top position, relative to parent
right Int: Right position, relative to parent
bottom Int: Bottom position, relative to parent

onMeasure

Added in API level 14
protected open fun onMeasure(
    widthSpec: Int,
    heightSpec: Int
): Unit
Parameters
widthMeasureSpec horizontal space requirements as imposed by the parent. The requirements are encoded with android.view.View.MeasureSpec.
heightMeasureSpec vertical space requirements as imposed by the parent. The requirements are encoded with android.view.View.MeasureSpec.

Properties

BASELINE

Added in API level 14
static val BASELINE: GridLayout.Alignment!

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.

BOTTOM

Added in API level 14
static val BOTTOM: GridLayout.Alignment!

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

CENTER

Added in API level 14
static val CENTER: GridLayout.Alignment!

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.

END

Added in API level 16
static val END: GridLayout.Alignment!

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

FILL

Added in API level 14
static val FILL: GridLayout.Alignment!

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

LEFT

Added in API level 14
static val LEFT: GridLayout.Alignment!

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

Added in API level 14
static val RIGHT: GridLayout.Alignment!

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

START

Added in API level 16
static val START: GridLayout.Alignment!

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

TOP

Added in API level 14
static val TOP: GridLayout.Alignment!

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