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 text arguments passed to the methods
#addLabel
,
#addTitle
, and
#addSeparator
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("Save &as"); // Mnemonic is the second 'a'
addLabel("Look&&Feel"); // No mnemonic, text is "look&feel"
textWithMnemonic
- the label's text -
may contain an ampersand (&) to mark a mnemonic
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("Save &as", "1, 1"); // Mnemonic is the second 'a'
addLabel("Look&&Feel", "1, 1"); // No mnemonic, text is "look&feel"
textWithMnemonic
- the label's text -
may contain an ampersand (&) to mark a mnemonicencodedConstraints
- 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("Save &as", cc.xy(1, 1)); // Mnemonic is the second 'a'
addLabel("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is "look&feel"
textWithMnemonic
- the label's text -
may contain an ampersand (&) to mark a mnemonicconstraints
- 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:", // Mnemonic is 'N'
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:", // Mnemonic is 'N'
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 an ampersand (&) to mark a mnemoniclabelConstraints
- the label's cell constraintscomponent
- the component to addcomponentConstraints
- the component's cell constraints
addSeparator
public final JComponent addSeparator(String textWithMnemonic)
Adds a titled separator to the form that spans all columns.
addSeparator("Name"); // No Mnemonic
addSeparator("N&ame"); // Mnemonic is 'a'
addSeparator("Save &as"); // Mnemonic is the second 'a'
addSeparator("Look&&Feel"); // No mnemonic, text is "look&feel"
textWithMnemonic
- the separator label's text -
may contain an ampersand (&) to mark a mnemonic
addSeparator
public final JComponent addSeparator(String textWithMnemonic,
String encodedConstraints)
Adds a titled separator to the form using the specified constraints.
addSeparator("Name", "1, 1"); // No Mnemonic
addSeparator("N&ame", "1, 1"); // Mnemonic is 'a'
addSeparator("Save &as", "1, 1"); // Mnemonic is the second 'a'
addSeparator("Look&&Feel", "1, 1"); // No mnemonic, text is "look&feel"
textWithMnemonic
- the separator label's text -
may contain an ampersand (&) to mark a mnemonicencodedConstraints
- a string representation for the constraints
addSeparator
public final JComponent addSeparator(String textWithMnemonic,
CellConstraints constraints)
Adds a titled separator to the form using the specified constraints.
addSeparator("Name", cc.xy(1, 1)); // No Mnemonic
addSeparator("N&ame", cc.xy(1, 1)); // Mnemonic is 'a'
addSeparator("Save &as", cc.xy(1, 1)); // Mnemonic is the second 'a'
addSeparator("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is "look&feel"
textWithMnemonic
- the separator label's text -
may contain an ampersand (&) to mark a mnemonicconstraints
- the separator's cell constraints
addSeparator
public final JComponent addSeparator(String textWithMnemonic,
int columnSpan)
Adds a titled separator to the form that spans the specified columns.
addSeparator("Name", 3); // No Mnemonic
addSeparator("N&ame", 3); // Mnemonic is 'a'
addSeparator("Save &as", 3); // Mnemonic is the second 'a'
addSeparator("Look&&Feel", 3); // No mnemonic, text is "look&feel"
textWithMnemonic
- the separator label's text -
may contain an ampersand (&) to mark a mnemoniccolumnSpan
- the number of columns the separator spans
addTitle
public final JLabel addTitle(String textWithMnemonic)
Adds a title label to the form using the default constraints.
addTitle("Name"); // No mnemonic
addTitle("N&ame"); // Mnemonic is 'a'
addTitle("Save &as"); // Mnemonic is the second 'a'
addTitle("Look&&Feel"); // No mnemonic, text is Look&Feel
textWithMnemonic
- the title label's text -
may contain an ampersand (&) to mark a mnemonic
addTitle
public final JLabel addTitle(String textWithMnemonic,
String encodedConstraints)
Adds a title label to the form using the specified constraints.
addTitle("Name", "1, 1"); // No mnemonic
addTitle("N&ame", "1, 1"); // Mnemonic is 'a'
addTitle("Save &as", "1, 1"); // Mnemonic is the second 'a'
addTitle("Look&&Feel", "1, 1"); // No mnemonic, text is Look&Feel
textWithMnemonic
- the title label's text -
may contain an ampersand (&) to mark a mnemonicencodedConstraints
- a string representation for the constraints
addTitle
public final JLabel addTitle(String textWithMnemonic,
CellConstraints constraints)
Adds a title label to the form using the specified constraints.
addTitle("Name", cc.xy(1, 1)); // No mnemonic
addTitle("N&ame", cc.xy(1, 1)); // Mnemonic is 'a'
addTitle("Save &as", cc.xy(1, 1)); // Mnemonic is the second 'a'
addTitle("Look&&Feel", cc.xy(1, 1)); // No mnemonic, text is Look&Feel
textWithMnemonic
- the title label's text -
may contain an ampersand (&) to mark a mnemonicconstraints
- the separator's cell constraints
getComponentFactory
public 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.