| 
 | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectcom.jgoodies.forms.layout.FormLayout
public final class FormLayout
FormLayout is a powerful, flexible and precise general purpose layout manager. It aligns components vertically and horizontally in a dynamic rectangular grid of cells, with each component occupying one or more cells. A whitepaper about the FormLayout ships with the product documentation and is available online.
 To use FormLayout you first define the grid by specifying the
 columns and rows. In a second step you add components to the grid. You can
 specify columns and rows via human-readable String descriptions or via
 arrays of ColumnSpec and RowSpec instances.
 Each component managed by a FormLayout is associated with an instance of
 CellConstraints. The constraints object specifies where a component
 should be located on the form's grid and how the component should be
 positioned. In addition to its constraints object the
 FormLayout also considers each component's minimum and
 preferred sizes in order to determine a component's size.
 FormLayout has been designed to work with non-visual builders that help you
 specify the layout and fill the grid. For example, the
 ButtonBarBuilder assists you in building button
 bars; it creates a standardized FormLayout and provides a minimal API that
 specializes in adding buttons and Actions. Other builders can create
 frequently used panel design, for example a form that consists of rows of
 label-component pairs.
 FormLayout has been prepared to work with different types of sizes as
 defined by the Size interface.
 Example 1 (Plain FormLayout):
 The following example creates a panel with 3 data columns and 3 data rows;
 the columns and rows are specified before components are added
 to the form.
 
 FormLayout layout = new FormLayout(
      "right:pref, 6dlu, 50dlu, 4dlu, default",  // columns
      "pref, 3dlu, pref, 3dlu, pref");           // rows
 JPanel panel = new JPanel(layout);
 panel.add(new JLabel("Label1"),   CC.xy  (1, 1));
 panel.add(new JTextField(),       CC.xywh(3, 1, 3, 1));
 panel.add(new JLabel("Label2"),   CC.xy  (1, 3));
 panel.add(new JTextField(),       CC.xy  (3, 3));
 panel.add(new JLabel("Label3"),   CC.xy  (1, 5));
 panel.add(new JTextField(),       CC.xy  (3, 5));
 panel.add(new JButton("/u2026"),  CC.xy  (5, 5));
 return panel;
 
 Example 2 (Using PanelBuilder):
 This example creates the same panel as above using the
 PanelBuilder to add components to the form.
 
 FormLayout layout = new FormLayout(
      "right:pref, 6dlu, 50dlu, 4dlu, default",  // columns
      "pref, 3dlu, pref, 3dlu, pref");           // rows
 PanelBuilder builder = new PanelBuilder(layout);
 builder.addLabel("Label1",         CC.xy  (1, 1));
 builder.add(new JTextField(),      CC.xywh(3, 1, 3, 1));
 builder.addLabel("Label2",         CC.xy  (1, 3));
 builder.add(new JTextField(),      CC.xy  (3, 3));
 builder.addLabel("Label3",         CC.xy  (1, 5));
 builder.add(new JTextField(),      CC.xy  (3, 5));
 builder.add(new JButton("/u2026"), CC.xy  (5, 5));
 return builder.getPanel();
 
 Example 3 (Using DefaultFormBuilder):
 This example utilizes the
 DefaultFormBuilder that
 ships with the source distribution.
 
 FormLayout layout = new FormLayout(
      "right:pref, 6dlu, 50dlu, 4dlu, default"); // 5 columns; add rows later
 DefaultFormBuilder builder = new DefaultFormBuilder(layout);
 builder.append("Label1", new JTextField(), 3);
 builder.append("Label2", new JTextField());
 builder.append("Label3", new JTextField());
 builder.append(new JButton("/u2026"));
 return builder.getPanel();
 
ColumnSpec, 
RowSpec, 
CellConstraints, 
AbstractFormBuilder, 
ButtonBarBuilder, 
DefaultFormBuilder, 
FormSpecs, 
Size, 
Sizes, 
Serialized Form| Nested Class Summary | |
|---|---|
| static class | FormLayout.LayoutInfoStores column and row origins. | 
| static interface | FormLayout.MeasureAn 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 specifications and LayoutMap. | |
| FormLayout(String encodedColumnSpecs,
           String encodedRowSpecs)Constructs a FormLayout using the given encoded column and row specifications and the default LayoutMap. | |
| FormLayout(String encodedColumnSpecs,
           String encodedRowSpecs,
           LayoutMap layoutMap)Constructs a FormLayout using the given 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 specified constraintsobject. | 
|  void | addLayoutComponent(String name,
                   Component component)Throws an UnsupportedOperationException. | 
|  void | appendColumn(ColumnSpec columnSpec)Appends the given column specification to the right hand side of all 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 ColumnSpecat 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 account 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 RowSpecat 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 manager 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 components in the specified target container. | 
|  Dimension | minimumLayoutSize(Container parent)Determines the minimum size of the parentcontainer
 using this form layout. | 
|  Dimension | preferredLayoutSize(Container parent)Determines the preferred size of the parentcontainer using this form layout. | 
|  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 same 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 by 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 account for sizing and positioning. | 
|  void | setRowGroups(int[][] rowGroupIndices)Sets the row groups, where each row in such a group gets the same group 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 | 
|---|
public FormLayout()
This constructor is intended to be used in environments that add columns and rows dynamically.
public FormLayout(String encodedColumnSpecs)
 This constructor is intended to be used with builder classes that
 add rows dynamically, such as the DefaultFormBuilder.
Examples:
 // Label, gap, component
 FormLayout layout = new FormLayout(
      "pref, 4dlu, pref");
 // Right-aligned label, gap, component, gap, component
 FormLayout layout = new FormLayout(
      "right:pref, 4dlu, 50dlu, 4dlu, 50dlu");
 // Left-aligned labels, gap, components, gap, components
 FormLayout layout = new FormLayout(
      "left:pref, 4dlu, pref, 4dlu, pref");
  See the class comment for more examples.
encodedColumnSpecs - comma separated encoded column specifications
NullPointerException - if encodedColumnSpecs is nullLayoutMap.getRoot()
public FormLayout(String encodedColumnSpecs,
                  LayoutMap layoutMap)
 This constructor is intended to be used with builder classes that
 add rows dynamically, such as the DefaultFormBuilder.
Examples:
 // Label, gap, component
 FormLayout layout = new FormLayout(
      "pref, 4dlu, pref",
      myLayoutMap);
 // Right-aligned label, gap, component, gap, component
 FormLayout layout = new FormLayout(
      "right:pref, @lcgap, 50dlu, 4dlu, 50dlu",
      myLayoutMap);
 // Left-aligned labels, gap, components, gap, components
 FormLayout layout = new FormLayout(
      "left:pref, @lcgap, pref, @myGap, pref",
      myLayoutMap);
  See the class comment for more examples.
encodedColumnSpecs - comma separated encoded column specificationslayoutMap - expands layout column and row variables
NullPointerException - if encodedColumnSpecs or
     layoutMap is nullLayoutMap.getRoot()
public FormLayout(String encodedColumnSpecs,
                  String encodedRowSpecs)
This constructor is recommended for most hand-coded layouts.
Examples:
 FormLayout layout = new FormLayout(
      "pref, 4dlu, pref",               // columns
      "p, 3dlu, p");                    // rows
 FormLayout layout = new FormLayout(
      "right:pref, 4dlu, pref",         // columns
      "p, 3dlu, p, 3dlu, fill:p:grow"); // rows
 FormLayout layout = new FormLayout(
      "left:pref, 4dlu, 50dlu",         // columns
      "p, 2px, p, 3dlu, p, 9dlu, p");   // rows
 FormLayout layout = new FormLayout(
      "max(75dlu;pref), 4dlu, default", // columns
      "p, 3dlu, p, 3dlu, p, 3dlu, p");  // rows
  See the class comment for more examples.
encodedColumnSpecs - comma separated encoded column specificationsencodedRowSpecs - comma separated encoded row specifications
NullPointerException - if encodedColumnSpecs or encodedRowSpecs
     is nullLayoutMap.getRoot()
public FormLayout(String encodedColumnSpecs,
                  String encodedRowSpecs,
                  LayoutMap layoutMap)
Examples:
 FormLayout layout = new FormLayout(
      "pref, 4dlu, pref",               // columns
      "p, 3dlu, p",                     // rows
      myLayoutMap);                     // custom LayoutMap
 FormLayout layout = new FormLayout(
      "right:pref, 4dlu, pref",         // columns
      "p, @lgap, p, @lgap, fill:p:grow",// rows
      myLayoutMap);                     // custom LayoutMap
 FormLayout layout = new FormLayout(
      "left:pref, 4dlu, 50dlu",         // columns
      "p, 2px, p, 3dlu, p, 9dlu, p",    // rows
      myLayoutMap);                     // custom LayoutMap
 FormLayout layout = new FormLayout(
      "max(75dlu;pref), 4dlu, default", // columns
      "p, 3dlu, p, 3dlu, p, 3dlu, p",   // rows
      myLayoutMap);                     // custom LayoutMap
  See the class comment for more examples.
encodedColumnSpecs - comma separated encoded column specificationsencodedRowSpecs - comma separated encoded row specificationslayoutMap - expands layout column and row variables
NullPointerException - if encodedColumnSpecs,
     encodedRowSpecs, or layoutMap is nullpublic FormLayout(ColumnSpec[] colSpecs)
colSpecs - an array of column specifications.
NullPointerException - if colSpecs is null
public FormLayout(ColumnSpec[] colSpecs,
                  RowSpec[] rowSpecs)
colSpecs - an array of column specifications.rowSpecs - an array of row specifications.
NullPointerException - if colSpecs or rowSpecs
     is null| Method Detail | 
|---|
public int getColumnCount()
public ColumnSpec getColumnSpec(int columnIndex)
ColumnSpec at the specified column index.
columnIndex - the column index of the requested ColumnSpec
ColumnSpec at the specified column
IndexOutOfBoundsException - if the column index is out of range
public void setColumnSpec(int columnIndex,
                          ColumnSpec columnSpec)
columnIndex - the index of the column to be changedcolumnSpec - the ColumnSpec to be set
NullPointerException - if columnSpec is null
IndexOutOfBoundsException - if the column index is out of rangepublic void appendColumn(ColumnSpec columnSpec)
columnSpec - the column specification to be added
NullPointerException - if columnSpec is null
public void insertColumn(int columnIndex,
                         ColumnSpec columnSpec)
The component shift works as follows: components that were located on the right hand side of the inserted column are shifted one column to the right; component column span is increased by one if it intersects the new column.
Column group indices that are greater or equal than the given column index will be increased by one.
columnIndex - index of the column to be insertedcolumnSpec - specification of the column to be inserted
IndexOutOfBoundsException - if the column index is out of rangepublic void removeColumn(int columnIndex)
The component shift works as follows: components that were located on the right hand side of the removed column are moved one column to the left; component column span is decreased by one if it intersects the removed column.
Column group indices that are greater than the column index will be decreased by one.
 Note: If one of the constraints mentioned above
 is violated, this layout's state becomes illegal and it is unsafe
 to work with this layout.
 A typical layout implementation can ensure that these constraints are
 not violated. However, in some cases you may need to check these
 conditions before you invoke this method. The Forms extras contain
 source code for class FormLayoutUtils that provides
 the required test methods:
 #columnContainsComponents(Container, int) and
 #isGroupedColumn(FormLayout, int).
columnIndex - index of the column to remove
IndexOutOfBoundsException - if the column index is out of range
IllegalStateException - if the column contains components
     or if the column is already groupedFormLayoutUtils.columnContainsComponent(Container, int), 
FormLayoutUtils.isGroupedColumn(FormLayout, int)public int getRowCount()
public RowSpec getRowSpec(int rowIndex)
RowSpec at the specified row index.
rowIndex - the row index of the requested RowSpec
RowSpec at the specified row
IndexOutOfBoundsException - if the row index is out of range
public void setRowSpec(int rowIndex,
                       RowSpec rowSpec)
rowIndex - the index of the row to be changedrowSpec - the RowSpec to be set
NullPointerException - if rowSpec is null
IndexOutOfBoundsException - if the row index is out of rangepublic void appendRow(RowSpec rowSpec)
rowSpec - the row specification to be added to the form layout
NullPointerException - if rowSpec is null
public void insertRow(int rowIndex,
                      RowSpec rowSpec)
The component shift works as follows: components that were located on the right hand side of the inserted column are shifted one column to the right; component column span is increased by one if it intersects the new column.
Column group indices that are greater or equal than the given column index will be increased by one.
rowIndex - index of the row to be insertedrowSpec - specification of the row to be inserted
IndexOutOfBoundsException - if the row index is out of rangepublic void removeRow(int rowIndex)
The component shift works as follows: components that were located below the removed row are moved up one row; component row span is decreased by one if it intersects the removed row.
Row group indices that are greater than the row index will be decreased by one.
 Note: If one of the constraints mentioned above
 is violated, this layout's state becomes illegal and it is unsafe
 to work with this layout.
 A typical layout implementation can ensure that these constraints are
 not violated. However, in some cases you may need to check these
 conditions before you invoke this method. The Forms extras contain
 source code for class FormLayoutUtils that provides
 the required test methods:
 #rowContainsComponents(Container, int) and
 #isGroupedRow(FormLayout, int).
rowIndex - index of the row to remove
IndexOutOfBoundsException - if the row index is out of range
IllegalStateException - if the row contains components
     or if the row is already groupedFormLayoutUtils.rowContainsComponent(Container, int), 
FormLayoutUtils.isGroupedRow(FormLayout, int)public CellConstraints getConstraints(Component component)
component - the component to be queried
NullPointerException - if component is null
IllegalStateException - if component has not been
     added to the container
public void setConstraints(Component component,
                           CellConstraints constraints)
component - the component to be modifiedconstraints - the constraints to be applied
NullPointerException - if component or constraints
     is nullpublic int[][] getColumnGroups()
public void setColumnGroups(int[][] colGroupIndices)
Examples:
 // Group columns 1, 3 and 4.
 setColumnGroups(new int[][]{ {1, 3, 4}});
 // Group columns 1, 3, 4, and group columns 7 and 9
 setColumnGroups(new int[][]{ {1, 3, 4}, {7, 9}});
 
colGroupIndices - a two-dimensional array of column groups indices
IndexOutOfBoundsException - if an index is outside the grid
IllegalArgumentException - if a column index is used twicepublic void addGroupedColumn(int columnIndex)
columnIndex - the column index to be set groupedpublic int[][] getRowGroups()
public void setRowGroups(int[][] rowGroupIndices)
Examples:
 // Group rows 1 and 2.
 setRowGroups(new int[][]{ {1, 2}});
 // Group rows 1 and 2, and group rows 5, 7, and 9.
 setRowGroups(new int[][]{ {1, 2}, {5, 7, 9}});
 
rowGroupIndices - a two-dimensional array of row group indices.
IndexOutOfBoundsException - if an index is outside the gridpublic void addGroupedRow(int rowIndex)
rowIndex - the index of the row that should be groupedpublic boolean getHonorsVisibility()
setHonorsVisibility(boolean) for details.
true if the component visibility is honored
     by this FormLayout, false if it is ignored.
     This setting can be overridden for individual CellConstraints
     using setHonorsVisibility(Component, Boolean).public void setHonorsVisibility(boolean b)
true invisible components will be ignored by
 the layout. If set to false components will be taken into
 account regardless of their visibility. Visible components are always
 used for sizing and positioning.
 The default value for this setting is true.
 It is useful to set the value to false (in other words
 to ignore the visibility) if you switch the component visibility
 dynamically and want the container to retain the size and
 component positions.
 This container-wide default setting can be overridden per component
 using setHonorsVisibility(Component, Boolean).
Components are taken into account, if
false), or
 
b - true to honor the visibility, i.e. to exclude
    invisible components from the sizing and positioning,
    false to ignore the visibility, in other words to
    layout visible and invisible components
public void setHonorsVisibility(Component component,
                                Boolean b)
setHonorsVisibility(boolean) for details.
component - the component that shall get an individual settingb - Boolean.TRUE to override the container
    default and honor the visibility for the given component,
    Boolean.FALSE to override the container default and
    ignore the visibility for the given component,
    null to use the container default value as specified
    by getHonorsVisibility().
public void addLayoutComponent(String name,
                               Component component)
UnsupportedOperationException. Does not add
 the specified component with the specified name to the layout.
addLayoutComponent in interface LayoutManagername - indicates entry's position and anchorcomponent - component to add
UnsupportedOperationException - always
public void addLayoutComponent(Component comp,
                               Object constraints)
constraints object.  Note that constraints are mutable and
 are, therefore, cloned when cached.
addLayoutComponent in interface LayoutManager2comp - the component to be addedconstraints - the component's cell constraints
NullPointerException - if constraints is null
IllegalArgumentException - if constraints is neither
     a String, nor a CellConstraints object,
     or a String that is rejected by the CellConstraints constructionpublic void removeLayoutComponent(Component comp)
Most applications do not call this method directly.
removeLayoutComponent in interface LayoutManagercomp - the component to be removed.Container.remove(java.awt.Component), 
Container.removeAll()public Dimension minimumLayoutSize(Container parent)
parent container
 using this form layout.Most applications do not call this method directly.
minimumLayoutSize in interface LayoutManagerparent - the container in which to do the layout
parent containerContainer.doLayout()public Dimension preferredLayoutSize(Container parent)
parent
 container using this form layout.Most applications do not call this method directly.
preferredLayoutSize in interface LayoutManagerparent - the container in which to do the layout
parent containerContainer.getPreferredSize()public Dimension maximumLayoutSize(Container target)
maximumLayoutSize in interface LayoutManager2target - the container which needs to be laid out
Container, 
minimumLayoutSize(Container), 
preferredLayoutSize(Container)public float getLayoutAlignmentX(Container parent)
getLayoutAlignmentX in interface LayoutManager2parent - the parent container
0.5f to indicate center alignmentpublic float getLayoutAlignmentY(Container parent)
getLayoutAlignmentY in interface LayoutManager2parent - the parent container
0.5f to indicate center alignmentpublic void invalidateLayout(Container target)
invalidateLayout in interface LayoutManager2target - the container that holds the layout to be invalidatedpublic void layoutContainer(Container parent)
FormLayout object.Most applications do not call this method directly.
The form layout performs the following steps:
layoutContainer in interface LayoutManagerparent - the container in which to do the layoutContainer, 
Container.doLayout()public FormLayout.LayoutInfo getLayoutInfo(Container parent)
#layoutContainer
 but does not layout the components.This method has been added only to make it easier to debug the form layout. You must not call this method directly; It may be removed in a future release or the visibility may be reduced.
parent - the Container to inspect
| 
 | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||