XUL:Grid

Grids

A grid is a set of boxes extended into two directions. The grid consists of two children, one which contains a set of vertical boxes, arranged horizontally, and the other contains a set of horizontal boxes, arranged vertically. The former defines the columns of the grid, while the latter defines the rows. These two children are referred to as grid line groups.

The grid element is defined with the <grid> element. The grid line groups are defined by either a <columns> or a <rows> element. The only difference between these latter two elements is that a <columns> element has horizontal orientation while a <rows> element defaults to vertical orientation.

A grid may have one of each of a <columns> or a <rows> element, in either order. Any additional <columns> and <rows> elements, or any other types of elements must be ignored -- that is, they do not participate in layout and do not get displayed. Usually the <columns> appear as the first child of the grid, and the <rows> second. In this case, the content within the columns is rendered first followed by the content within the rows on top of it. If the <rows> element is an earlier child that the <columns> element, then the content within the rows is rendered first, followed by the content within the columns. The dir attribute may be used on the <grid> to reverse this behaviour so that elements are drawn in reverse order.

Within a grid line group, individual grid lines are placed. These consist of individual <column> or <row> elements. The <column> element has vertical orientation while the <row> element has horizontal orientation. They function equivalently otherwise. A grid line group may contain as many grid lines as needed. If an element that is not a grid line (that is, not a <column> or <row> element) appears in the grid line group, these form special grid lines, the layout and position of which is defined later.

Within the <column> and <row> elements are zero or more children which become the content of the cells of the grid. As a <column> element has vertical orientation, each successive child is used for the cell on each successive row within that column. Each successive child of a <row> element defines a cell horizontally along the row, one for each column.

In this example, a grid of two columns and three rows is defined.

<grid>
  <columns>
    <column/>
    <column flex="1"/>
  </columns>
  <rows>
    <row><label/><button/></row>
    <row><label/><textbox/></row>
    <row><checkbox/></row>
  </rows>
</grid>

The first <row> element has two children. The first child, the <label>, specifies the content for the first column in that row, while the second child, the <button>, specifies the content for the second column. The second row behaves similarly.

If there are less children in a row than there are defined columns, the remaining cells are treated as if they had empty space with a default width and height of 0. Similarly, the same applies if there are less children in a column than there are rows.

If there are more children in a row than there are defined columns, one or more extra anonymous columns, as needed, are added. Similarly, if there are more children in a column than there are defined rows, one or more extra anonymous rows are added. Anonymous rows and columns have the default value for all attributes, but otherwise behave the same as normal rows and columns. The extra rows and columns have empty space with default width and height of 0 in other cells that don't also have content in them.

In the example above, the third row has only one child. The remaining cell in this column will be empty. Also, both columns do not have any content. Thus, they define columns, the second of which is flexible, but otherwise do not add any content.

Cell content may be defined in both the columns and rows of a grid as in the following example:

<grid>
  <columns>
    <column><label/><textbox/></column>
    <column flex="1"/>
  </columns>
  <rows>
    <row><scale/><button/></row>
    <row><checkbox/><progressmeter/></row>
  </rows>
</grid>

The first column defines a label to appear in the first cell (in the first row) and a textbox to appear in the second cell within that column (and thus appears in the second row). However, the two rows also define content to appear in these cell positions. The result is that both elements become part of the cell, and will both be rendered at the same location in the cell. The order is determined by whether the columns or rows is rendered first in the grid, as described earlier.

Mouse events will fire on the element that appears above if they overlap. Naturally, if two elements appear in a cell but have non-overlapping sections in whole or in part, the mouse event will fall through to the lower element for non-overlapping sections.

In the example above, the scale will be displayed over top of the label, and the checkbox will be rendered over top of the textbox.

The size of a cell is determined by the size of both of the elements within that cell as well as size and box attributes placed on the grid.

A cell is considered to be within both the row and column it is logically contained within for the purposes of the descriptions below. That means that each cell position has two content nodes within it.

Special columns are non-<column> elements placed within a <columns> element. The used width of a special column is the width of the non-<column> element. The used height is the height of the grid.

Special rows are non-<row> elements placed within a <rows> element. The used width is the width of the grid. The used height of a special row is the width of the non-<row> element.

<grid> elements

The width of the grid is determined by the larger of:

• the smaller of the width and maxwidth of the grid element
• the minwidth of the grid element
• the smaller of the width and maxwidth of the columns element (not needed)
• the minwidth of the columns element (not needed)
• the smaller of the width and maxwidth of the specific column element (not needed)
• the minwidth of the specific column element (not needed)
• the smaller of the width and maxwidth of the rows element (not needed)
• the minwidth of the rows element (not needed)
• total used width of the content in the cells of the column including special rows and columns

The height of the grid is determined by the larger of:

• the smaller of the height and maxheight of the grid element
• the minheight of the grid element
• the smaller of the height and maxheight of the columns element (not needed)
• the minheight of the columns element (not needed)
• the smaller of the height and maxheight of the specific column element (not needed)
• the minheight of the specific column element (not needed)
• the smaller of the height and maxheight of the rows element (not needed)
• the minheight of the rows element (not needed)
• total used height of the content in the cells of the column including special rows and columns

The align, pack and orient attributes have no effect on the grid element.

<rows> and <columns> elements

The used width and height of both the rows and columns elements is always the same width and height as the grid.

The align, flex and ordinal attribute have no effect on the rows element.

The pack attribute on the columns element determines where the columns, special columns as well as the cells in the columns are packed horizontally when the grid is wider than the space that they need. The pack attribute on the rows element determines where the rows, special rows as well as the cells in the rows are packed vertically when the grid is higher than the space that they need.

The orient attribute would not normally be used. The computed orient determines whether the element acts like a <rows> element or a <columns> elements. If the computed value of orient is 'vertical' then the element acts like a <rows> element. If the computed value of orient is 'horizontal' then the element acts like a <columns> element.

The dir attribute may be used to render the columns and special columns as if they were defined in the reverse order. All cell content is rendered in their new positions. Similarly for the rows and special rows.

<row> and <column> elements

The used width of a row is the total computed width of the columns and special columns. The used height of a column is the total computed height of the rows and special rows.

The ordinal attribute determines the order in which the row and column elements are displayed. It affects special rows and columns and well as the content in all cells.

The flex attribute determines how the parent rows or columns divides any extra available space.

The align attribute on a row determines the vertical alignment of all cells in that row. The align attribute on a column determines the horizontal alignment of all cells in that column.

The dir and pack attributes have no effect on the row and column elements.

The orient attribute would not normally be used. The computed orient determines whether the element acts like a <row> element or a <column> elements. If the computed value of orient is 'horizontal' then the element acts like a <row> element. If the computed value of orient is 'vertical' then the element acts like a <column> element.

Cells

The width and height of a cell is determined by the column width or row height, not the computed width and height of the content within it, although the computed values may have been used as described earlier to determine the column width or row height. The used width and height of the content in the cells is the width and height of the cell. The flex attribute has no effect on cell nodes. The division of extra space is determined by the align attributes of the containing row and column elements.

The ordinal attribute has no effect on cell nodes.

Other box attributes have effect as would be applicable to the element itself.

Nested <rows> and <columns> elements

To be done...