| java.lang.Object com.jgoodies.forms.layout.FormLayout
FormLayout | final public class FormLayout implements LayoutManager2,Serializable(Code) | | 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
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("/u2026"), 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("/u2026"), 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"); // 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.
author: Karsten Lentzsch version: $Revision: 1.6 $ See Also: ColumnSpec See Also: RowSpec See Also: CellConstraints See Also: com.jgoodies.forms.builder.AbstractFormBuilder See Also: com.jgoodies.forms.builder.ButtonBarBuilder See Also: com.jgoodies.forms.builder.DefaultFormBuilder See Also: com.jgoodies.forms.factories.FormFactory See Also: Size See Also: Sizes |
Inner Class :public static interface Measure | |
Inner Class :final public static class LayoutInfo | |
Constructor Summary | |
public | FormLayout() Constructs an empty FormLayout. | public | FormLayout(String encodedColumnSpecs) Constructs a FormLayout using the given encoded column specifications. | public | 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"); // rows
See the class comment for more examples. | public | FormLayout(ColumnSpec[] colSpecs) Constructs a FormLayout using the given column specifications. | public | FormLayout(ColumnSpec[] colSpecs, RowSpec[] rowSpecs) Constructs a FormLayout using the given column and row specifications. |
Method Summary | |
public void | addGroupedColumn(int columnIndex) Adds the specified column index to the last column group. | public void | addGroupedRow(int rowIndex) Adds the specified row index to the last row group. | public void | addLayoutComponent(String name, Component component) Throws an UnsupportedOperationException . | public void | addLayoutComponent(Component comp, Object constraints) Adds the specified component to the layout, using the specified
constraints object. | public void | appendColumn(ColumnSpec columnSpec) Appends the given column specification to the right hand side of all
columns. | public void | appendRow(RowSpec rowSpec) Appends the given row specification to the bottom of all rows. | public int | getColumnCount() Returns the number of columns in this layout. | public int[][] | getColumnGroups() Returns a deep copy of the column groups. | public ColumnSpec | getColumnSpec(int columnIndex) Returns the ColumnSpec at the specified column index. | public CellConstraints | getConstraints(Component component) Looks up and returns the constraints for the specified component. | public float | getLayoutAlignmentX(Container parent) Returns the alignment along the x axis. | public float | getLayoutAlignmentY(Container parent) Returns the alignment along the y axis. | public LayoutInfo | getLayoutInfo(Container parent) Computes and returns the horizontal and vertical grid origins.
Performs the same layout process as #layoutContainer
but does not layout the components.
This method has been added only to make it easier to debug
the form layout. | public int | getRowCount() Returns the number of rows in this layout. | public int[][] | getRowGroups() Returns a deep copy of the row groups. | public RowSpec | getRowSpec(int rowIndex) Returns the RowSpec at the specified row index. | public void | insertColumn(int columnIndex, ColumnSpec columnSpec) Inserts the specified column at the specified position. | public void | insertRow(int rowIndex, RowSpec rowSpec) Inserts the specified column at the specified position. | public void | invalidateLayout(Container target) Invalidates the layout, indicating that if the layout manager
has cached information it should be discarded. | public void | layoutContainer(Container parent) Lays out the specified container using this form layout. | public Dimension | maximumLayoutSize(Container target) Returns the maximum dimensions for this layout given the components
in the specified target container. | public Dimension | minimumLayoutSize(Container parent) Determines the minimum size of the parent container
using this form layout.
Most applications do not call this method directly. | public Dimension | preferredLayoutSize(Container parent) Determines the preferred size of the parent
container using this form layout.
Most applications do not call this method directly. | 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 part
of a column group.
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. | public void | removeLayoutComponent(Component comp) Removes the specified component from this layout.
Most applications do not call this method directly. | public void | removeRow(int rowIndex) Removes the row with the given row index from the layout. | public void | setColumnGroups(int[][] colGroupIndices) Sets the column groups, where each column in a group gets the same
group wide width. | public void | setColumnSpec(int columnIndex, ColumnSpec columnSpec) Sets the ColumnSpec at the specified column index. | public void | setConstraints(Component component, CellConstraints constraints) Sets the constraints for the specified component in this layout. | public void | setRowGroups(int[][] rowGroupIndices) Sets the row groups, where each row in such a group gets the same group
wide height. | public void | setRowSpec(int rowIndex, RowSpec rowSpec) Sets the RowSpec at the specified row index. |
FormLayout | public FormLayout()(Code) | | Constructs an empty FormLayout. Columns and rows must be added
before components can be added to the layout container.
This constructor is intended to be used in environments
that add columns and rows dynamically.
|
FormLayout | public FormLayout(String encodedColumnSpecs)(Code) | | Constructs a FormLayout using the given encoded column specifications.
The constructed layout has no rows; these must be added
before components can be added to the layout container.
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 |
FormLayout | public FormLayout(String encodedColumnSpecs, String encodedRowSpecs)(Code) | | 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"); // rows
See the class comment for more examples.
Parameters: encodedColumnSpecs - comma separated encoded column specifications Parameters: encodedRowSpecs - comma separated encoded row specifications throws: NullPointerException - if encodedColumnSpecs or encodedRowSpecs is null |
FormLayout | public FormLayout(ColumnSpec[] colSpecs)(Code) | | Constructs a FormLayout using the given column specifications.
The constructed layout has no rows; these must be added
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)(Code) | | Constructs a FormLayout using the given column and row specifications.
Parameters: colSpecs - an array of column specifications. Parameters: rowSpecs - an array of row specifications. throws: NullPointerException - if colSpecs or rowSpecs is null |
addGroupedColumn | public void addGroupedColumn(int columnIndex)(Code) | | 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 |
addGroupedRow | public void addGroupedRow(int rowIndex)(Code) | | 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 |
addLayoutComponent | public void addLayoutComponent(String name, Component component)(Code) | | Throws an UnsupportedOperationException . Does not add
the specified component with the specified name to the layout.
Parameters: name - indicates entry's position and anchor Parameters: component - component to add throws: UnsupportedOperationException - always |
addLayoutComponent | public void addLayoutComponent(Component comp, Object constraints)(Code) | | Adds the specified component to the layout, using the specified
constraints object. Note that constraints are mutable and
are, therefore, cloned when cached.
Parameters: comp - the component to be added Parameters: constraints - the component's cell constraints throws: NullPointerException - if constraints is null throws: IllegalArgumentException - if constraints is not aCellConstraints or a String that cannot be used to constructa CellConstraints |
appendColumn | public void appendColumn(ColumnSpec columnSpec)(Code) | | Appends the given column specification to the right hand side of all
columns.
Parameters: columnSpec - the column specification to be added throws: NullPointerException - if the column specification is null |
appendRow | public void appendRow(RowSpec rowSpec)(Code) | | 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 the rowSpec is null |
getColumnCount | public int getColumnCount()(Code) | | Returns the number of columns in this layout.
the number of columns |
getColumnGroups | public int[][] getColumnGroups()(Code) | | Returns a deep copy of the column groups.
the column groups as two-dimensional int array |
getColumnSpec | public ColumnSpec getColumnSpec(int columnIndex)(Code) | | Returns the ColumnSpec at the specified column index.
Parameters: columnIndex - the column index of the requested ColumnSpec the ColumnSpec at the specified column throws: IndexOutOfBoundsException - if the column index is out of range |
getConstraints | public CellConstraints getConstraints(Component component)(Code) | | Looks up and returns the constraints for the specified component.
A copy of the actual CellConstraints object is returned.
Parameters: component - the component to be queried the CellConstraints for the specified component throws: NullPointerException - if component is null or has not been added to the container |
getLayoutAlignmentX | public float getLayoutAlignmentX(Container parent)(Code) | | Returns the alignment along the x axis. This specifies how
the component would like to be aligned relative to other
components. The value should be a number between 0 and 1
where 0 represents alignment along the origin, 1 is aligned
the furthest away from the origin, 0.5 is centered, etc.
Parameters: parent - the parent container the value 0.5f to indicate center alignment |
getLayoutAlignmentY | public float getLayoutAlignmentY(Container parent)(Code) | | Returns the alignment along the y axis. This specifies how
the component would like to be aligned relative to other
components. The value should be a number between 0 and 1
where 0 represents alignment along the origin, 1 is aligned
the furthest away from the origin, 0.5 is centered, etc.
Parameters: parent - the parent container the value 0.5f to indicate center alignment |
getLayoutInfo | public LayoutInfo getLayoutInfo(Container parent)(Code) | | Computes and returns the horizontal and vertical grid origins.
Performs the same layout process as #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 an object that comprises the grid x and y origins |
getRowCount | public int getRowCount()(Code) | | Returns the number of rows in this layout.
the number of rows |
getRowGroups | public int[][] getRowGroups()(Code) | | Returns a deep copy of the row groups.
the row groups as two-dimensional int array |
getRowSpec | public RowSpec getRowSpec(int rowIndex)(Code) | | Returns the RowSpec at the specified row index.
Parameters: rowIndex - the row index of the requested RowSpec the RowSpec at the specified row throws: IndexOutOfBoundsException - if the row index is out of range |
insertColumn | public void insertColumn(int columnIndex, ColumnSpec columnSpec)(Code) | | Inserts the specified column at the specified position. Shifts components
that intersect the new column to the right hand side and readjusts
column groups.
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 |
insertRow | public void insertRow(int rowIndex, RowSpec rowSpec)(Code) | | Inserts the specified column at the specified position. Shifts
components that intersect the new column to the right and readjusts
column groups.
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 |
invalidateLayout | public void invalidateLayout(Container target)(Code) | | Invalidates the layout, indicating that if the layout manager
has cached information it should be discarded.
Parameters: target - the container that holds the layout to be invalidated |
layoutContainer | public void layoutContainer(Container parent)(Code) | | Lays out the specified container using this form layout. This method
reshapes components in the specified container in order to satisfy the
contraints of this FormLayout object.
Most applications do not call this method directly.
The form layout performs the following steps:
- find components that occupy exactly one column or row
- compute minimum widths and heights
- compute preferred widths and heights
- give cols and row equal size if they share a group
- compress default columns and rows if total is less than pref size
- give cols and row equal size if they share a group
- distribute free space
- set components bounds
Parameters: parent - the container in which to do the layout See Also: Container See Also: Container.doLayout |
minimumLayoutSize | public Dimension minimumLayoutSize(Container parent)(Code) | | Determines the minimum size of the parent container
using this form layout.
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 |
preferredLayoutSize | public Dimension preferredLayoutSize(Container parent)(Code) | | Determines the preferred size of the parent
container using this form layout.
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 |
removeColumn | public void removeColumn(int columnIndex)(Code) | | 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 part
of a column group.
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 componentsor if the column is already grouped See Also: com.jgoodies.forms.extras.FormLayoutUtils.columnContainsComponent(Containerint) See Also: com.jgoodies.forms.extras.FormLayoutUtils.isGroupedColumn(FormLayoutint) |
removeRow | public void removeRow(int rowIndex)(Code) | | Removes the row with the given row index from the layout. Components
will be rearranged and row groups will be readjusted. Therefore, the
row must not contain components and must not be part of a row group.
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 componentsor if the row is already grouped See Also: com.jgoodies.forms.extras.FormLayoutUtils.rowContainsComponent(Containerint) See Also: com.jgoodies.forms.extras.FormLayoutUtils.isGroupedRow(FormLayoutint) |
setColumnGroups | public void setColumnGroups(int[][] colGroupIndices)(Code) | | Sets the column groups, where each column in a group gets the same
group wide width. Each group is described by an array of integers that
are interpreted as column indices. The parameter is an array of such
group descriptions.
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 throws: IllegalArgumentException - if a column index is used twice |
setColumnSpec | public void setColumnSpec(int columnIndex, ColumnSpec columnSpec)(Code) | | Sets the ColumnSpec at the specified column index.
Parameters: columnIndex - the index of the column to be changed Parameters: columnSpec - the ColumnSpec to be set throws: NullPointerException - if the column specification is null throws: IndexOutOfBoundsException - if the column index is out of range |
setConstraints | public void setConstraints(Component component, CellConstraints constraints)(Code) | | Sets the constraints for the specified component in this layout.
Parameters: component - the component to be modified Parameters: constraints - the constraints to be applied throws: NullPointerException - if the component or constraints objectis null |
setRowGroups | public void setRowGroups(int[][] rowGroupIndices)(Code) | | Sets the row groups, where each row in such a group gets the same group
wide height. Each group is described by an array of integers that are
interpreted as row indices. The parameter is an array of such group
descriptions.
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 |
setRowSpec | public void setRowSpec(int rowIndex, RowSpec rowSpec)(Code) | | Sets the RowSpec at the specified row index.
Parameters: rowIndex - the index of the row to be changed Parameters: rowSpec - the RowSpec to be set throws: NullPointerException - if the row specification is null throws: IndexOutOfBoundsException - if the row index is out of range |
|
|