com.jgoodies.forms.builder

Class PanelBuilder

java.lang.Object

com.jgoodies.forms.builder.AbstractBuilder

com.jgoodies.forms.builder.AbstractFormBuilder

com.jgoodies.forms.builder.PanelBuilder

Direct Known Subclasses:

I15dPanelBuilder

public class PanelBuilder
extends AbstractFormBuilder

An general purpose panel builder that uses the FormLayout to lay out JPanels. 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(
      "pref, $lcgap, 50dlu, $rgap, default",  // columns
      "pref, $lg, pref, $lg, pref");          // rows

 PanelBuilder builder = new PanelBuilder(layout);
 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.21 $

See Also:

ComponentFactory, I15dPanelBuilder, DefaultFormBuilder

Field Summary

Fields

Modifier and Type	Field and Description
private static java.lang.String	LABELED_BY_PROPERTY A JComponent client property that is used to determine the label labeling a component.
private boolean	labelForFeatureEnabled The instance value for the setLabelFor feature.
private java.lang.ref.WeakReference	mostRecentlyAddedLabelReference Refers to the most recently added label.

Fields inherited from class com.jgoodies.forms.builder.AbstractBuilder

currentCellConstraints

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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.
PanelBuilder	background(java.awt.Color background) Sets the panel's background color and the panel to be opaque.
PanelBuilder	border(javax.swing.border.Border border) Sets the panel's border.
PanelBuilder	border(java.lang.String emptyBorderSpec) Sets the panel's border as an EmptyBorder using the given specification for the top, left, bottom, right in DLU.
javax.swing.JPanel	build() Returns the panel used to build the form.
private static void	checkConstraints(CellConstraints c1, CellConstraints c2)
private void	clearMostRecentlyAddedLabel() Clears the reference to the most recently added mnemonic label.
PanelBuilder	focusTraversal(java.awt.FocusTraversalPolicy policy) Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider.
private javax.swing.JLabel	getMostRecentlyAddedLabel() Returns the most recently added JLabel that has a mnemonic set - if any, null, if none has been set, or if it has been cleared after setting an association before, or if it has been cleared by the garbage collector.
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).
PanelBuilder	labelForFeatureEnabled(boolean b) Enables or disables the setLabelFor feature for this PanelBuilder.
private void	manageLabelsAndComponents(java.awt.Component c)
PanelBuilder	opaque(boolean b) Sets the panel's opaque state.
void	setBorder(javax.swing.border.Border border) Deprecated. Replaced by border(Border)
void	setDefaultDialogBorder() Deprecated. Replaced by #border(Borders.DIALOG)
protected void	setLabelFor(javax.swing.JLabel label, java.awt.Component component) Sets label as labeling label for component or an appropriate child.
private void	setMostRecentlyAddedLabel(javax.swing.JLabel label) Sets the given label as most recently added label using a weak reference.
void	setOpaque(boolean b) Deprecated. Replaced by opaque(boolean)

Methods inherited from class com.jgoodies.forms.builder.AbstractFormBuilder

add, add, appendColumn, appendColumn, appendGlueColumn, appendGlueRow, appendLabelComponentsGapColumn, appendParagraphGapRow, appendRelatedComponentsGapColumn, appendRelatedComponentsGapRow, appendRow, appendRow, appendUnrelatedComponentsGapColumn, appendUnrelatedComponentsGapRow, cellConstraints, createLeftAdjustedConstraints, getColumn, getColumnIncrementSign, getLeadingColumn, getRow, isLeftToRight, nextColumn, nextColumn, nextLine, nextLine, nextRow, nextRow, setAlignment, setBounds, setColumn, setColumnSpan, setExtent, setHAlignment, setLeftToRight, setOrigin, setRow, setRowSpan, setVAlignment

Methods inherited from class com.jgoodies.forms.builder.AbstractBuilder

createComponentFactory, getColumnCount, getComponentFactory, getContainer, getLayout, getRowCount, setComponentFactory

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LABELED_BY_PROPERTY

private static final java.lang.String LABELED_BY_PROPERTY

A JComponent client property that is used to determine the label labeling a component. Copied from the JLabel class.

See Also:

Constant Field Values

labelForFeatureEnabled

private boolean labelForFeatureEnabled

The instance value for the setLabelFor feature. Is initialized using the global default.

See Also:

#setLabelForFeatureEnabledDefault(boolean), #setLabelForFeatureEnabledDefault(boolean)

mostRecentlyAddedLabelReference

private java.lang.ref.WeakReference mostRecentlyAddedLabelReference

Refers to the most recently added label. Used to invoke JLabel.setLabelFor(java.awt.Component) for the next component added to the panel that is applicable for this feature (for example focusable). After the association has been set, the reference will be cleared.

See Also:

add(Component, CellConstraints)

Constructor Detail

PanelBuilder

public PanelBuilder(FormLayout layout)

Constructs a 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

Throws:

java.lang.NullPointerException - if layout is null

PanelBuilder

public PanelBuilder(FormLayout layout,
                    javax.swing.JPanel panel)

Constructs a PanelBuilder for the given FormLayout and layout container.

Parameters:

layout - the FormLayout to use

panel - the layout container to build on

Throws:

java.lang.NullPointerException - if layout or container is null

Method Detail

getPanel

public final javax.swing.JPanel getPanel()

Returns the panel used to build the form. Intended to access panel properties. For returning the built panel, you should use build().

Returns:

the panel used by this builder to build the form

background

public PanelBuilder background(java.awt.Color background)

Sets the panel's background color and the panel to be opaque.

Parameters:

background - the color to set as new background

Since:

1.6

See Also:

JComponent.setBackground(Color)

border

public PanelBuilder border(javax.swing.border.Border border)

Sets the panel's border.

Parameters:

border - the border to set

Since:

1.6

See Also:

JComponent.setBorder(Border)

border

public PanelBuilder border(java.lang.String emptyBorderSpec)

Sets the panel's border as an EmptyBorder using the given specification for the top, left, bottom, right in DLU. For example "1dlu, 2dlu, 3dlu, 4dlu" sets an empty border with 1dlu in the top, 2dlu in the left side, 3dlu at the bottom, and 4dlu in the right hand side.

Equivalent to setBorder(Borders.createEmptyBorder(emptyBorderSpec)).

Parameters:

emptyBorderSpec - describes the top, left, bottom, right sizes of the EmptyBorder to create

Since:

1.6

See Also:

Borders.createEmptyBorder(String)

opaque

public PanelBuilder opaque(boolean b)

Sets the panel's opaque state.

Parameters:

b - true for opaque, false for non-opaque

Since:

1.6

See Also:

JComponent.setOpaque(boolean)

focusTraversal

public PanelBuilder focusTraversal(java.awt.FocusTraversalPolicy policy)

Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider. Hence, this call is equivalent to:

 builder.getPanel().setFocusTraversalPolicy(policy);
 builder.getPanel().setFocusTraversalPolicyProvider(true);
 

Parameters:

policy - the focus traversal policy that will manage keyboard traversal of the children in this builder's panel

Since:

1.7

See Also:

Container.setFocusTraversalPolicy(FocusTraversalPolicy), Container.setFocusTraversalPolicyProvider(boolean)

labelForFeatureEnabled

public PanelBuilder labelForFeatureEnabled(boolean b)

Enables or disables the setLabelFor feature for this PanelBuilder. The value is initialized from the global default value FormsSetup.getLabelForFeatureEnabledDefault(). It is globally disabled by default.

Parameters:

b - true for enabled, false for disabled

setBorder

@Deprecated
public void setBorder(javax.swing.border.Border border)

Deprecated. Replaced by border(Border)

Sets the panel's border.

Parameters:

border - the border to set

See Also:

JComponent.setBorder(Border)

setDefaultDialogBorder

@Deprecated
public void setDefaultDialogBorder()

Deprecated. Replaced by #border(Borders.DIALOG)

Sets the default dialog border.

See Also:

Borders

setOpaque

@Deprecated
public void setOpaque(boolean b)

Deprecated. Replaced by opaque(boolean)

Sets the panel's opaque state.

Parameters:

b - true for opaque, false for non-opaque

Since:

1.1

See Also:

JComponent.setOpaque(boolean)

build

public final javax.swing.JPanel build()

Returns the panel used to build the form. Intended to return the panel in build methods.

Returns:

the panel used by this builder to build the form

Since:

1.6

addLabel

public final javax.swing.JLabel addLabel(java.lang.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"
 

Parameters:

textWithMnemonic - the label's text - may contain an ampersand (&) to mark a mnemonic

Returns:

the new label

See Also:

ComponentFactory

addLabel

public final javax.swing.JLabel addLabel(java.lang.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"
 

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

public final javax.swing.JLabel addLabel(java.lang.String textWithMnemonic,
                                         java.lang.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"
 

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

addLabel

public final 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. 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:

 builder.addLabel(
     "&Name:",
     CC.xy(1, 7),         // creates an instance
     nameField,
     CC.xy(3, 7)          // creates another instance
 );
 

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:

java.lang.IllegalArgumentException - if the same cell constraints instance is used for the label and the component

See Also:

JLabel.setLabelFor(java.awt.Component), ComponentFactory, DefaultFormBuilder

addROLabel

public final 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.

 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"
 

Parameters:

textWithMnemonic - the label's text - may contain an ampersand (&) to mark a mnemonic

Returns:

the new label

Since:

1.3

addROLabel

public final 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.

 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"
 

Parameters:

textWithMnemonic - the label's text - may contain an ampersand (&) to mark a mnemonic

constraints - the label's cell constraints

Returns:

the new label

Since:

1.3

addROLabel

public final 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.

 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"
 

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

Since:

1.3

addROLabel

public final 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. 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.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:

 builder.addROLabel(
     "&Name:",
     CC.xy(1, 7),          // creates an instance
     nameField,
     CC.xy(3, 7)           // creates another instance
 );
 

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:

java.lang.IllegalArgumentException - if the same cell constraints instance is used for the label and the component

Since:

1.3

See Also:

JLabel.setLabelFor(java.awt.Component), DefaultFormBuilder

addTitle

public final javax.swing.JLabel addTitle(java.lang.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
 

Parameters:

textWithMnemonic - the title label's text - may contain an ampersand (&) to mark a mnemonic

Returns:

the added title label

See Also:

ComponentFactory

addTitle

public final javax.swing.JLabel addTitle(java.lang.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
 

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

public final javax.swing.JLabel addTitle(java.lang.String textWithMnemonic,
                                         java.lang.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
 

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

addSeparator

public final javax.swing.JComponent addSeparator(java.lang.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"
 

Parameters:

textWithMnemonic - the separator label's text - may contain an ampersand (&) to mark a mnemonic

Returns:

the added separator

addSeparator

public final javax.swing.JComponent addSeparator(java.lang.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"
 

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

public final javax.swing.JComponent addSeparator(java.lang.String textWithMnemonic,
                                                 java.lang.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"
 

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

public final javax.swing.JComponent addSeparator(java.lang.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"
 

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

add

public final 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. 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:

 builder.add(
     nameLabel,
     CC.xy(1, 7),         // creates an instance
     nameField,
     CC.xy(3, 7)          // creates another instance
 );
 

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:

java.lang.IllegalArgumentException - if the same cell constraints instance is used for the label and the component

See Also:

JLabel.setLabelFor(java.awt.Component), DefaultFormBuilder

add

public java.awt.Component add(java.awt.Component component,
                              CellConstraints cellConstraints)

Adds a component to the panel using the given cell constraints. In addition to the superclass behavior, this implementation tracks the most recently added label, and associates it with the next added component that is applicable for being set as component for the label.

Overrides:

add in class AbstractFormBuilder

Parameters:

component - the component to add

cellConstraints - the component's cell constraints

Returns:

the added component

See Also:

isLabelForApplicable(JLabel, Component)

manageLabelsAndComponents

private void manageLabelsAndComponents(java.awt.Component c)

isLabelForApplicable

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). This default implementation checks whether the component is focusable, and - if a JComponent - whether it is already labeled by a JLabel. Subclasses may override.

Parameters:

label - the candidate for labeling component

component - the component that could be labeled by label

Returns:

true if focusable, false otherwise

setLabelFor

protected void setLabelFor(javax.swing.JLabel label,
                           java.awt.Component component)

Sets 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.

Parameters:

label - the labeling label

component - the component to be labeled, or the parent of the labeled component

getMostRecentlyAddedLabel

private javax.swing.JLabel getMostRecentlyAddedLabel()

Returns the most recently added JLabel that has a mnemonic set - if any, null, if none has been set, or if it has been cleared after setting an association before, or if it has been cleared by the garbage collector.

Returns:

the most recently added JLabel that has a mnemonic set and has not been associated with a component applicable for this feature. null otherwise.

setMostRecentlyAddedLabel

private void setMostRecentlyAddedLabel(javax.swing.JLabel label)

Sets the given label as most recently added label using a weak reference.

Parameters:

label - the label to be set

clearMostRecentlyAddedLabel

private void clearMostRecentlyAddedLabel()

Clears the reference to the most recently added mnemonic label.

checkConstraints

private static void checkConstraints(CellConstraints c1,
                                     CellConstraints c2)