|
||||||||||
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. 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
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.extras.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();
ColumnSpec
,
RowSpec
,
CellConstraints
,
AbstractFormBuilder
,
ButtonBarBuilder
,
FormFactory
,
Size
,
Sizes
Nested Class Summary | |
---|---|
static class |
FormLayout.LayoutInfo
|
Constructor Summary | |
---|---|
FormLayout(ColumnSpec[] colSpecs,
RowSpec[] rowSpecs)
Constructs an instance of FormLayout using the given
column and row specifications. |
|
FormLayout(java.lang.String encodedColumnSpecs)
Constructs an instance of FormLayout using the given
encoded string representation for column specifications. |
|
FormLayout(java.lang.String encodedColumnSpecs,
java.lang.String encodedRowSpecs)
Constructs an instance of FormLayout using the given
encoded string representations for 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(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. |
static ColumnSpec[] |
decodeColSpecs(java.lang.String encodedColSpec)
Parses and splits encoded column specifications and returns an array of ColumnSpec objects. |
static RowSpec[] |
decodeRowSpecs(java.lang.String encodedRowSpec)
Parses and splits encoded row specifications and returns an array of RowSpec objects. |
int |
getColumnCount()
Returns the number of columns in this form layout. |
int[][] |
getColumnGroups()
Answers a deep copy of the column groups. |
ColumnSpec |
getColumnSpec(int columnIndex)
Returns the ColumnSpec at the specified column. |
CellConstraints |
getConstraints(java.awt.Component component)
Gets the constraints for the specified component. |
java.util.Map |
getConstraintsMap()
|
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 answers the horizontal and vertical grid origins. |
int |
getRowCount()
Returns the number of rows in this form layout. |
int[][] |
getRowGroups()
Answers a deep copy of the row groups. |
RowSpec |
getRowSpec(int rowIndex)
Returns the RowSpec at the specified row. |
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 |
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. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public FormLayout(ColumnSpec[] colSpecs, RowSpec[] rowSpecs)
FormLayout
using the given
column and row specifications.
colSpecs
- an array of column specifications.rowSpecs
- an array of row specifications.
java.lang.NullPointerException
- if colSpecs or rowSpecs is nullpublic FormLayout(java.lang.String encodedColumnSpecs, java.lang.String encodedRowSpecs)
FormLayout
using the given
encoded string representations for column and row specifications.
See the class comment for examples.
encodedColumnSpecs
- comma separated encoded column specificationsencodedRowSpecs
- comma separated encoded row specifications
java.lang.NullPointerException
- if encodedColumnSpecs or encodedRowSpecs is nullpublic FormLayout(java.lang.String encodedColumnSpecs)
FormLayout
using the given
encoded string representation for column specifications. The constructed
layout has no rows; these must be added before any component 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
.
See the class comment for examples.
encodedColumnSpecs
- comma separated encoded column specifications
java.lang.NullPointerException
- if encodedColumnSpecs is nullMethod Detail |
---|
public java.util.Map getConstraintsMap()
public int getColumnCount()
public int getRowCount()
public ColumnSpec getColumnSpec(int columnIndex)
ColumnSpec
at the specified column.
columnIndex
- the column index of the requested ColumnSpec
ColumnSpec
at the specified column
java.lang.IndexOutOfBoundsException
- if the column index is out of rangepublic RowSpec getRowSpec(int rowIndex)
RowSpec
at the specified row.
rowIndex
- the row index of the requested RowSpec
RowSpec
at the specified row
java.lang.IndexOutOfBoundsException
- if the row index is out of rangepublic void appendColumn(ColumnSpec columnSpec)
columnSpec
- the column specification to be added
java.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 inserted
java.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.
columnIndex
- index of the column to remove
java.lang.IndexOutOfBoundsException
- if the column index is out of range
java.lang.IllegalStateException
- if the column contains components
java.lang.IllegalStateException
- if the column is groupedpublic void appendRow(RowSpec rowSpec)
rowSpec
- the row specification to be added to the form layout
java.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 inserted
java.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.
rowIndex
- index of the row to remove
java.lang.IndexOutOfBoundsException
- if the row index is out of range
java.lang.IllegalStateException
- if the row contains components
java.lang.IllegalStateException
- if the row is groupedpublic void setConstraints(java.awt.Component component, CellConstraints constraints)
component
- the component to be modifiedconstraints
- the constraints to be applied
java.lang.NullPointerException
- if the component is null
java.lang.NullPointerException
- if the constraints are nullpublic CellConstraints getConstraints(java.awt.Component component)
CellConstraints
object is returned.
component
- the component to be queried
CellConstraints
for the specified component
java.lang.NullPointerException
- if component is null or has not been added to the Containerpublic int[][] getColumnGroups()
public void setColumnGroups(int[][] colGroupIndices)
Example: we build two groups, the first of columns 1, 3, and 4; and a second group for columns 7 and 9.
setColumnGroups(new int[][] { { 1, 3, 4 }, { 7, 9 } });
colGroupIndices
- a two-dimensional array of column groups indices
java.lang.IndexOutOfBoundsException
- if an index is outside the grid
java.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)
Example: we build two groups, the first of rows 1, and 2,; and a second group for 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.LayoutManager
name
- indicates entry's position and anchorcomponent
- component to add
java.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.LayoutManager2
comp
- the component to be addedconstraints
- the component's form layout constraints
java.lang.NullPointerException
- if constraints
is null
java.lang.IllegalArgumentException
- if constraints
is not a
CellConstraints
or a String that can be used
to construct a CellConstraints
public void removeLayoutComponent(java.awt.Component comp)
Most applications do not call this method directly.
removeLayoutComponent
in interface java.awt.LayoutManager
comp
- 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.LayoutManager
parent
- the container in which to do the layout
parent
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.LayoutManager
parent
- the container in which to do the layout
parent
containerContainer.getPreferredSize()
public java.awt.Dimension maximumLayoutSize(java.awt.Container target)
maximumLayoutSize
in interface java.awt.LayoutManager2
target
- the container which needs to be laid out
Container
,
minimumLayoutSize(Container)
,
preferredLayoutSize(Container)
public float getLayoutAlignmentX(java.awt.Container parent)
getLayoutAlignmentX
in interface java.awt.LayoutManager2
0.5f
to indicate center alignmentpublic float getLayoutAlignmentY(java.awt.Container parent)
getLayoutAlignmentY
in interface java.awt.LayoutManager2
0.5f
to indicate center alignmentpublic void invalidateLayout(java.awt.Container target)
invalidateLayout
in interface java.awt.LayoutManager2
public 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.LayoutManager
parent
- the container in which to do the layoutContainer
,
Container.doLayout()
public FormLayout.LayoutInfo getLayoutInfo(java.awt.Container parent)
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
public static ColumnSpec[] decodeColSpecs(java.lang.String encodedColSpec)
ColumnSpec
objects.
encodedColSpec
- the encoded column specification
java.lang.NullPointerException
- if the string description is nullpublic static RowSpec[] decodeRowSpecs(java.lang.String encodedRowSpec)
RowSpec
objects.
encodedRowSpec
- the encoded row specification
java.lang.NullPointerException
- if the string description is null
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |