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.AbstractFormBuilder
          com.jgoodies.forms.builder.PanelBuilder

Direct Known Subclasses:
  AbstractI15dPanelBuilder, ButtonBarBuilder, ButtonStackBuilder

    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(
          "right:pref, 6dlu, 50dlu, 4dlu, default",  // columns
          "pref, 3dlu, pref, 3dlu, pref");           // rows

     PanelBuilder builder = new PanelBuilder(layout);
     CellConstraints cc = new CellConstraints();
     builder.addLabel("&Title",      cc.xy  (1, 1));
     builder.add(new JTextField(),   cc.xywh(3, 1, 3, 1));
     builder.addLabel("&Price",      cc.xy  (1, 3));
     builder.add(new JTextField(),   cc.xy  (3, 3));
     builder.addLabel("&Author",     cc.xy  (1, 5));
     builder.add(new JTextField(),   cc.xy  (3, 5));
     builder.add(new JButton("..."), cc.xy  (5, 5));
     return builder.getPanel();

Version:
  $Revision: 1.5 $
Author:
  Karsten Lentzsch
See Also:
  `ComponentFactory`, `I15dPanelBuilder`, `DefaultFormBuilder`

Constructor Summary
`PanelBuilder(FormLayout layout)` Constructs a `PanelBuilder` for the given layout.
`PanelBuilder(FormLayout layout, JPanel panel)` Constructs a `PanelBuilder` for the given FormLayout and layout container.

Method Summary
`JLabel` | `add(JLabel label, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)` Adds a label and component to the panel using the given cell constraints.
`JLabel` | `addLabel(String textWithMnemonic)` Adds a textual label to the form using the default constraints.
`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.
`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.
`ComponentFactory` | `getComponentFactory()` Returns the builder's component factory.
`JPanel` | `getPanel()` Returns the panel used to build the form.
`void` | `setBackground(Color background)` Sets the panel's background color.
`void` | `setBorder(Border border)` Sets the panel's border.
`void` | `setComponentFactory(ComponentFactory newFactory)` Sets a new component factory.
`void` | `setDefaultDialogBorder()` Sets the default dialog border.
`void` | `setOpaque(boolean b)` Sets the panel's opaque state.

Methods inherited from class com.jgoodies.forms.builder.AbstractFormBuilder
`add, add, add, appendColumn, appendColumn, appendGlueColumn, appendGlueRow, appendLabelComponentsGapColumn, appendParagraphGapRow, appendRelatedComponentsGapColumn, appendRelatedComponentsGapRow, appendRow, appendRow, appendUnrelatedComponentsGapColumn, appendUnrelatedComponentsGapRow, cellConstraints, createLeftAdjustedConstraints, getColumn, getColumnCount, getColumnIncrementSign, getContainer, getLayout, getLeadingColumn, getRow, getRowCount, isLeftToRight, nextColumn, nextColumn, nextLine, nextLine, nextRow, nextRow, setAlignment, setBounds, setColumn, setColumnSpan, setExtent, setHAlignment, setLeftToRight, setOrigin, setRow, setRowSpan, setVAlignment`

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

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

Method Detail

### getPanel

    public final JPanel getPanel()

  Returns the panel used to build the form.

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

### setBackground

    public final void setBackground(Color background)

  Sets the panel's background color.

  Parameters:
    `background` - the color to set as new background
  Since:
    1.1
  See Also:
    `JComponent.setBackground(Color)`

### setBorder

    public final void setBorder(Border border)

  Sets the panel's border.

  Parameters:
    `border` - the border to set
  See Also:
    `JComponent.setBorder(Border)`

### setDefaultDialogBorder

    public final void setDefaultDialogBorder()

  Sets the default dialog border.

  See Also:
    `Borders`

### setOpaque

    public final void setOpaque(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)`

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

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

       // Using a single CellConstraints instance and cloning
       CellConstraints cc = new CellConstraints();
       builder.add(
           nameLabel,
           (CellConstraints) cc.xy(1, 7).clone(), // cloned before the next modification
           nameField,
           cc.xy(3, 7)                            // sets this instance to (3, 7)
       );

       // Using two CellConstraints instances
       CellConstraints cc1 = new CellConstraints();
       CellConstraints cc2 = new CellConstraints();
       builder.add(
           nameLabel,
           cc1.xy(1, 7),       // sets instance 1 to (1, 7)
           nameField,
           cc2.xy(3, 7)        // sets instance 2 to (3, 7)
       );

  Parameters:
    `label` - the label to add
    `labelConstraints` - the label's cell constraints
    `component` - the component to add
    `componentConstraints` - the component's cell constraints
  Returns:
    the added label
  Throws:
    `IllegalArgumentException` - if the same cell constraints instance is used for the label and the component
  See Also:
    `JLabel.setLabelFor(java.awt.Component)`, `DefaultFormBuilder`

### addLabel

    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:

       // Using a single CellConstraints instance and cloning
       CellConstraints cc = new CellConstraints();
       builder.addLabel(
           "&Name:",
           (CellConstraints) cc.xy(1, 7).clone(), // cloned before the next modification
           nameField,
           cc.xy(3, 7)                            // sets this instance to (3, 7)
       );

       // Using two CellConstraints instances
       CellConstraints cc1 = new CellConstraints();
       CellConstraints cc2 = new CellConstraints();
       builder.addLabel(
           "&Name:",           // Mnemonic is 'N'
           cc1.xy(1, 7),       // sets instance 1 to (1, 7)
           nameField,
           cc2.xy(3, 7)        // sets instance 2 to (3, 7)
       );

  Parameters:
    `textWithMnemonic` - the label's text - may contain an ampersand (`&`) to mark a mnemonic
    `labelConstraints` - the label's cell constraints
    `component` - the component to add
    `componentConstraints` - the component's cell constraints
  Returns:
    the added label
  Throws:
    `IllegalArgumentException` - if the same cell constraints instance is used for the label and the component
  See Also:
    `JLabel.setLabelFor(java.awt.Component)`, `ComponentFactory`, `DefaultFormBuilder`

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

### getComponentFactory

    public final ComponentFactory getComponentFactory()

  Returns the builder's component factory. If no factory has been set before, it is lazily initialized using with an instance of `DefaultComponentFactory`.

  Returns:
    the component factory
  See Also:
    `setComponentFactory(ComponentFactory)`

### setComponentFactory

    public final void setComponentFactory(ComponentFactory newFactory)

  Sets a new component factory.

  Parameters:
    `newFactory` - the component factory to be set
  See Also:
    `getComponentFactory()`

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-2007 JGoodies Karsten Lentzsch. All Rights Reserved.