com.jgoodies.forms.layout
public final class FormLayout extends Object implements LayoutManager2, Serializable
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 {@link ColumnSpec} and {@link RowSpec} instances.
Each component managed by a FormLayout is associated with an instance of
{@link 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 {@link 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 {@link 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("/u2026"), cc.xy (5, 5)); return panel;
Example 2 (Using PanelBuilder):
This example creates the same panel as above using the
{@link 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("/u2026"), cc.xy (5, 5)); return builder.getPanel();
Example 3 (Using DefaultFormBuilder):
This example utilizes the
{@link com.jgoodies.forms.builder.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();
TODO: In the Forms 1.0.x invisible components are not taken into account when the FormLayout lays out the container. Add an optional setting for this on both the container-level and component-level. So one can specify that invisible components shall be taken into account, but may exclude individual components. Or the other way round, exclude invisible components, and include individual components. The API of both the FormLayout and CellConstraints classes shall be extended to support this option. This feature is planned for the Forms version 1.1 and is described in issue #28 of the Forms' issue tracker where you can track the progress.
Version: $Revision: 1.6 $
See Also: ColumnSpec RowSpec CellConstraints AbstractFormBuilder ButtonBarBuilder DefaultFormBuilder FormFactory Size Sizes
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(String encodedColumnSpecs)
Constructs a FormLayout using the given encoded column specifications.
| |
FormLayout(String encodedColumnSpecs, String encodedRowSpecs)
Constructs a FormLayout using the given
encoded column and row specifications. 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"); // rowsSee the class comment for more examples. | |
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.
|
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(String name, Component component)
Throws an UnsupportedOperationException . |
void | addLayoutComponent(Component comp, Object constraints)
Adds the specified component to the layout, using the specified
constraints object. |
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 ColumnSpec at the specified column index.
|
CellConstraints | getConstraints(Component component)
Looks up and returns the constraints for the specified component.
|
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 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 parent container
using this form layout.Most applications do not call this method directly. |
Dimension | preferredLayoutSize(Container parent)
Determines the preferred size of the parent
container using this form layout.Most applications do not call this method directly. |
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. Most applications do not call this method directly. |
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 | 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.
|
This constructor is intended to be used in environments that add columns and rows dynamically.
This constructor is primarily 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.
Parameters: encodedColumnSpecs comma separated encoded column specifications
Throws: NullPointerException if encodedColumnSpecs is null
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"); // rowsSee the class comment for more examples.
Parameters: encodedColumnSpecs comma separated encoded column specifications encodedRowSpecs comma separated encoded row specifications
Throws: NullPointerException if encodedColumnSpecs or encodedRowSpecs
is null
Parameters: colSpecs an array of column specifications.
Throws: NullPointerException if colSpecs is null
Since: 1.1
Parameters: colSpecs an array of column specifications. rowSpecs an array of row specifications.
Throws: NullPointerException if colSpecs or rowSpecs is null
Parameters: columnIndex the column index to be set grouped
Parameters: rowIndex the index of the row that should be grouped
UnsupportedOperationException
. Does not add
the specified component with the specified name to the layout.
Parameters: name indicates entry's position and anchor component component to add
Throws: UnsupportedOperationException always
constraints
object. Note that constraints are mutable and
are, therefore, cloned when cached.
Parameters: comp the component to be added constraints the component's cell constraints
Throws: NullPointerException if constraints
is null
IllegalArgumentException if constraints
is not a
CellConstraints
or a String that cannot be used to construct
a CellConstraints
Parameters: columnSpec the column specification to be added
Throws: NullPointerException if the column specification is null
Parameters: rowSpec the row specification to be added to the form layout
Throws: NullPointerException if the rowSpec is null
Returns: the number of columns
Returns: the column groups as two-dimensional int array
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
CellConstraints
object is returned.
Parameters: component the component to be queried
Returns: the CellConstraints
for the specified component
Throws: NullPointerException if component is null
or
has not been added to the container
Parameters: parent the parent container
Returns: the value 0.5f
to indicate center alignment
Parameters: parent the parent container
Returns: the value 0.5f
to indicate center alignment
#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.
Parameters: parent the Container
to inspect
Returns: an object that comprises the grid x and y origins
Returns: the number of rows
Returns: the row groups as two-dimensional int array
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
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 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 rowSpec specification of the row to be inserted
Throws: IndexOutOfBoundsException if the row index is out of range
Parameters: target the container that holds the layout to be invalidated
FormLayout
object.Most applications do not call this method directly.
The form layout performs the following steps:
Parameters: parent the container in which to do the layout
See Also: Container Container#doLayout()
Parameters: target the container which needs to be laid out
Returns: the maximum dimensions for this layout
See Also: Container minimumLayoutSize preferredLayoutSize
parent
container
using this form layout.Most applications do not call this method directly.
Parameters: parent the container in which to do the layout
Returns: the minimum size of the parent
container
See Also: Container#doLayout()
parent
container using this form layout.Most applications do not call this method directly.
Parameters: parent the container in which to do the layout
Returns: 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 IllegalStateException if the column contains components or if the column is already grouped
See Also: FormLayoutUtils FormLayoutUtils
Most applications do not call this method directly.
Parameters: comp the component to be removed.
See Also: Container#remove(java.awt.Component) 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 IllegalStateException if the row contains components or if the row is already grouped
See Also: FormLayoutUtils FormLayoutUtils
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}});
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
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 the column specification is null IndexOutOfBoundsException if the column index is out of range
Parameters: component the component to be modified constraints the constraints to be applied
Throws: NullPointerException if the component or constraints object
is null
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}});
Parameters: rowGroupIndices a two-dimensional array of row group indices.
Throws: IndexOutOfBoundsException if an index is outside the grid
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 the row specification is null IndexOutOfBoundsException if the row index is out of range