com.jgoodies.forms.layout
Class FormLayout

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




static class
FormLayout.LayoutInfo



          Stores column and row origins.



static interface
FormLayout.Measure



          An interface that describes how to measure a Component.


 



Constructor Summary
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




 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
setColumnGroups(int[][] colGroupIndices)



          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
setRowGroups(int[][] rowGroupIndices)



          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[][] colGroupIndices)

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:
colGroupIndices - 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





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[][] rowGroupIndices)

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:
rowGroupIndices - a two-dimensional array of row group indices.
Throws:
IndexOutOfBoundsException - if an index is outside the grid





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
 


Specified by:
layoutContainer in interface LayoutManager


Parameters:
parent - the container in which to do the layout
See Also:
Container, 
Container.doLayout()





getLayoutInfo
public FormLayout.LayoutInfo getLayoutInfo(Container parent)

Computes and returns the horizontal and vertical grid origins
 Performs the same layout process as #layoutContainerYou must not call this method directly
 It may be removed in a future release or the visibilit
 may be reduced.





Parameters:
parent - the Container to inspect
Returns:
an object that comprises the grid x and y origins