Spark DataGrid Layout - Functional and Design Specification

Introduction

This section describes how the Grid/DataGrid properties rowHeight, variableRowHeight, typicalItem, requestedRowCount, and requestedColumnCount, and the GridColumn width properties are used to compute the actual row heights, column widths, and the DataGrid's measured size and content size. Many of the layout rules defined below correspond to what could be reasonably characterized as "corner cases", situations where the DataGrid is only partially defined.

Grid layout is "virtual", which is to say that only the item renderers that have been scrolled into view are created and measured. The grid's content size, which corresponds to all rows and columns, is estimated based on the size of item renderers configured with the typical item.

Definitions

cell - Specified by a row and column index, relative to the dataProvider and columns lists respectively.

columns - The DataGrid,Grid property whose value is a list (IList) of GridColumns.

dataProvider - The DataGrid,Grid property whose value is a list (IList) of data "items", one per row.

grid - The DataGrid's Grid skin part.

item renderer - An instance of an IGridItemRenderer: the visual element that displays the value for one cell.

preferred size - A visual elements preferred width or height is its explicit width or height. If an explicit size wasn't specified, then the preferred size is the element's measured size.

requestedMinColumnCount - Grid,DataGrid property that specifies the minimum number of columns that should be visible. The default is -1, which indicates there is no minimum. This property has no effect when requestedColumnCount is set, when the Grid's width is explicitly set or if the Grid is inside a Scroller.

requestedColumnCount - Grid,DataGrid property that specifies how many columns should be visible. If the dataProvider's length is greater than requestedRowCount then DataGrid skin's Scroller adds a vertical scrollbar.

requestedMinRowCount - Grid,DataGrid property that specifies the minimum number of rows that should be visible. The default is -1, which indicates there is no minimum.

requestedRowCount - Grid,DataGrid property that specifies how many rows should be visible. If the dataProvider's length is smaller than the requestedRowCount, then the DataGrid is padded with empty rows. If the dataProvider's length is greater than requestedRowCount then DataGrid skin's Scroller adds a vertical scrollbar. If the requestedRowCount is -1, then the measured size will be big enough for all of the layout elements.

requestedMaxRowCount - Grid,DataGrid property that specifies the maximum number of rows that should be visible. The default is 10.

rowHeight - Grid,DataGrid property that specifies the height for all rows if variableRowHeight=false, or the typical row height.

typicalItem - Grid,DataGrid property that specifies a dataProvider item to be used when computing the measured size. The grid's layout creates per-column item renderers configured with the typicalItem as the renderer's data proeprty and uses the renderers' measured width and height to compute the grid's "typical row height" and "typical column width"

typical row height - The maximum preferred height, for all columns measured so far, of item renderers configured with the typicalItem.

typical column width - The preferred width, of the item renderer for a particular column, configured with the typicalItem.

variableRowHeight - A boolean Grid,DataGrid property that specifies if all row heights should match rowHeight, if that was specified, or the typical row height.

Typical Row Height

The measuredHeight of a Grid is a multiple of the "typical row height". If variableRowHeight is false, then the height of all rows is the "typical row height".

If the Grid has rowHeight defined, then the "typical row height" is rowHeight.

Otherwise, if the typicalItem is defined, then the "typical row height" is the maximum preferred height for the item renderers for the first requestedColumnCount columns, where each item renderer has been configured with the typical item and the typical column width.

If typicalItem isn't specified but a dataProvider whose length is non-zero is specified, then dataProvider.getItemAt(0) is used instead of typicalItem.

Otherwise, the "typical row height" is NaN. In this case, we'll say that the "typical row height" is undefined.

MeasuredHeight

Once the "typical row height" is determined, the Grid's measuredHeight is determined like this:

If the typical row height is undefined, then we use the minHeight. (not working if columns IList is set)

If the typical row height is defined and requestedRowCount is >= 0, then the measuredHeight is the requestedRowCount * typical row height.

If the typical row height is defined, the requestedRowCount is -1, and a dataProvider was specified, then the measuredHeight is dataProvider.length * typical row height. However, if requestedMinRowCount or requestedMaxRowCount are specified, the measuredHeight is bounded by requestedMin/MaxRowCount * typical row height. Otherwise, if the dataProvider doesn't exist, the measuredHeight is the Math.max(minHeight, 0).

In a DataGrid, the measuredHeight includes space for the ColumnHeaderBar.

Columns and MeasuredWidth

The Grid's measured width depends on the Grid's columns IList (default is null). If no columns are specified, then columns are generated at commitProperties() time, one per typicalItem property.

The typical item must have valid values for all columns. For example, for columns that just specify a dataField, the typical item must have a matching property.

The Grid's measuredWidth is the sum of requestedColumnCount "typical column widths". If requestedColumnCount is -1, then all columns contribute to the sum. If requestedMinColumnCount is defined, then the sum will be at least the sum of requestedMinColumnCount columns.

A typical column width is equal to the column's explicit width if the column's explicit width is not NaN. If the column's explicit width is NaN, then the typical column width is the preferred width of the column's item renderer configured with the typical item. If no typical item exists, we use the preferred width of the column's item renderer configured with data = null and label= " ".

Measured Size changes

Changing these properties of Grid will cause the Grid's cached measured size to be recomputed: typicalItem, requestedRowCount, requestedColumnCount, itemRenderer, columns.

Changing these properties of any GridColumn will cause the Grid's cached measured size to be recomputed: dataField, itemRenderer, itemRendererFunction, labelFunction, minWidth, maxWidth, width, visible.

The Grid's measured size is cached. It doesn't track changes to the first dataProvider item, even if that item was used as the typical item. Similarly, even if requestedRowCount or requestedColumnCount=-1, the DataGrid's measured size will not change if the length of the dataProvider or columns changes.

Actual Displayed DataGrid

The column header bar is displayed when columns are defined or columns can be generated (typicalItem or dP's first item).

If the typical row height is defined, we may show empty grid lines to fill up space. Otherwise, the grid is blank. (currently not true when columns are defined)

If variableRowHeight is true (the default) then requestedRowCount does not guarantee that as many rows will be shown since the height of each row depends on its data provider item.

If a width is specified for the Grid and it's larger than the measuredWidth of all the columns, we widen the columns whose GridColumn's width is not defined explicitly. The extra width is distributed evenly among those columns.