GridLayout

This view shows a grid of alphabetic letters that you can tap on to advance a list to the
beginning of that list.

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 accommodates the principle of weight.
In the event that no weights are specified, 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.

Constants

ALIGN_BOUNDS

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

ALIGN_MARGINS

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.

HORIZONTAL

public static final int HORIZONTAL

The horizontal orientation.

Constant Value:
0
(0x00000000)

UNDEFINED

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

setOrientation

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.

setUseDefaultMargins

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.