An general purpose panel builder that uses the
FormLayout
to lay out
JPanel
s. It provides convenience methods
to set a default border and to add labels, titles and titled separators.
The PanelBuilder is the working horse for layouts when more specialized
builders like the
ButtonBarBuilder
or
DefaultFormBuilder
are inappropriate.
The Forms tutorial includes several examples that present and compare
different style to build with the PanelBuilder: static row numbers
vs. row variable, explicit CellConstraints vs. builder cursor,
static rows vs. dynamically added rows. Also, you may check out the
Tips & Tricks section of the Forms HTML documentation.
The texts used in method
#addLabel
can contain an optional
mnemonic marker. The mnemonic and mnemonic index are indicated by
a single ampersand (
&). For example
"&Save", or
"Save &as". To use the ampersand itself,
duplicate it, for example
"Look&&Feel".
Example:
This example creates a panel with 3 columns and 3 rows.
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("&Title", cc.xy (1, 1));
builder.add(new JTextField(), cc.xywh(3, 1, 3, 1));
builder.addLabel("&Price", cc.xy (1, 3));
builder.add(new JTextField(), cc.xy (3, 3));
builder.addLabel("&Author", cc.xy (1, 5));
builder.add(new JTextField(), cc.xy (3, 5));
builder.add(new JButton("..."), cc.xy (5, 5));
return builder.getPanel();
add
public final JLabel add(JLabel label,
CellConstraints labelConstraints,
Component component,
CellConstraints componentConstraints)
Adds a label and component to the panel using the given cell constraints.
Sets the given label as
the component label using
JLabel.setLabelFor(java.awt.Component)
.
Note: The
CellConstraints
objects for the label
and the component must be different. Cell constraints are implicitly
cloned by the
FormLayout
when added to the container.
However, in this case you may be tempted to reuse a
CellConstraints
object in the same way as with many other
builder methods that require a single
CellConstraints
parameter.
The pitfall is that the methods
CellConstraints.xy*(...)
just set the coordinates but do
not create a new instance.
And so the second invocation of
xy*(...)
overrides
the settings performed in the first invocation before the object
is cloned by the
FormLayout
.
Wrong:
CellConstraints cc = new CellConstraints();
builder.add(
nameLabel,
cc.xy(1, 7), // will be modified by the code below
nameField,
cc.xy(3, 7) // sets the single instance to (3, 7)
);
Correct:
// Using a single CellConstraints instance and cloning
CellConstraints cc = new CellConstraints();
builder.add(
nameLabel,
(CellConstraints) cc.xy(1, 7).clone(), // cloned before the next modification
nameField,
cc.xy(3, 7) // sets this instance to (3, 7)
);
// Using two CellConstraints instances
CellConstraints cc1 = new CellConstraints();
CellConstraints cc2 = new CellConstraints();
builder.add(
nameLabel,
cc1.xy(1, 7), // sets instance 1 to (1, 7)
nameField,
cc2.xy(3, 7) // sets instance 2 to (3, 7)
);
label
- the label to addlabelConstraints
- the label's cell constraintscomponent
- the component to addcomponentConstraints
- the component's cell constraints
addLabel
public final JLabel addLabel(String textWithMnemonic)
Adds a textual label to the form using the default constraints.
addLabel("Name"); // No Mnemonic
addLabel("N&ame"); // Mnemonic is 'a'
addLabel("Look&&Feel"); // No mnemonic, text is "look&feel"
textWithMnemonic
- the label's text - may contain a mnemonic marker
addLabel
public final JLabel addLabel(String textWithMnemonic,
String encodedConstraints)
Adds a textual label to the form using the specified constraints.
addLabel("Name", "1, 1"); // No Mnemonic
addLabel("N&ame", "1, 1"); // Mnemonic is 'a'
addLabel("Look&&Feel", "1, 1"); // No mnemonic, text is "look&feel"
textWithMnemonic
- the label's text - may contain a mnemonic markerencodedConstraints
- a string representation for the constraints
addLabel
public final JLabel addLabel(String textWithMnemonic,
CellConstraints constraints)
Adds a textual label to the form using the specified constraints.
addLabel("Name", cc.xy(1, 1)); // No Mnemonic
addLabel("N&ame", cc.xy(1, 1)); // Mnemonic is 'a'
addLabel("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is "look&feel"
textWithMnemonic
- the label's text - may contain a mnemonic markerconstraints
- the label's cell constraints
addLabel
public final JLabel addLabel(String textWithMnemonic,
CellConstraints labelConstraints,
Component component,
CellConstraints componentConstraints)
Adds a label and component to the panel using the given cell constraints.
Sets the given label as
the component label using
JLabel.setLabelFor(java.awt.Component)
.
Note: The
CellConstraints
objects for the label
and the component must be different. Cell constraints are implicitly
cloned by the
FormLayout
when added to the container.
However, in this case you may be tempted to reuse a
CellConstraints
object in the same way as with many other
builder methods that require a single
CellConstraints
parameter.
The pitfall is that the methods
CellConstraints.xy*(...)
just set the coordinates but do
not create a new instance.
And so the second invocation of
xy*(...)
overrides
the settings performed in the first invocation before the object
is cloned by the
FormLayout
.
Wrong:
builder.addLabel(
"&Name:",
cc.xy(1, 7), // will be modified by the code below
nameField,
cc.xy(3, 7) // sets the single instance to (3, 7)
);
Correct:
// Using a single CellConstraints instance and cloning
CellConstraints cc = new CellConstraints();
builder.addLabel(
"&Name:",
(CellConstraints) cc.xy(1, 7).clone(), // cloned before the next modification
nameField,
cc.xy(3, 7) // sets this instance to (3, 7)
);
// Using two CellConstraints instances
CellConstraints cc1 = new CellConstraints();
CellConstraints cc2 = new CellConstraints();
builder.addLabel(
"&Name:",
cc1.xy(1, 7), // sets instance 1 to (1, 7)
nameField,
cc2.xy(3, 7) // sets instance 2 to (3, 7)
);
textWithMnemonic
- the label's text - may contain a mnemonic markerlabelConstraints
- the label's cell constraintscomponent
- the component to addcomponentConstraints
- the component's cell constraints
addSeparator
public final JComponent addSeparator(String text)
Adds a titled separator to the form that spans all columns.
text
- the separator titel
addSeparator
public final JComponent addSeparator(String text,
String encodedConstraints)
Adds a titled separator to the form using the specified constraints.
text
- the separator titelencodedConstraints
- a string representation for the constraints
addSeparator
public final JComponent addSeparator(String text,
CellConstraints constraints)
Adds a titled separator to the form using the specified constraints.
text
- the separator titleconstraints
- the separator's cell constraints
addSeparator
public final JComponent addSeparator(String text,
int columnSpan)
Adds a titled separator to the form that spans the specified columns.
text
- the separator titelcolumnSpan
- the number of columns the separator spans
addTitle
public final JLabel addTitle(String text)
Adds a title label to the form using the default constraints.
text
- the separator titel
addTitle
public final JLabel addTitle(String text,
String encodedConstraints)
Adds a title label to the form using the specified constraints.
text
- the label's textencodedConstraints
- a string representation for the constraints
addTitle
public final JLabel addTitle(String text,
CellConstraints constraints)
Adds a title label to the form using the specified constraints.
text
- the label's title textconstraints
- the separator's cell constraints
getComponentFactory
protected final ComponentFactory getComponentFactory()
Returns the builder's component factory. If no factory
has been set before, it is lazily initialized using with an instance of
DefaultComponentFactory
.
getPanel
public final JPanel getPanel()
Returns the panel used to build the form.
- the panel used by this builder to build the form
setBorder
public final void setBorder(Border border)
Sets the panel's border.
border
- the border to set
setComponentFactory
public final void setComponentFactory(ComponentFactory newFactory)
Sets a new component factory.
newFactory
- the component factory to be set
setDefaultDialogBorder
public final void setDefaultDialogBorder()
Sets the default dialog border.