Java Doc for FormLayout.java in  » Swing-Library » abeille-forms-designer » com » jgoodies » forms » layout » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 com.jgoodies.forms.builder.ButtonBarBuilder assists you in building button bars; it creates a standardized FormLayout and provides a minimal API that specializes in adding buttons. 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
 CellConstraints cc = new CellConstraints();
 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("..."), cc.xy(5, 5));
 return panel;
 

Example 2 (Using PanelBuilder):
This example creates the same panel as above using the com.jgoodies.forms.builder.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);
 CellConstraints cc = new CellConstraints();
 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("..."), cc.xy(5, 5));
 return builder.getPanel();
 

Example 3 (Using DefaultFormBuilder):
This example utilizes the com.jgoodies.forms.builder.DefaultFormBuilder that ships with the source distribution.

 FormLayout layout = new FormLayout("right:pref, 6dlu, 50dlu, 4dlu, default", // columns 
 ""); // add rows dynamically
 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("..."));
 return builder.getPanel();
 

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.

See the class comment for examples.
Parameters:
  encodedColumnSpecs - comma separated encoded column specifications
Parameters:
  encodedRowSpecs - comma separated encoded row specifications
throws:
  NullPointerException - if encodedColumnSpecs or encodedRowSpecs is null

This constructor is primarily intended to be used with builder classes that add rows dynamically, such as the DefaultFormBuilder.

See the class comment for examples.
Parameters:
  encodedColumnSpecs - comma separated encoded column specifications
throws:
  NullPointerException - if encodedColumnSpecs is null

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.
Parameters:
  parent - the Container to inspect an object that comprises the grid x and y origins

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.
Parameters:
  columnIndex - index of the column to be inserted
Parameters:
  columnSpec - specification of the column to be inserted
throws:
  IndexOutOfBoundsException - if the column index is out of range

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.
Parameters:
  rowIndex - index of the row to be inserted
Parameters:
  rowSpec - specification of the row to be inserted
throws:
  IndexOutOfBoundsException - if the row index is out of range

Most applications do not call this method directly.

The form layout performs the following steps:

1. find components that occupy exactly one column or row
2. compute minimum widths and heights
3. compute preferred widths and heights
4. give cols and row equal size if they share a group
5. compress default columns and rows if total is less than pref size
6. give cols and row equal size if they share a group
7. distribute free space
8. set components bounds

Most applications do not call this method directly.
Parameters:
  parent - the container in which to do the layout the minimum size of the parent container
See Also:   Container.doLayout

Most applications do not call this method directly.
Parameters:
  parent - the container in which to do the layout the preferred size of the parent container
See Also:   Container.getPreferredSize

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).
Parameters:
  columnIndex - index of the column to remove
throws:
  IndexOutOfBoundsException - if the column index is out of range
throws:
  IllegalStateException - if the column contains components or if the column is alreadygrouped
See Also:   com.jgoodies.forms.extras.FormLayoutUtils.columnContainsComponent(Containerint)
See Also:   com.jgoodies.forms.extras.FormLayoutUtils.isGroupedColumn(FormLayoutint)

Most applications do not call this method directly.
Parameters:
  comp - the component to be removed.
See Also:   Container.remove(java.awt.Component)
See Also:   Container.removeAll

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).
Parameters:
  rowIndex - index of the row to remove
throws:
  IndexOutOfBoundsException - if the row index is out of range
throws:
  IllegalStateException - if the row contains components or if the row is alreadygrouped
See Also:   com.jgoodies.forms.extras.FormLayoutUtils.rowContainsComponent(Containerint)
See Also:   com.jgoodies.forms.extras.FormLayoutUtils.isGroupedRow(FormLayoutint)

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 } });
 

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 } });