PanelBuilder (JGoodies Forms 1.6 API)
Date: 2012-07-24

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
`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
`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.
`static boolean` | `getLabelForFeatureEnabledDefault()` Returns the global default for the enablement of the setLabelFor feature.
`static boolean` | `getOpaqueDefault()`
`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.
`static void` | `setLabelForFeatureEnabledDefault(boolean b)` Sets the default value for the setLabelFor feature enablement.
`void` | `setOpaque(boolean b)` Deprecated. Replaced by `opaque(boolean)`
`static void` | `setOpaqueDefault(boolean b)` Sets the global default value for a builder's opaque state that can be overridden per builder.

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, getComponentFactoryDefault, getContainer, getLayout, getRowCount, setComponentFactory, setComponentFactoryDefault`

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

### getLabelForFeatureEnabledDefault

    public static boolean getLabelForFeatureEnabledDefault()

  Returns the global default for the enablement of the setLabelFor feature. This can be overridden per PanelBuilder using `labelForFeatureEnabled(boolean)`. The feature is globally disabled by default.

  Returns:
    true for globally enabled, false for globally disabled

### setLabelForFeatureEnabledDefault

    public static void setLabelForFeatureEnabledDefault(boolean b)

  Sets the default value for the setLabelFor feature enablement. This can be overridden per PanelBuilder using `labelForFeatureEnabled(boolean)`. The default value is used to set the initial PanelBuilder setting for this feature. The feature is globally disabled by default.

  Parameters:
    `b` - true for globally enabled, false for globally disabled

### getOpaqueDefault

    public static boolean getOpaqueDefault()

  Returns:
    the global default value for a builder's opaque state that can be overridden per builder

### setOpaqueDefault

    public static void setOpaqueDefault(boolean b)

  Sets the global default value for a builder's opaque state that can be overridden per builder. Since the Forms 1.6, the default value is `false`, in other words, panels will not be opaque.

  Parameters:
    `b` - the new value

### getPanel

    public final JPanel getPanel()

  Returns the panel used to build the form.

  Returns:
    the panel used by this builder to build the form

### 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)`

### 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.1
  See Also:
    `JComponent.setBackground(Color)`

### border

    public PanelBuilder border(Border border)

  Sets the panel's border.

  Parameters:
    `border` - the border to set
  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
  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.1
  See Also:
    `JComponent.setOpaque(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 `getLabelForFeatureEnabledDefault()`. It is globally disabled by default.

  Parameters:
    `b` - true for enabled, false for disabled

### build

    public final JPanel build()

  Returns the panel used to build the form.

  Returns:
    the panel used by this builder to build the form

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2012 JGoodies Karsten Lentzsch. All Rights Reserved.