com.jgoodies.forms.builder
public class PanelBuilder extends AbstractFormBuilder
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 {@link ButtonBarBuilder} or {@link 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();
Version: $Revision: 1.7 $
See Also: ComponentFactory I15dPanelBuilder DefaultFormBuilder
Constructor Summary | |
---|---|
PanelBuilder(FormLayout layout)
Constructs a PanelBuilder for the given
layout. | |
PanelBuilder(FormLayout layout, JPanel panel)
Constructs a PanelBuilder for the given
FormLayout and layout container.
|
Method Summary | |
---|---|
JLabel | add(JLabel label, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)
Adds a label and component to the panel using the given cell constraints.
|
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" |
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" |
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" |
JLabel | addLabel(String textWithMnemonic, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)
Adds a label and component to the panel using the given cell constraints.
|
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" |
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" |
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" |
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" |
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 |
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 |
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 |
ComponentFactory | getComponentFactory()
Returns the builder's component factory. |
JPanel | getPanel()
Returns the panel used to build the form.
|
void | setBackground(Color background)
Sets the panel's background color.
|
void | setBorder(Border border)
Sets the panel's border.
|
void | setComponentFactory(ComponentFactory newFactory)
Sets a new component factory.
|
void | setDefaultDialogBorder()
Sets the default dialog border.
|
void | setOpaque(boolean b)
Sets the panel's opaque state.
|
PanelBuilder
for the given
layout. Uses an instance of JPanel
as layout container
with the given layout as layout manager.
Parameters: layout the FormLayout to use
PanelBuilder
for the given
FormLayout and layout container.
Parameters: layout the FormLayout to use panel the layout container to build on
Note: The {@link 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) );
Parameters: label the label to add labelConstraints the label's cell constraints component the component to add componentConstraints the component's cell constraints
Returns: the added label
Throws: IllegalArgumentException if the same cell constraints instance is used for the label and the component
See Also: JLabel#setLabelFor(java.awt.Component) DefaultFormBuilder
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"
Parameters: textWithMnemonic the label's text - may contain an ampersand (&) to mark a mnemonic
Returns: the new label
See Also: ComponentFactory
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"
Parameters: textWithMnemonic the label's text - may contain an ampersand (&) to mark a mnemonic constraints the label's cell constraints
Returns: the new label
See Also: ComponentFactory
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"
Parameters: textWithMnemonic the label's text - may contain an ampersand (&) to mark a mnemonic encodedConstraints a string representation for the constraints
Returns: the new label
See Also: ComponentFactory
Note: The {@link 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) );
Parameters: textWithMnemonic the label's text - may contain an ampersand (&) to mark a mnemonic labelConstraints the label's cell constraints component the component to add componentConstraints the component's cell constraints
Returns: the added label
Throws: IllegalArgumentException if the same cell constraints instance is used for the label and the component
See Also: JLabel#setLabelFor(java.awt.Component) ComponentFactory DefaultFormBuilder
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"
Parameters: textWithMnemonic the separator label's text - may contain an ampersand (&) to mark a mnemonic
Returns: the added separator
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"
Parameters: textWithMnemonic the separator label's text - may contain an ampersand (&) to mark a mnemonic constraints the separator's cell constraints
Returns: the added separator
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"
Parameters: textWithMnemonic the separator label's text - may contain an ampersand (&) to mark a mnemonic encodedConstraints a string representation for the constraints
Returns: the added separator
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"
Parameters: textWithMnemonic the separator label's text - may contain an ampersand (&) to mark a mnemonic columnSpan the number of columns the separator spans
Returns: the added separator
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
Parameters: textWithMnemonic the title label's text - may contain an ampersand (&) to mark a mnemonic
Returns: the added title label
See Also: ComponentFactory
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
Parameters: textWithMnemonic the title label's text - may contain an ampersand (&) to mark a mnemonic constraints the separator's cell constraints
Returns: the added title label
See Also: ComponentFactory
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
Parameters: textWithMnemonic the title label's text - may contain an ampersand (&) to mark a mnemonic encodedConstraints a string representation for the constraints
Returns: the added title label
See Also: ComponentFactory
Returns: the component factory
See Also: setComponentFactory
Returns: the panel used by this builder to build the form
Parameters: background the color to set as new background
Since: 1.1
See Also: JComponent#setBackground(Color)
Parameters: border the border to set
See Also: JComponent#setBorder(Border)
Parameters: newFactory the component factory to be set
See Also: getComponentFactory
See Also: Borders
Parameters: b true for opaque, false for non-opaque
Since: 1.1
See Also: JComponent#setOpaque(boolean)