Package com.smartgwt.client.docs

# Interface FormLayout

public interface FormLayout

### Form Layout

FormItem Placement in Columns and Rows

With the default tabular layout mechanism, items are laid out in rows from left to right until the number of columns, specified by `form.numCols`, is filled, then a new row is begun. Flags on FormItems, including `startRow`, `endRow`, `colSpan` and `rowSpan`, control row and column placement and spanning.

Note that the most common form items (TextItem, SelectItem, etc) take up two columns by default: one for the form control itself, and one for it's title. The default setting of `form.numCols:2` will result in one TextItem or SelectItem per row.

Note also that ButtonItems have both startRow:true and endRow:true by default. You must set startRow and/or endRow to `false` on a ButtonItem in order to place a button in the same row as any other item.

The log category "tablePlacement" can be enabled from the Developer Console to watch items being placed. You can also set `form.cellBorder:1` to reveal the table structure for layout troubleshooting purposes.

Row and Column Sizing

`DynamicForm.colWidths` controls the widths of form columns. FormItems that have "*" for `FormItem.width` will fill the column. FormItems with a numeric width will have that width in pixels regardless of the column's specified width, which may cause the column to overflow as described under `DynamicForm.fixedColWidths`.

Browser Layout and Column Compression

With `fixedColWidths:false` (the default), the browser may compress columns containing smaller content (such as titles) below their specified `DynamicForm.colWidths` to make room for columns with larger content. This compression works well when all columns can shrink, but certain items cannot shrink below their specified width: TextItem with `width:"*"`, and FileItem and CanvasItem in general.

If a colSpan item is sized based on policy column widths but other columns compress, the colSpan item may force the form to overflow. Use `DynamicForm.colWidths` min/max syntax or `DynamicForm.autoDetectColumnMinWidths` to prevent this by ensuring columns have appropriate minimums.

For row heights, the largest pixel height specified on any item in the row is taken as a minimum size for the row. Then, any rows that have "*" or "%" height items will share any height not taken up by fixed-sized items.

Individual item heights are controlled by `item.height`. This may be specified as an integer (pixel value), or a percentage string, or the special string "*", which indicates an item should fill the available space.
Percentages allow developers to determine how the available space in the form is split amongst items. For example if a form has 4 items in a single column, 2 of which have an absolute pixel height specified, and 2 of which are have heights of `"30%"` and `"70%"` respectively, the percentage sized items will split up the available space after the fixed size items have been rendered.
Note that `item.cellHeight` may be specified to explicitly control the height of an item's cell. In this case the specified `item.height` will govern the size of the item within the cell (and if set to a percentage, this will be interpreted as a percentage of the cellHeight).

Managing Overflow

Forms often contain labels, data values, or instructional text which can vary in size based on the skin, data values, or internationalization settings. There are a few ways to deal with a form potentially varying in size:

1. Allow scrolling when necessary, using `overflow:auto`, either on the immediate form, or on some parent.
2. Place the form in a Layout along with a component that can render any specified size, such as a `ListGrid`. In this case, the Layout will automatically shrink the grid in order to accommodate the form.
3. Ensure that the form can always render at a designed minimum size by reducing the number of cases of variable-sized text, and testing remaining cases across all supported skins. For example, move help text into hovers on help icons, or clip long text values at a maximum length and provide a hover to see the rest.

Adaptive Layout

To have various automatic adjustments made to render your form items in a single column, you can use `linearMode`. Importantly, you can have this mode automatically applied to a form on `handset devices` by setting `linearOnMobile` true. For further details and the properties that are available to customize this mode, see the `linearMode` documentation.

Several examples of Form Layout are available @see here.

See Also:
  - `FormItem.getWidth()`
  - `FormItem.getHeight()`
  - `DynamicForm.getItemLayout()`
  - `DynamicForm.getItemLayout()`
  - `DynamicForm.getLinearMode()`
  - `DynamicForm.getLinearOnMobile()`
  - `DynamicForm.getNumCols()`
  - `DynamicForm.getLinearNumCols()`
  - `DynamicForm.getLinearHintWidth()`
  - `DynamicForm.getFixedColWidths()`
  - `DynamicForm.getAutoDetectColumnMinWidths()`
  - `com.smartgwt.client.widgets.form.DynamicForm#getColWidths`
  - `DynamicForm.getMinColWidth()`
  - `DynamicForm.getCellPadding()`
  - `DynamicForm.getCellBorder()`
  - `DynamicForm.getSectionVisibilityMode()`
  - `FormItem.getWidth()`
  - `FormItem.getLinearWidth()`
  - `FormItem.getHeight()`
  - `FormItem.getStaticHeight()`
  - `FormItem.getTitleColSpan()`
  - `com.smartgwt.client.widgets.form.fields.FormItem#getColSpan`
  - `FormItem.getLinearColSpan()`
  - `FormItem.getRowSpan()`
  - `FormItem.getStartRow()`
  - `FormItem.getEndRow()`
  - `FormItem.getLinearStartRow()`
  - `FormItem.getLinearEndRow()`
  - `ButtonItem.getStartRow()`
  - `ButtonItem.getEndRow()`
  - `FormItem.getHeight()`
  - `TextAreaItem.getStaticHeight()`
  - `ShuttleItem.getWidth()`
  - `ShuttleItem.getHeight()`