public final class FormLayout
extends java.lang.Object
implements java.awt.LayoutManager2, java.io.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 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. 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("/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);
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
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.
ColumnSpec,
RowSpec,
CellConstraints,
AbstractFormBuilder,
ButtonBarBuilder,
DefaultFormBuilder,
FormFactory,
Size,
Sizes,
Serialized Form| Modifier and Type | Class and Description |
|---|---|
static class |
FormLayout.LayoutInfo
Stores column and row origins.
|
(package private) static interface |
FormLayout.Measure
An interface that describes how to measure a
Component. |
| Constructor and Description |
|---|
FormLayout()
Constructs an empty FormLayout.
|
FormLayout(ColumnSpec[] colSpecs,
RowSpec[] rowSpecs)
Constructs a FormLayout using the given column and row specifications.
|
FormLayout(java.lang.String encodedColumnSpecs)
Constructs a FormLayout using the given encoded column specifications.
|
FormLayout(java.lang.String encodedColumnSpecs,
java.lang.String encodedRowSpecs)
Constructs a FormLayout using the given
encoded column and row specifications.
|
| 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(java.awt.Component comp,
java.lang.Object constraints)
Adds the specified component to the layout, using the specified
constraints object. |
void |
addLayoutComponent(java.lang.String name,
java.awt.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
ColumnSpec at the specified column index. |
CellConstraints |
getConstraints(java.awt.Component component)
Looks up and returns the constraints for the specified component.
|
float |
getLayoutAlignmentX(java.awt.Container parent)
Returns the alignment along the x axis.
|
float |
getLayoutAlignmentY(java.awt.Container parent)
Returns the alignment along the y axis.
|
FormLayout.LayoutInfo |
getLayoutInfo(java.awt.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(java.awt.Container target)
Invalidates the layout, indicating that if the layout manager
has cached information it should be discarded.
|
void |
layoutContainer(java.awt.Container parent)
Lays out the specified container using this form layout.
|
java.awt.Dimension |
maximumLayoutSize(java.awt.Container target)
Returns the maximum dimensions for this layout given the components
in the specified target container.
|
java.awt.Dimension |
minimumLayoutSize(java.awt.Container parent)
Determines the minimum size of the
parent container
using this form layout. |
java.awt.Dimension |
preferredLayoutSize(java.awt.Container parent)
Determines the preferred size of the
parent
container using this form layout. |
void |
removeColumn(int columnIndex)
Removes the column with the given column index from the layout.
|
void |
removeLayoutComponent(java.awt.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(java.awt.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. |
public FormLayout()
This constructor is intended to be used in environments that add columns and rows dynamically.
public FormLayout(java.lang.String encodedColumnSpecs)
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.encodedColumnSpecs - comma separated encoded column specificationsjava.lang.NullPointerException - if encodedColumnSpecs is nullpublic FormLayout(java.lang.String encodedColumnSpecs,
java.lang.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 specificationsjava.lang.NullPointerException - if encodedColumnSpecs or encodedRowSpecs
is nullpublic FormLayout(ColumnSpec[] colSpecs, RowSpec[] rowSpecs)
colSpecs - an array of column specifications.rowSpecs - an array of row specifications.java.lang.NullPointerException - if colSpecs or rowSpecs is nullpublic int getColumnCount()
public int getRowCount()
public ColumnSpec getColumnSpec(int columnIndex)
ColumnSpec at the specified column index.columnIndex - the column index of the requested ColumnSpecColumnSpec at the specified columnjava.lang.IndexOutOfBoundsException - if the column index is out of rangepublic void setColumnSpec(int columnIndex,
ColumnSpec columnSpec)
ColumnSpec at the specified column index.columnIndex - the index of the column to be changedcolumnSpec - the ColumnSpec to be setjava.lang.NullPointerException - if the column specification is nulljava.lang.IndexOutOfBoundsException - if the column index is out of rangepublic RowSpec getRowSpec(int rowIndex)
RowSpec at the specified row index.rowIndex - the row index of the requested RowSpecRowSpec at the specified rowjava.lang.IndexOutOfBoundsException - if the row index is out of rangepublic void setRowSpec(int rowIndex,
RowSpec rowSpec)
RowSpec at the specified row index.rowIndex - the index of the row to be changedrowSpec - the RowSpec to be setjava.lang.NullPointerException - if the row specification is nulljava.lang.IndexOutOfBoundsException - if the row index is out of rangepublic void appendColumn(ColumnSpec columnSpec)
columnSpec - the column specification to be addedjava.lang.NullPointerException - if the column specification is nullpublic 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 insertedjava.lang.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 removejava.lang.IndexOutOfBoundsException - if the column index is out of rangejava.lang.IllegalStateException - if the column contains components
or if the column is already groupedpublic void appendRow(RowSpec rowSpec)
rowSpec - the row specification to be added to the form layoutjava.lang.NullPointerException - if the rowSpec is nullpublic 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 insertedjava.lang.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 removejava.lang.IndexOutOfBoundsException - if the row index is out of rangejava.lang.IllegalStateException - if the row contains components
or if the row is already groupedpublic CellConstraints getConstraints(java.awt.Component component)
CellConstraints object is returned.component - the component to be queriedCellConstraints for the specified componentjava.lang.NullPointerException - if component is null or
has not been added to the containerpublic void setConstraints(java.awt.Component component,
CellConstraints constraints)
component - the component to be modifiedconstraints - the constraints to be appliedjava.lang.NullPointerException - if the component or constraints object
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 indicesjava.lang.IndexOutOfBoundsException - if an index is outside the gridjava.lang.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.java.lang.IndexOutOfBoundsException - if an index is outside the gridpublic void addGroupedRow(int rowIndex)
rowIndex - the index of the row that should be groupedpublic void addLayoutComponent(java.lang.String name,
java.awt.Component component)
UnsupportedOperationException. Does not add
the specified component with the specified name to the layout.addLayoutComponent in interface java.awt.LayoutManagername - indicates entry's position and anchorcomponent - component to addjava.lang.UnsupportedOperationException - alwayspublic void addLayoutComponent(java.awt.Component comp,
java.lang.Object constraints)
constraints object. Note that constraints are mutable and
are, therefore, cloned when cached.addLayoutComponent in interface java.awt.LayoutManager2comp - the component to be addedconstraints - the component's cell constraintsjava.lang.NullPointerException - if constraints is nulljava.lang.IllegalArgumentException - if constraints is not a
CellConstraints or a String that cannot be used to construct
a CellConstraintspublic void removeLayoutComponent(java.awt.Component comp)
Most applications do not call this method directly.
removeLayoutComponent in interface java.awt.LayoutManagercomp - the component to be removed.Container.remove(java.awt.Component),
Container.removeAll()public java.awt.Dimension minimumLayoutSize(java.awt.Container parent)
parent container
using this form layout.Most applications do not call this method directly.
minimumLayoutSize in interface java.awt.LayoutManagerparent - the container in which to do the layoutparent containerContainer.doLayout()public java.awt.Dimension preferredLayoutSize(java.awt.Container parent)
parent
container using this form layout.Most applications do not call this method directly.
preferredLayoutSize in interface java.awt.LayoutManagerparent - the container in which to do the layoutparent containerContainer.getPreferredSize()public java.awt.Dimension maximumLayoutSize(java.awt.Container target)
maximumLayoutSize in interface java.awt.LayoutManager2target - the container which needs to be laid outContainer,
minimumLayoutSize(Container),
preferredLayoutSize(Container)public float getLayoutAlignmentX(java.awt.Container parent)
getLayoutAlignmentX in interface java.awt.LayoutManager2parent - the parent container0.5f to indicate center alignmentpublic float getLayoutAlignmentY(java.awt.Container parent)
getLayoutAlignmentY in interface java.awt.LayoutManager2parent - the parent container0.5f to indicate center alignmentpublic void invalidateLayout(java.awt.Container target)
invalidateLayout in interface java.awt.LayoutManager2target - the container that holds the layout to be invalidatedpublic void layoutContainer(java.awt.Container parent)
FormLayout object.Most applications do not call this method directly.
The form layout performs the following steps:
layoutContainer in interface java.awt.LayoutManagerparent - the container in which to do the layoutContainer,
Container.doLayout()public FormLayout.LayoutInfo getLayoutInfo(java.awt.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