Adobe Flex 3 Help

Grid layout container

You use a Grid layout container to arrange children as rows and columns of cells, much like an HTML table. The following example shows a Grid container that consists of nine cells arranged in a three-by-three pattern:

Grid container with 9 cells

You can put zero or one child in each cell of a Grid container. If you include multiple children in a cell, put a container in the cell, and then add children to the container. The height of all cells in a row is the same, but each row can have a different height. The width of all cells in a column is the same, but each column can have a different width.

You can define a different number of cells for each row or each column of the Grid container. In addition, a cell can span multiple columns and/or multiple rows of the container.

If the default or explicit size of the child is larger than the size of an explicitly sized cell, the child is clipped at the cell boundaries.

If the child's default width or default height is smaller than the cell, the default horizontal alignment of the child in the cell is left and the default vertical alignment is top. You can use the horizontalAlign and verticalAlign properties of the <mx:GridItem> tag to control positioning of the child.

For complete reference information, see the Adobe Flex Language Reference. For information on the Tile container, which creates a layout where all cells have the same size, see Tile layout container.

Creating a Grid layout container

You create a Grid layout container as follows:

  • You use the <mx:Grid> tag to define a Grid container; it can hold any number of <mx:GridRow> child tags.
  • You use the <mx:GridRow> tag to define each row. It must be a child of the <mx:Grid> tag and can hold any number of <mx:GridItem> child tags.
  • You use the <mx:GridItem> tag to define each row cell; it must be a child of the <mx:GridRow> tag.

The <mx:GridItem> tag takes the following optional properties that control how the item is laid out:

Property

Type

Use

Descriptions
rowSpan

Number

Property

Specifies the number of rows of the Grid container spanned by the cell. The default value is 1. You cannot extend a cell past the number of rows in the Grid container.

colSpan

Number

Property

Specifies the number of columns of the Grid container spanned by the cell. The default value is 1. You cannot extend a cell past the number of columns in the Grid container.

The following image shows a Grid container with three rows and three columns:

Grid container with three rows and three columns

On the left, you see how the Grid container appears in Flash Player. On the right, you see the Grid container with borders overlaying it to illustrate the configuration of the rows and columns. In this example, the buttons in the first (top) row each occupy a single cell. The button in the second row spans three columns, and the button in the third row spans the second and third columns.

You do not have to define the same number of cells for every row of a Grid container, as the following image shows. The Grid container defines five cells in row one; row two has one item that spans three cells; and row 3 has one empty cell, followed by an item that spans two cells.

The Grid container defines five cells in row one; row two has one item that spans three cells; and row 3 has one empty cell, followed by an item that spans two cells

The following MXML code creates the Grid container with three rows and three columns shown in the first image in this section: 

<?xml version="1.0"?>
<!-- containers\layouts\GridSimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Grid id="myGrid">

        <!-- Define Row 1. -->
        <mx:GridRow id="row1">
            <!-- Define the first cell of Row 1. -->
            <mx:GridItem>
                <mx:Button label="Button 1"/>
            </mx:GridItem>
            <!-- Define the second cell of Row 1. -->
            <mx:GridItem>
                <mx:Button label="2"/>
            </mx:GridItem>
            <!-- Define the third cell of Row 1. -->
            <mx:GridItem>
                <mx:Button label="Button 3"/>
            </mx:GridItem>
        </mx:GridRow>

        <!-- Define Row 2. -->
        <mx:GridRow id="row2">
            <!-- Define a single cell to span three columns of Row 2. -->
            <mx:GridItem colSpan="3" horizontalAlign="center">
                <mx:Button label="Long-Named Button 4"/>
            </mx:GridItem>
        </mx:GridRow>

        <!-- Define Row 3. -->
        <mx:GridRow id="row3">
            <!-- Define an empty first cell of Row 3. -->
            <mx:GridItem/>
            <!-- Define a cell to span columns 2 and 3 of Row 3. -->
            <mx:GridItem colSpan="2" horizontalAlign="center">
                <mx:Button label="Button 5"/>
            </mx:GridItem>
        </mx:GridRow>

    </mx:Grid>
</mx:Application>

The executing SWF file for the previous example is shown below:

To modify the preceding example to include five buttons across the top row, you modify the first <mx:GridRow> tag as follows: 

<?xml version="1.0"?>
<!-- containers\layouts\Grid5Button.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Grid id="myGrid">

        <!-- Define Row 1. -->
        <mx:GridRow id="row1">
            <!-- Define the first cell of Row 1. -->
            <mx:GridItem>
                <mx:Button label="Button 1"/>
            </mx:GridItem>
            <mx:GridItem>
                <mx:Button label="2"/>
            </mx:GridItem>
            <mx:GridItem>
                <mx:Button label="Button 3"/>
            </mx:GridItem>
            <mx:GridItem>
                <mx:Button label="Button 3a"/>
            </mx:GridItem>
            <mx:GridItem>
                <mx:Button label="Button 3b"/>
            </mx:GridItem>
        </mx:GridRow>

        <!-- Define Row 2. -->
        <mx:GridRow id="row2">
            <!-- Define a single cell to span three columns of Row 2. -->
            <mx:GridItem colSpan="3" horizontalAlign="center">
                <mx:Button label="Long-Named Button 4"/>
            </mx:GridItem>
        </mx:GridRow>

        <!-- Define Row 3. -->
        <mx:GridRow id="row3">
            <!-- Define an empty first cell of Row 3. -->
            <mx:GridItem/>
            <!-- Define a cell to span columns 2 and 3 of Row 3. -->
            <mx:GridItem colSpan="2" horizontalAlign="center">
                <mx:Button label="Button 5"/>
            </mx:GridItem>
        </mx:GridRow>

    </mx:Grid>
</mx:Application>

The executing SWF file for the previous example is shown below:

Setting the row and column span

The colSpan and rowSpan properties of the GridItem container let you create grid items that occupy multiple grid rows and columns. Making an item span multiple rows or columns does not necessarily make its child control or container larger; you must size the child so it fits the space appropriately, as the following example shows.

The following image shows a modification to the example in Creating a Grid layout container, where Button 3a now spans two rows, Button 3b spans three rows, and Button 5 spans three columns:

The Grid container where Button 3a spans two rows, Button 3b spans three rows, and Button 5 spans three column

The following code shows the changes that were made to produce these results: 

<?xml version="1.0"?>
<!-- containers\layouts\GridRowSpan.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Grid id="myGrid">

        <!-- Define Row 1. -->
        <mx:GridRow id="row1" height="33%">
            <!-- Define the first cell of Row 1. -->
            <mx:GridItem>
                <mx:Button label="Button 1"/>
            </mx:GridItem>
            <mx:GridItem>
                <mx:Button label="2"/>
            </mx:GridItem>
            <mx:GridItem>
                <mx:Button label="Button 3"/>
            </mx:GridItem>
            <mx:GridItem rowSpan="2">
                <mx:Button label="Button 3a" height="100%"/>
            </mx:GridItem>
            <mx:GridItem rowSpan="3">
                <mx:Button label="Button 3b" height="100%"/>
            </mx:GridItem>
        </mx:GridRow>
        
        <!-- Define Row 2. -->
        <mx:GridRow id="row2" height="33%">
            <!-- Define a single cell to span three columns of Row 2. -->
            <mx:GridItem colSpan="3" horizontalAlign="center">
                <mx:Button label="Long-Named Button 4"/>
            </mx:GridItem>
        </mx:GridRow>

        <!-- Define Row 3. -->
        <mx:GridRow id="row3" height="33%">
            <!-- Define an empty first cell of Row 3. -->
            <mx:GridItem/>
            <!-- Define a cell to span columns 2 and 3 and 4 of Row 3. -->
            <mx:GridItem colSpan="3">
                <mx:Button 
                    label="Button 5 expands across 3 columns" 
                    width="75%"/>
            </mx:GridItem>
        </mx:GridRow>

    </mx:Grid>
</mx:Application>

The executing SWF file for the previous example is shown below:

This example makes several changes with the following effects:

  • It sets the height of each row to 33% of the grid, ensuring that the rows have equal heights.
  • It sets the rowSpan properties of the items with Buttons 3a and 3b to make them span two and three rows, respectively.
  • It sets the height properties of Buttons 3a and 3b to 100% to make these buttons fill all rows that they span. If you omit this property on these buttons, Flex sets the buttons to their default height, so they do not appear to span the rows.
  • It sets Button 5 to span three rows and sets a percentage-based width of 75%. In this example, the text requires the button to fill the available width of the three columns, so Flex sizes the button to the default size that fits the text, not the requested 75%. If you omit the width property, the result is identical. To see the effect of the percentage width specification, keep the specification and shorten the label text; the button then spans three-quarters of the three columns, centered on the middle column.

The resulting grid has the several additional characteristics. Although the second row definition specifies only a single <mx:GridItem> tag that defines a cell spanning three columns, Flex automatically creates two additional cells to allow Buttons 3a and 3b to expand into the row. The third row also has five cells. The first cell is defined by the empty <mx:gridItem/> tag. The second through fourth cells are defined by the GridItem that contains Button 5, which spans three columns. The fifth column is created because the last item in the first row spans all three rows.