|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.jgoodies.forms.builder.AbstractFormBuilder
com.jgoodies.forms.builder.PanelBuilder
public class PanelBuilder
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 ButtonBarBuilder2
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( "pref, $lcgap, 50dlu, $rgap, default", // columns "pref, $lg, pref, $lg, 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();
ComponentFactory
,
I15dPanelBuilder
,
DefaultFormBuilder
Constructor Summary | |
---|---|
PanelBuilder(FormLayout layout)
Constructs a PanelBuilder for the given
layout. |
|
PanelBuilder(FormLayout layout,
javax.swing.JPanel panel)
Constructs a PanelBuilder for the given
FormLayout and layout container. |
Method Summary | |
---|---|
java.awt.Component |
add(java.awt.Component component,
CellConstraints cellConstraints)
Adds a component to the panel using the given cell constraints. |
javax.swing.JLabel |
add(javax.swing.JLabel label,
CellConstraints labelConstraints,
java.awt.Component component,
CellConstraints componentConstraints)
Adds a label and component to the panel using the given cell constraints. |
javax.swing.JLabel |
addLabel(java.lang.String textWithMnemonic)
Adds a textual label to the form using the default constraints. |
javax.swing.JLabel |
addLabel(java.lang.String textWithMnemonic,
CellConstraints constraints)
Adds a textual label to the form using the specified constraints. |
javax.swing.JLabel |
addLabel(java.lang.String textWithMnemonic,
CellConstraints labelConstraints,
java.awt.Component component,
CellConstraints componentConstraints)
Adds a label and component to the panel using the given cell constraints. |
javax.swing.JLabel |
addLabel(java.lang.String textWithMnemonic,
java.lang.String encodedConstraints)
Adds a textual label to the form using the specified constraints. |
javax.swing.JLabel |
addROLabel(java.lang.String textWithMnemonic)
Adds a textual label intended for labeling read-only components to the form using the default constraints. |
javax.swing.JLabel |
addROLabel(java.lang.String textWithMnemonic,
CellConstraints constraints)
Adds a textual label intended for labeling read-only components to the form using the specified constraints. |
javax.swing.JLabel |
addROLabel(java.lang.String textWithMnemonic,
CellConstraints labelConstraints,
java.awt.Component component,
CellConstraints componentConstraints)
Adds a label and component to the panel using the given cell constraints. |
javax.swing.JLabel |
addROLabel(java.lang.String textWithMnemonic,
java.lang.String encodedConstraints)
Adds a textual label intended for labeling read-only components to the form using the specified constraints. |
javax.swing.JComponent |
addSeparator(java.lang.String textWithMnemonic)
Adds a titled separator to the form that spans all columns. |
javax.swing.JComponent |
addSeparator(java.lang.String textWithMnemonic,
CellConstraints constraints)
Adds a titled separator to the form using the specified constraints. |
javax.swing.JComponent |
addSeparator(java.lang.String textWithMnemonic,
int columnSpan)
Adds a titled separator to the form that spans the specified columns. |
javax.swing.JComponent |
addSeparator(java.lang.String textWithMnemonic,
java.lang.String encodedConstraints)
Adds a titled separator to the form using the specified constraints. |
javax.swing.JLabel |
addTitle(java.lang.String textWithMnemonic)
Adds a title label to the form using the default constraints. |
javax.swing.JLabel |
addTitle(java.lang.String textWithMnemonic,
CellConstraints constraints)
Adds a title label to the form using the specified constraints. |
javax.swing.JLabel |
addTitle(java.lang.String textWithMnemonic,
java.lang.String encodedConstraints)
Adds a title label to the form using the specified constraints. |
ComponentFactory |
getComponentFactory()
Returns the builder's component factory. |
static boolean |
getLabelForFeatureEnabledDefault()
Returns the global default for the enablement of the setLabelFor feature. |
javax.swing.JPanel |
getPanel()
Returns the panel used to build the form. |
protected boolean |
isLabelForApplicable(javax.swing.JLabel label,
java.awt.Component component)
Checks and answers whether the given component shall be set as component for a previously added label using JLabel.setLabelFor(Component) . |
boolean |
isLabelForFeatureEnabled()
Returns whether the setLabelFor feature is enabled for this PanelBuilder. |
void |
setBackground(java.awt.Color background)
Sets the panel's background color. |
void |
setBorder(javax.swing.border.Border border)
Sets the panel's border. |
void |
setComponentFactory(ComponentFactory newFactory)
Sets a new component factory. |
void |
setDefaultDialogBorder()
Sets the default dialog border. |
protected void |
setLabelFor(javax.swing.JLabel label,
java.awt.Component component)
Sets label as labeling label for component or an
appropriate child. |
void |
setLabelForFeatureEnabled(boolean b)
Enables or disables the setLabelFor feature for this PanelBuilder. |
static void |
setLabelForFeatureEnabledDefault(boolean b)
Sets the default value for the setLabelFor feature enablement. |
void |
setOpaque(boolean b)
Sets the panel's opaque state. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public PanelBuilder(FormLayout layout)
PanelBuilder
for the given
layout. Uses an instance of JPanel
as layout container
with the given layout as layout manager.
layout
- the FormLayout to usepublic PanelBuilder(FormLayout layout, javax.swing.JPanel panel)
PanelBuilder
for the given
FormLayout and layout container.
layout
- the FormLayout to usepanel
- the layout container to build onMethod Detail |
---|
public static boolean getLabelForFeatureEnabledDefault()
setLabelForFeatureEnabled(boolean)
.
The feature is globally disabled by default.
public static void setLabelForFeatureEnabledDefault(boolean b)
setLabelForFeatureEnabled(boolean)
.
The default value is used to set the initial PanelBuilder
setting for this feature.
The feature is globally disabled by default.
b
- true for globally enabled, false for globally disabledpublic boolean isLabelForFeatureEnabled()
getLabelForFeatureEnabledDefault()
. It is globally disabled
by default.
public void setLabelForFeatureEnabled(boolean b)
getLabelForFeatureEnabledDefault()
. It is globally disabled
by default.
b
- true for enabled, false for disabledpublic final javax.swing.JPanel getPanel()
public final void setBackground(java.awt.Color background)
background
- the color to set as new backgroundJComponent.setBackground(Color)
public final void setBorder(javax.swing.border.Border border)
border
- the border to setJComponent.setBorder(Border)
public final void setDefaultDialogBorder()
Borders
public final void setOpaque(boolean b)
b
- true for opaque, false for non-opaqueJComponent.setOpaque(boolean)
public final javax.swing.JLabel addLabel(java.lang.String textWithMnemonic)
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
ComponentFactory
public final javax.swing.JLabel addLabel(java.lang.String textWithMnemonic, CellConstraints 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
ComponentFactory
public final javax.swing.JLabel addLabel(java.lang.String textWithMnemonic, java.lang.String encodedConstraints)
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
ComponentFactory
public final javax.swing.JLabel addLabel(java.lang.String textWithMnemonic, CellConstraints labelConstraints, java.awt.Component component, CellConstraints componentConstraints)
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
java.lang.IllegalArgumentException
- if the same cell constraints instance
is used for the label and the componentJLabel.setLabelFor(java.awt.Component)
,
ComponentFactory
,
DefaultFormBuilder
public final javax.swing.JLabel addROLabel(java.lang.String textWithMnemonic)
addROLabel("Name:"); // No Mnemonic addROLabel("N&ame:"); // Mnemonic is 'a' addROLabel("Save &as:"); // Mnemonic is the second 'a' addROLabel("Look&&Feel:"); // No mnemonic, text is "look&feel"
textWithMnemonic
- the label's text -
may contain an ampersand (&) to mark a mnemonic
ComponentFactory2
public final javax.swing.JLabel addROLabel(java.lang.String textWithMnemonic, CellConstraints constraints)
addROLabel("Name:", cc.xy(1, 1)); // No Mnemonic addROLabel("N&ame:", cc.xy(1, 1)); // Mnemonic is 'a' addROLabel("Save &as:", cc.xy(1, 1)); // Mnemonic is the second 'a' addROLabel("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
ComponentFactory2
public final javax.swing.JLabel addROLabel(java.lang.String textWithMnemonic, java.lang.String encodedConstraints)
addROLabel("Name:", "1, 1"); // No Mnemonic addROLabel("N&ame:", "1, 1"); // Mnemonic is 'a' addROLabel("Save &as:", "1, 1"); // Mnemonic is the second 'a' addROLabel("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
ComponentFactory2
public final javax.swing.JLabel addROLabel(java.lang.String textWithMnemonic, CellConstraints labelConstraints, java.awt.Component component, CellConstraints componentConstraints)
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.addROLabel( "&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.addROLabel( "&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.addROLabel( "&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
java.lang.IllegalArgumentException
- if the same cell constraints instance
is used for the label and the componentJLabel.setLabelFor(java.awt.Component)
,
ComponentFactory2
,
DefaultFormBuilder
public final javax.swing.JLabel addTitle(java.lang.String textWithMnemonic)
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
ComponentFactory
public final javax.swing.JLabel addTitle(java.lang.String textWithMnemonic, CellConstraints 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
ComponentFactory
public final javax.swing.JLabel addTitle(java.lang.String textWithMnemonic, java.lang.String encodedConstraints)
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
ComponentFactory
public final javax.swing.JComponent addSeparator(java.lang.String textWithMnemonic)
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
public final javax.swing.JComponent addSeparator(java.lang.String textWithMnemonic, CellConstraints 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
public final javax.swing.JComponent addSeparator(java.lang.String textWithMnemonic, java.lang.String encodedConstraints)
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
public final javax.swing.JComponent addSeparator(java.lang.String textWithMnemonic, int columnSpan)
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
public final javax.swing.JLabel add(javax.swing.JLabel label, CellConstraints labelConstraints, java.awt.Component component, CellConstraints componentConstraints)
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
java.lang.IllegalArgumentException
- if the same cell constraints instance
is used for the label and the componentJLabel.setLabelFor(java.awt.Component)
,
DefaultFormBuilder
public final ComponentFactory getComponentFactory()
DefaultComponentFactory
.
setComponentFactory(ComponentFactory)
public final void setComponentFactory(ComponentFactory newFactory)
newFactory
- the component factory to be setgetComponentFactory()
public java.awt.Component add(java.awt.Component component, CellConstraints cellConstraints)
add
in class AbstractFormBuilder
component
- the component to addcellConstraints
- the component's cell constraints
isLabelForFeatureEnabled()
,
isLabelForApplicable(JLabel, Component)
protected boolean isLabelForApplicable(javax.swing.JLabel label, java.awt.Component component)
JLabel.setLabelFor(Component)
.
This default implementation checks whether the component is focusable,
and - if a JComponent - whether it is already labeled by a JLabel.
Subclasses may override.
label
- the candidate for labeling component
component
- the component that could be labeled by label
protected void setLabelFor(javax.swing.JLabel label, java.awt.Component component)
label
as labeling label for component
or an
appropriate child. In case of a JScrollPane as given component,
this default implementation labels the view of the scroll pane's
viewport.
label
- the labeling labelcomponent
- the component to be labeled, or the parent of
the labeled component
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |