FormLayout (JGoodies Forms 1.8 API)

java.lang.Object
- com.jgoodies.forms.layout.FormLayout

All Implemented Interfaces:

LayoutManager, LayoutManager2, Serializable
```
public final class FormLayout
extends Object
implements LayoutManager2, Serializable
```
FormLayout is a powerful, flexible and precise general purpos layout manager. It aligns components vertically and horizontally i a dynamic rectangular grid of cells, with each component occupying one o more cells A whitepaperonline.
ColumnSpec and RowSpec instances.
CellConstraints. The constraints object specifies where a componen should be located on the form's grid and how the component should b positioned. In addition to its constraints object th FormLayout also considers each component's minimum an preferred sizes in order to determine a component's size.
ButtonBarBuilder assists you in building butto bars; it creates a standardized FormLayout and provides a minimal API tha specializes in adding buttons and Actions. Other builders can creat frequently used panel design, for example a form that consists of rows o label-component pairs.
Size interface.
Example 1 (Plain FormLayout):
Example 2 (Using PanelBuilder):
PanelBuilder to add components to the form
```
Example 3 (Using DefaultFormBuilder):
DefaultFormBuilder tha
 ships with the source distribution
 
```
Version:

$Revision: 1.30 $

Author:

Karsten Lentzsch

See Also:
ColumnSpec, RowSpec, CellConstraints, AbstractFormBuilder, ButtonBarBuilder, DefaultFormBuilder, FormSpecs, Size, Sizes, Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`FormLayout.LayoutInfo` Stores column and row origins.
`static interface`	`FormLayout.Measure` An interface that describes how to measure a `Component`.

Constructor Summary

Constructors
Constructor and Description
`FormLayout()` Constructs an empty FormLayout.
`FormLayout(ColumnSpec[] colSpecs)` Constructs a FormLayout using the given column specifications.
`FormLayout(ColumnSpec[] colSpecs, RowSpec[] rowSpecs)` Constructs a FormLayout using the given column and row specifications.
`FormLayout(String encodedColumnSpecs)` Constructs a FormLayout using the given encoded column specifications.
`FormLayout(String encodedColumnSpecs, LayoutMap layoutMap)` Constructs a FormLayout using the given encoded column specification and LayoutMap.
`FormLayout(String encodedColumnSpecs, String encodedRowSpecs)` Constructs a FormLayout using the give encoded column and row specifications and the default LayoutMap.
`FormLayout(String encodedColumnSpecs, String encodedRowSpecs, LayoutMap layoutMap)` Constructs a FormLayout using the give encoded column and row specifications and the given LayoutMap.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addGroupedColumn(int columnIndex)` Adds the specified column index to the last column group.
`void`	`addGroupedRow(int rowIndex)` Adds the specified row index to the last row group.
`void`	`addLayoutComponent(Component comp, Object constraints)` Adds the specified component to the layout, using the specifie `constraints` object.
`void`	`addLayoutComponent(String name, Component component)` Throws an `UnsupportedOperationException`.
`void`	`appendColumn(ColumnSpec columnSpec)` Appends the given column specification to the right hand side of al columns.
`void`	`appendRow(RowSpec rowSpec)` Appends the given row specification to the bottom of all rows.
`int`	`getColumnCount()` Returns the number of columns in this layout.
`int[][]`	`getColumnGroups()` Returns a deep copy of the column groups.
`ColumnSpec`	`getColumnSpec(int columnIndex)` Returns the `ColumnSpec` at the specified column index.
`CellConstraints`	`getConstraints(Component component)` Looks up and returns the constraints for the specified component.
`boolean`	`getHonorsVisibility()` Returns whether invisible components shall be taken into accoun by this layout.
`float`	`getLayoutAlignmentX(Container parent)` Returns the alignment along the x axis.
`float`	`getLayoutAlignmentY(Container parent)` Returns the alignment along the y axis.
`FormLayout.LayoutInfo`	`getLayoutInfo(Container parent)` Computes and returns the horizontal and vertical grid origins.
`int`	`getRowCount()` Returns the number of rows in this layout.
`int[][]`	`getRowGroups()` Returns a deep copy of the row groups.
`RowSpec`	`getRowSpec(int rowIndex)` Returns the `RowSpec` at the specified row index.
`void`	`insertColumn(int columnIndex, ColumnSpec columnSpec)` Inserts the specified column at the specified position.
`void`	`insertRow(int rowIndex, RowSpec rowSpec)` Inserts the specified column at the specified position.
`void`	`invalidateLayout(Container target)` Invalidates the layout, indicating that if the layout manage has cached information it should be discarded.
`void`	`layoutContainer(Container parent)` Lays out the specified container using this form layout.
`Dimension`	`maximumLayoutSize(Container target)` Returns the maximum dimensions for this layout given the component in the specified target container.
`Dimension`	`minimumLayoutSize(Container parent)` Determines the minimum size of the `parent` containe using this form layout.
`Dimension`	`preferredLayoutSize(Container parent)` Determines the preferred size of the `parent`
`void`	`removeColumn(int columnIndex)` Removes the column with the given column index from the layout.
`void`	`removeLayoutComponent(Component comp)` Removes the specified component from this layout.
`void`	`removeRow(int rowIndex)` Removes the row with the given row index from the layout.
`void`	`setColumnGroup(int... indices)` Sets a single column group, where each column gets the same width.
`void`	`setColumnGroups(int[][] groupOfIndices)` Sets the column groups, where each column in a group gets the sam group wide width.
`void`	`setColumnSpec(int columnIndex, ColumnSpec columnSpec)` Sets the ColumnSpec at the specified column index.
`void`	`setConstraints(Component component, CellConstraints constraints)` Sets the constraints for the specified component in this layout.
`void`	`setHonorsVisibility(boolean b)` Specifies whether invisible components shall be taken into account b this layout for computing the layout size and setting component bounds.
`void`	`setHonorsVisibility(Component component, Boolean b)` Specifies whether the given component shall be taken into accoun for sizing and positioning.
`void`	`setRowGroup(int... indices)` Sets a single row group, where each row gets the same height.
`void`	`setRowGroups(int[][] groupOfIndices)` Sets the row groups, where each row in such a group gets the same grou wide height.
`void`	`setRowSpec(int rowIndex, RowSpec rowSpec)` Sets the RowSpec at the specified row index.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - FormLayout
```
public FormLayout()
```
    Constructs an empty FormLayout. Columns and rows must be adde before components can be added to the layout container.
  - FormLayout
```
public FormLayout(String encodedColumnSpecs)
```
    Constructs a FormLayout using the given encoded column specifications The constructed layout has no rows; these must be adde before components can be added to the layout container The string decoding uses the default LayoutMap.
    DefaultFormBuilder.
    Examples:
```
 See the class comment for more examples.
```
    Parameters:
    encodedColumnSpecs - comma separated encoded column specifications
    
    Throws:
    
    NullPointerException - if encodedColumnSpecs is null
    See Also:
    LayoutMap.getRoot()
  - FormLayout
```
public FormLayout(String encodedColumnSpecs,
          LayoutMap layoutMap)
```
    Constructs a FormLayout using the given encoded column specification and LayoutMap. The constructed layout has no rows; these must be adde before components can be added to the layout container.
    DefaultFormBuilder.
    Examples:
```
 See the class comment for more examples.
```
    Parameters:
    encodedColumnSpecs - comma separated encoded column specifications
    layoutMap - expands layout column and row variables
    
    Throws:
    
    NullPointerException - if encodedColumnSpecs o layoutMap is null
    Since:
    
    1.2
    
    See Also:
    LayoutMap.getRoot()
  - FormLayout
```
public FormLayout(String encodedColumnSpecs,
          String encodedRowSpecs)
```
    Constructs a FormLayout using the give encoded column and row specifications and the default LayoutMap.
    Examples:
```
 See the class comment for more examples.
```
    Parameters:
    encodedColumnSpecs - comma separated encoded column specifications
    encodedRowSpecs - comma separated encoded row specifications
    
    Throws:
    
    NullPointerException - if encodedColumnSpecs or encodedRowSpec is null
    See Also:
    LayoutMap.getRoot()
  - FormLayout
```
public FormLayout(String encodedColumnSpecs,
          String encodedRowSpecs,
          LayoutMap layoutMap)
```
    Constructs a FormLayout using the give encoded column and row specifications and the given LayoutMap.
    Examples:
```
 See the class comment for more examples.
```
    Parameters:
    encodedColumnSpecs - comma separated encoded column specifications
    encodedRowSpecs - comma separated encoded row specifications
    layoutMap - expands layout column and row variables
    
    Throws:
    
    NullPointerException - if encodedColumnSpecs encodedRowSpecs, or layoutMap is null
    Since:
    
    1.2
  - FormLayout
```
public FormLayout(ColumnSpec[] colSpecs)
```
    Constructs a FormLayout using the given column specifications The constructed layout has no rows; these must be adde before components can be added to the layout container.
    
    Parameters:
    colSpecs - an array of column specifications.
    
    Throws:
    
    NullPointerException - if colSpecs is null
    Since:
    
    1.1
  - FormLayout
```
public FormLayout(ColumnSpec[] colSpecs,
          RowSpec[] rowSpecs)
```
    Constructs a FormLayout using the given column and row specifications.
    
    Parameters:
    colSpecs - an array of column specifications.
    rowSpecs - an array of row specifications.
    
    Throws:
    
    NullPointerException - if colSpecs or rowSpecsnull
- Method Detail
  - getColumnCount
```
public int getColumnCount()
```
    Returns the number of columns in this layout.
    
    Returns:
    the number of columns
  - getColumnSpec
```
public ColumnSpec getColumnSpec(int columnIndex)
```
    Returns the ColumnSpec at the specified column index.
    
    Parameters:
    columnIndex - the column index of the requested ColumnSpec
    
    Returns:
    the ColumnSpec at the specified column
    
    Throws:
    
    IndexOutOfBoundsException - if the column index is out of range
  - setColumnSpec
```
public void setColumnSpec(int columnIndex,
                 ColumnSpec columnSpec)
```
    Sets the ColumnSpec at the specified column index.
    
    Parameters:
    columnIndex - the index of the column to be changed
    columnSpec - the ColumnSpec to be set
    
    Throws:
    
    NullPointerException - if columnSpec is null
    
    IndexOutOfBoundsException - if the column index is out of range
  - appendColumn
```
public void appendColumn(ColumnSpec columnSpec)
```
    Appends the given column specification to the right hand side of al columns.
    
    Parameters:
    columnSpec - the column specification to be added
    
    Throws:
    
    NullPointerException - if columnSpec is null
  - insertColumn
```
public void insertColumn(int columnIndex,
                ColumnSpec columnSpec)
```
    Inserts the specified column at the specified position. Shifts component that intersect the new column to the right hand side and readjust column groups.
    
    Parameters:
    columnIndex - index of the column to be inserted
    columnSpec - specification of the column to be inserted
    
    Throws:
    
    IndexOutOfBoundsException - if the column index is out of range
  - removeColumn
```
public void removeColumn(int columnIndex)
```
    Removes the column with the given column index from the layout Components will be rearranged and column groups will be readjusted Therefore, the column must not contain components and must not be par of a column group.
    Note: If one of the constraints mentioned abov is violated, this layout's state becomes illegal and it is unsaf to work with this layout A typical layout implementation can ensure that these constraints ar not violated. However, in some cases you may need to check thes conditions before you invoke this method. The Forms extras contai source code for class FormLayoutUtils that provide the required test methods:
    #columnContainsComponents(Container, int) and
    #isGroupedColumn(FormLayout, int).
    
    Parameters:
    columnIndex - index of the column to remove
    
    Throws:
    
    IndexOutOfBoundsException - if the column index is out of range
    
    IllegalStateException - if the column contains component or if the column is already grouped
    See Also:
    FormLayoutUtils.columnContainsComponent(Container, int), FormLayoutUtils.isGroupedColumn(FormLayout, int)
  - getRowCount
```
public int getRowCount()
```
    Returns the number of rows in this layout.
    
    Returns:
    the number of rows
  - getRowSpec
```
public RowSpec getRowSpec(int rowIndex)
```
    Returns the RowSpec at the specified row index.
    
    Parameters:
    rowIndex - the row index of the requested RowSpec
    
    Returns:
    the RowSpec at the specified row
    
    Throws:
    
    IndexOutOfBoundsException - if the row index is out of range
  - setRowSpec
```
public void setRowSpec(int rowIndex,
              RowSpec rowSpec)
```
    Sets the RowSpec at the specified row index.
    
    Parameters:
    rowIndex - the index of the row to be changed
    rowSpec - the RowSpec to be set
    
    Throws:
    
    NullPointerException - if rowSpec is null
    
    IndexOutOfBoundsException - if the row index is out of range
  - appendRow
```
public void appendRow(RowSpec rowSpec)
```
    Appends the given row specification to the bottom of all rows.
    
    Parameters:
    rowSpec - the row specification to be added to the form layout
    
    Throws:
    
    NullPointerException - if rowSpec is null
  - insertRow
```
public void insertRow(int rowIndex,
             RowSpec rowSpec)
```
    Inserts the specified column at the specified position. Shift components that intersect the new column to the right and readjust column groups.
    
    Parameters:
    rowIndex - index of the row to be inserted
    rowSpec - specification of the row to be inserted
    
    Throws:
    
    IndexOutOfBoundsException - if the row index is out of range
  - removeRow
```
public void removeRow(int rowIndex)
```
    Removes the row with the given row index from the layout. Component will be rearranged and row groups will be readjusted. Therefore, th row must not contain components and must not be part of a row group.
    Note: If one of the constraints mentioned abov is violated, this layout's state becomes illegal and it is unsaf to work with this layout A typical layout implementation can ensure that these constraints ar not violated. However, in some cases you may need to check thes conditions before you invoke this method. The Forms extras contai source code for class FormLayoutUtils that provide the required test methods:
    #rowContainsComponents(Container, int) and
    #isGroupedRow(FormLayout, int).
    
    Parameters:
    rowIndex - index of the row to remove
    
    Throws:
    
    IndexOutOfBoundsException - if the row index is out of range
    
    IllegalStateException - if the row contains component or if the row is already grouped
    See Also:
    FormLayoutUtils.rowContainsComponent(Container, int), FormLayoutUtils.isGroupedRow(FormLayout, int)
  - getConstraints
```
public CellConstraints getConstraints(Component component)
```
    Looks up and returns the constraints for the specified component A copy of the actualCellConstraints object is returned.
    
    Parameters:
    component - the component to be queried
    
    Returns:
    the CellConstraints for the specified component
    
    Throws:
    
    NullPointerException - if component is null
    
    IllegalStateException - if component has not bee added to the container
  - setConstraints
```
public void setConstraints(Component component,
                  CellConstraints constraints)
```
    Sets the constraints for the specified component in this layout.
    
    Parameters:
    component - the component to be modified
    constraints - the constraints to be applied
    
    Throws:
    
    NullPointerException - if component or constraintsnull
  - getColumnGroups
```
public int[][] getColumnGroups()
```
    Returns a deep copy of the column groups.
    
    Returns:
    the column groups as two-dimensional int array
  - setColumnGroups
```
public void setColumnGroups(int[][] groupOfIndices)
```
    Sets the column groups, where each column in a group gets the sam group wide width. Each group is described by an array of integers tha are interpreted as column indices. The parameter is an array of suc group descriptions.
    Examples:
    Parameters:
    groupOfIndices - a two-dimensional array of column groups indices
    
    Throws:
    
    IndexOutOfBoundsException - if an index is outside the grid
    
    IllegalArgumentException - if a column index is used twice or of a group of indices contains only a single element
  - setColumnGroup
```
public void setColumnGroup(int... indices)
```
    Sets a single column group, where each column gets the same width.
    Example:
    Parameters:
    indices - the indices for a single column group
    
    Throws:
    
    IndexOutOfBoundsException - if an index is outside the grid
    
    IllegalArgumentException - if a column index is used twic or if there is only a single index
    
    NullPointerException - if indices is null
    Since:
    
    1.8
    
    See Also:
    setColumnGroups(int[][])
  - addGroupedColumn
```
public void addGroupedColumn(int columnIndex)
```
    Adds the specified column index to the last column group In case there are no groups, a new group will be created.
    
    Parameters:
    columnIndex - the column index to be set grouped
  - getRowGroups
```
public int[][] getRowGroups()
```
    Returns a deep copy of the row groups.
    
    Returns:
    the row groups as two-dimensional int array
  - setRowGroups
```
public void setRowGroups(int[][] groupOfIndices)
```
    Sets the row groups, where each row in such a group gets the same grou wide height. Each group is described by an array of integers that ar interpreted as row indices. The parameter is an array of such grou descriptions.
    Examples:
    Parameters:
    groupOfIndices - a two-dimensional array of row group indices
    
    Throws:
    
    IndexOutOfBoundsException - if an index is outside the grid
    
    IllegalArgumentException - if a column index is used twice or of a group of indices contains only a single element
  - setRowGroup
```
public void setRowGroup(int... indices)
```
    Sets a single row group, where each row gets the same height.
    Example:
    Parameters:
    indices - the indices for a single row group
    
    Throws:
    
    IndexOutOfBoundsException - if an index is outside the grid
    
    IllegalArgumentException - if a row index is used twic or if there is only a single index
    
    NullPointerException - if indices is null
    Since:
    
    1.8
    
    See Also:
    setRowGroups(int[][])
  - addGroupedRow
```
public void addGroupedRow(int rowIndex)
```
    Adds the specified row index to the last row group In case there are no groups, a new group will be created.
    
    Parameters:
    rowIndex - the index of the row that should be grouped
  - getHonorsVisibility
```
public boolean getHonorsVisibility()
```
    Returns whether invisible components shall be taken into accoun by this layout. This container-wide setting can be overridde per component. See setHonorsVisibility(boolean) for details.
    
    Returns:
    true if the component visibility is honore by this FormLayout, false if it is ignored This setting can be overridden for individual CellConstraint using setHonorsVisibility(Component, Boolean).
    Since:
    
    1.2
  - setHonorsVisibility
```
public void setHonorsVisibility(boolean b)
```
    Specifies whether invisible components shall be taken into account b this layout for computing the layout size and setting component bounds If set to true invisible components will be ignored b the layout. If set to false components will be taken int account regardless of their visibility. Visible components are alway used for sizing and positioning.
    true It is useful to set the value to false (in other word to ignore the visibility) if you switch the component visibilit dynamically and want the container to retain the size an component positions.
    setHonorsVisibility(Component, Boolean).
    they are visible, o
  - they have no individual setting and the container-wide setting ignores the visibility (honorsVisibility set to false), o
  - the individual component ignores the visibility

Parameters:: b - true to honor the visibility, i.e. to exclud invisible components from the sizing and positioning false to ignore the visibility, in other words t layout visible and invisible components
Since:: 1.2

setHonorsVisibility
```
public void setHonorsVisibility(Component component,
                       Boolean b)
```
Specifies whether the given component shall be taken into accoun for sizing and positioning. This setting overrides the container-wid default. See setHonorsVisibility(boolean) for details.

Parameters:
component - the component that shall get an individual setting
b - Boolean.TRUE to override the containe default and honor the visibility for the given component Boolean.FALSE to override the container default an ignore the visibility for the given component null to use the container default value as specifie by getHonorsVisibility().
Since:

1.2

addLayoutComponent
```
public void addLayoutComponent(String name,
                      Component component)
```
Throws an UnsupportedOperationException. Does not ad the specified component with the specified name to the layout.

Specified by:

addLayoutComponent in interface LayoutManager

Parameters:
name - indicates entry's position and anchor
component - component to add

Throws:

UnsupportedOperationException - always

addLayoutComponent
```
public void addLayoutComponent(Component comp,
                      Object constraints)
```
Adds the specified component to the layout, using the specifie constraints object. Note that constraints are mutable an are, therefore, cloned when cached.

Specified by:

addLayoutComponent in interface LayoutManager2

Parameters:
comp - the component to be added
constraints - the component's cell constraints

Throws:

NullPointerException - if constraints is null

IllegalArgumentException - if constraints is neithe a String, nor a CellConstraints object or a String that is rejected by the CellConstraints construction

removeLayoutComponent
```
public void removeLayoutComponent(Component comp)
```
Removes the specified component from this layout.

Specified by:

removeLayoutComponent in interface LayoutManager

Parameters:
comp - the component to be removed.
See Also:
Container.remove(java.awt.Component), Container.removeAll()

minimumLayoutSize
```
public Dimension minimumLayoutSize(Container parent)
```
Determines the minimum size of the parent containe using this form layout.

Specified by:

minimumLayoutSize in interface LayoutManager

Parameters:
parent - the container in which to do the layout

Returns:
the minimum size of the parent container
See Also:
Container.doLayout()

preferredLayoutSize
```
public Dimension preferredLayoutSize(Container parent)
```
Determines the preferred size of the parent

Specified by:

preferredLayoutSize in interface LayoutManager

Parameters:
parent - the container in which to do the layout

Returns:
the preferred size of the parent container
See Also:
Container.getPreferredSize()

maximumLayoutSize
```
public Dimension maximumLayoutSize(Container target)
```
Returns the maximum dimensions for this layout given the component in the specified target container.

Specified by:

maximumLayoutSize in interface LayoutManager2

Parameters:
target - the container which needs to be laid out

Returns:
the maximum dimensions for this layout
See Also:
Container, minimumLayoutSize(Container), preferredLayoutSize(Container)

getLayoutAlignmentX
```
public float getLayoutAlignmentX(Container parent)
```
Returns the alignment along the x axis. This specifies ho the component would like to be aligned relative to othe components. The value should be a number between 0 and where 0 represents alignment along the origin, 1 is aligne the farthest away from the origin, 0.5 is centered, etc.

Specified by:

getLayoutAlignmentX in interface LayoutManager2

Parameters:
parent - the parent container

Returns:
the value 0.5f to indicate center alignment

getLayoutAlignmentY
```
public float getLayoutAlignmentY(Container parent)
```
Returns the alignment along the y axis. This specifies ho the component would like to be aligned relative to othe components. The value should be a number between 0 and where 0 represents alignment along the origin, 1 is aligne the farthest away from the origin, 0.5 is centered, etc.

Specified by:

getLayoutAlignmentY in interface LayoutManager2

Parameters:
parent - the parent container

Returns:
the value 0.5f to indicate center alignment

invalidateLayout
```
public void invalidateLayout(Container target)
```
Invalidates the layout, indicating that if the layout manage has cached information it should be discarded.

Specified by:

invalidateLayout in interface LayoutManager2

Parameters:
target - the container that holds the layout to be invalidated

layoutContainer
```
public void layoutContainer(Container parent)
```
Lays out the specified container using this form layout. This metho reshapes components in the specified container in order to satisf the constraints of this FormLayout object.
find components that occupy exactly one column or ro
compute minimum widths and height
compute preferred widths and height
give cols and row equal size if they share a grou
compress default columns and rows if total is less than pref siz
give cols and row equal size if they share a grou
distribute free spac
set components bound

Class FormLayout

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FormLayout

FormLayout

FormLayout

FormLayout

FormLayout

FormLayout

FormLayout

Method Detail

getColumnCount

getColumnSpec

setColumnSpec

appendColumn

insertColumn

removeColumn

getRowCount

getRowSpec

setRowSpec

appendRow

insertRow

removeRow

getConstraints

setConstraints

getColumnGroups

setColumnGroups

setColumnGroup

addGroupedColumn

getRowGroups

setRowGroups

setRowGroup

addGroupedRow

getHonorsVisibility

setHonorsVisibility

setHonorsVisibility

addLayoutComponent

addLayoutComponent

removeLayoutComponent

minimumLayoutSize

preferredLayoutSize

maximumLayoutSize

getLayoutAlignmentX

getLayoutAlignmentY

invalidateLayout

layoutContainer

getLayoutInfo