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 `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(
            "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 $
  Author:
    Karsten Lentzsch
  See Also:
    `ComponentFactory`, `I15dPanelBuilder`, `DefaultFormBuilder`

- - ### Field Summary

    - ### 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, JPanel panel)` Constructs a `PanelBuilder` for the given FormLayout and layout container.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Component` | `add(Component component, CellConstraints cellConstraints)` Adds a component to the panel using the given cell constraints.
    `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.
    `JLabel` | `addLabel(String textWithMnemonic, CellConstraints constraints)` Adds a textual label to the form using the specified constraints.
    `JLabel` | `addLabel(String textWithMnemonic, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)` Adds a label and component to the panel using the given cell constraints.
    `JLabel` | `addLabel(String textWithMnemonic, String encodedConstraints)` Adds a textual label to the form using the specified constraints.
    `JLabel` | `addROLabel(String textWithMnemonic)` Adds a textual label intended for labeling read-only components to the form using the default constraints.
    `JLabel` | `addROLabel(String textWithMnemonic, CellConstraints constraints)` Adds a textual label intended for labeling read-only components to the form using the specified constraints.
    `JLabel` | `addROLabel(String textWithMnemonic, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)` Adds a label and component to the panel using the given cell constraints.
    `JLabel` | `addROLabel(String textWithMnemonic, String encodedConstraints)` Adds a textual label intended for labeling read-only components to the form using the specified constraints.
    `JComponent` | `addSeparator(String textWithMnemonic)` Adds a titled separator to the form that spans all columns.
    `JComponent` | `addSeparator(String textWithMnemonic, CellConstraints constraints)` Adds a titled separator to the form using the specified constraints.
    `JComponent` | `addSeparator(String textWithMnemonic, int columnSpan)` Adds a titled separator to the form that spans the specified columns.
    `JComponent` | `addSeparator(String textWithMnemonic, String encodedConstraints)` Adds a titled separator to the form using the specified constraints.
    `JLabel` | `addTitle(String textWithMnemonic)` Adds a title label to the form using the default constraints.
    `JLabel` | `addTitle(String textWithMnemonic, CellConstraints constraints)` Adds a title label to the form using the specified constraints.
    `JLabel` | `addTitle(String textWithMnemonic, String encodedConstraints)` Adds a title label to the form using the specified constraints.
    `PanelBuilder` | `background(Color background)` Sets the panel's background color and the panel to be opaque.
    `PanelBuilder` | `border(Border border)` Sets the panel's border.
    `PanelBuilder` | `border(String emptyBorderSpec)` Sets the panel's border as an EmptyBorder using the given specification for the top, left, bottom, right in DLU.
    `JPanel` | `build()` Returns the panel used to build the form.
    `PanelBuilder` | `focusTraversal(FocusTraversalPolicy policy)` Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider.
    `JPanel` | `getPanel()` Returns the panel used to build the form.
    `protected boolean` | `isLabelForApplicable(JLabel label, 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.
    `PanelBuilder` | `opaque(boolean b)` Sets the panel's opaque state.
    `void` | `setBorder(Border border)` Deprecated. Replaced by `border(Border)`
    `void` | `setDefaultDialogBorder()` Deprecated. Replaced by `#border(Borders.DIALOG)`
    `protected void` | `setLabelFor(JLabel label, Component component)` Sets `label` as labeling label for `component` or an appropriate child.
    `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`

- - ### 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:
        `NullPointerException` - if `layout` is `null`

    - #### PanelBuilder

          public PanelBuilder(FormLayout layout,
                      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:
        `NullPointerException` - if `layout` or `container` is `null`

  - ### Method Detail

    - #### getPanel

          public final 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(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(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(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(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(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 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 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"

      Parameters:
        `textWithMnemonic` - the label's text - may contain an ampersand (`&`) to mark a mnemonic
      Returns:
        the new label
      See Also:
        `ComponentFactory`

    - #### 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"

      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 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"

      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 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:

           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:
        `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 JLabel addROLabel(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 JLabel addROLabel(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 JLabel addROLabel(String textWithMnemonic,
                          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 JLabel addROLabel(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.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:
        `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 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

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

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

      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 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"

      Parameters:
        `textWithMnemonic` - the separator label's text - may contain an ampersand (`&`) to mark a mnemonic
      Returns:
        the added separator

    - #### 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"

      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 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"

      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 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"

      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 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:

           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:
        `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 Component add(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)`

    - #### isLabelForApplicable

          protected boolean isLabelForApplicable(JLabel label,
                                     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(JLabel label,
                         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

Copyright © 2002-2014 JGoodies Software GmbH. All Rights Reserved.