Class PanelBuilder

java.lang.Object
com.jgoodies.forms.internal.AbstractBuilder<PanelBuilder>
com.jgoodies.forms.internal.AbstractFormBuilder<PanelBuilder>
com.jgoodies.forms.builder.PanelBuilder
Direct Known Subclasses:
I15dPanelBuilder
@Deprecated public class PanelBuilder extends AbstractFormBuilder<PanelBuilder>
Deprecated.
Replaced by FormBuilder. However, this class will remain in the Forms library for the next versions.
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 "&Saveinvalid input: '&quot', or "Save &asinvalid input: '&quot'. To use the ampersand itself duplicate it, for example "Look&&Feelinvalid input: '&quot'.

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("invalid input: '&Title':",        CC.xy  (1, 1));
builder.add(new JTextField(),      CC.xywh(3, 1, 3, 1));
builder.addLabel("invalid input: '&Price':",        CC.xy  (1, 3));
builder.add(new JTextField(),      CC.xy  (3, 3));
builder.addLabel("invalid input: '&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:

  • Field Details

    • LABELED_BY_PROPERTY

      private static final String LABELED_BY_PROPERTY
      Deprecated.
      A JComponent client property that is used to determine the label labeling a component. Copied from the JLabel class.
      See Also:

    • labelForFeatureEnabled

      private boolean labelForFeatureEnabled
      Deprecated.
      The instance value for the setLabelFor feature. Is initialized using the global default.
      See Also:
      • invalid reference 
        #setLabelForFeatureEnabledDefault(boolean)
      • invalid reference 
        #setLabelForFeatureEnabledDefault(boolean)

    • mostRecentlyAddedLabelReference

      private WeakReference mostRecentlyAddedLabelReference
      Deprecated.
      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:

  • Constructor Details

    • PanelBuilder

      public PanelBuilder(FormLayout layout)
      Deprecated.
      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)
      Deprecated.
      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 Details

    • focusTraversal

      public PanelBuilder focusTraversal(FocusTraversalPolicy policy)
      Deprecated.
      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:

    • labelForFeatureEnabled

      public PanelBuilder labelForFeatureEnabled(boolean b)
      Deprecated.
      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

    • build

      public final JPanel build()
      Deprecated.
      Returns the panel used to build the form. Intended to return the panel in build methods.
      Specified by:
      build in class AbstractBuilder<PanelBuilder>
      Returns:
      the panel used by this builder to build the form
      Since:
      1.6

    • addLabel

      public final JLabel addLabel(String textWithMnemonic)
      Deprecated.
      Adds a textual label to the form using the default constraints.

      addLabel("Name:");       // No Mnemonic
addLabel("Ninvalid input: '&ame':");      // Mnemonic is 'a'
addLabel("Save invalid input: '&as':");   // Mnemonic is the second 'a'
addLabel("Lookinvalid input: '&'invalid input: '&Feel':"); // No mnemonic, text is "lookinvalid input: '&feel'"
      Parameters:
      textWithMnemonic - the label's text - may contain an ampersand (&) to mark a mnemonic
      Returns:
      the new label
      See Also:

    • addLabel

      public final JLabel addLabel(String textWithMnemonic, CellConstraints constraints)
      Deprecated.
      Adds a textual label to the form using the specified constraints.

      addLabel("Name:",       CC.xy(1, 1)); // No Mnemonic
addLabel("Ninvalid input: '&ame':",      CC.xy(1, 1)); // Mnemonic is 'a'
addLabel("Save invalid input: '&as':",   CC.xy(1, 1)); // Mnemonic is the second 'a'
addLabel("Lookinvalid input: '&'invalid input: '&Feel':", CC.xy(1, 1)); // No mnemonic, text is "lookinvalid input: '&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:

    • addLabel

      public final JLabel addLabel(String textWithMnemonic, String encodedConstraints)
      Deprecated.
      Adds a textual label to the form using the specified constraints.

      addLabel("Name:",       "1, 1"); // No Mnemonic
addLabel("Ninvalid input: '&ame':",      "1, 1"); // Mnemonic is 'a'
addLabel("Save invalid input: '&as':",   "1, 1"); // Mnemonic is the second 'a'
addLabel("Lookinvalid input: '&'invalid input: '&Feel':", "1, 1"); // No mnemonic, text is "lookinvalid input: '&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:

    • addLabel

      public final JLabel addLabel(String textWithMnemonic, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)
      Deprecated.
      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(
    "invalid input: '&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(
    "invalid input: '&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:

    • addROLabel

      public final JLabel addROLabel(String textWithMnemonic)
      Deprecated.
      Adds a textual label intended for labeling read-only components to the form using the default constraints.

      addROLabel("Name:");       // No Mnemonic
addROLabel("Ninvalid input: '&ame':");      // Mnemonic is 'a'
addROLabel("Save invalid input: '&as':");   // Mnemonic is the second 'a'
addROLabel("Lookinvalid input: '&'invalid input: '&Feel':"); // No mnemonic, text is "lookinvalid input: '&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)
      Deprecated.
      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("Ninvalid input: '&ame':",      CC.xy(1, 1)); // Mnemonic is 'a'
addROLabel("Save invalid input: '&as':",   CC.xy(1, 1)); // Mnemonic is the second 'a'
addROLabel("Lookinvalid input: '&'invalid input: '&Feel':", CC.xy(1, 1)); // No mnemonic, text is "lookinvalid input: '&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)
      Deprecated.
      Adds a textual label intended for labeling read-only components to the form using the specified constraints.

      addROLabel("Name:",       "1, 1"); // No Mnemonic
addROLabel("Ninvalid input: '&ame':",      "1, 1"); // Mnemonic is 'a'
addROLabel("Save invalid input: '&as':",   "1, 1"); // Mnemonic is the second 'a'
addROLabel("Lookinvalid input: '&'invalid input: '&Feel':", "1, 1"); // No mnemonic, text is "lookinvalid input: '&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)
      Deprecated.
      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(
    "invalid input: '&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(
    "invalid input: '&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:

    • addTitle

      public final JLabel addTitle(String textWithMnemonic)
      Deprecated.
      Adds a title label to the form using the default constraints.

      addTitle("Name");       // No mnemonic
addTitle("Ninvalid input: '&ame'");      // Mnemonic is 'a'
addTitle("Save invalid input: '&as'");   // Mnemonic is the second 'a'
addTitle("Lookinvalid input: '&'invalid input: '&Feel'"); // No mnemonic, text is Lookinvalid input: '&Feel'
      Parameters:
      textWithMnemonic - the title label's text - may contain an ampersand (&) to mark a mnemonic
      Returns:
      the added title label
      See Also:

    • addTitle

      public final JLabel addTitle(String textWithMnemonic, CellConstraints constraints)
      Deprecated.
      Adds a title label to the form using the specified constraints.

      addTitle("Name",       CC.xy(1, 1)); // No mnemonic
addTitle("Ninvalid input: '&ame'",      CC.xy(1, 1)); // Mnemonic is 'a'
addTitle("Save invalid input: '&as'",   CC.xy(1, 1)); // Mnemonic is the second 'a'
addTitle("Lookinvalid input: '&'invalid input: '&Feel'", CC.xy(1, 1)); // No mnemonic, text is Lookinvalid input: '&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:

    • addTitle

      public final JLabel addTitle(String textWithMnemonic, String encodedConstraints)
      Deprecated.
      Adds a title label to the form using the specified constraints.

      addTitle("Name",       "1, 1"); // No mnemonic
addTitle("Ninvalid input: '&ame'",      "1, 1"); // Mnemonic is 'a'
addTitle("Save invalid input: '&as'",   "1, 1"); // Mnemonic is the second 'a'
addTitle("Lookinvalid input: '&'invalid input: '&Feel'", "1, 1"); // No mnemonic, text is Lookinvalid input: '&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:

    • addSeparator

      public final JComponent addSeparator(String textWithMnemonic)
      Deprecated.
      Adds a titled separator to the form that spans all columns.

      addSeparator("Name");       // No Mnemonic
addSeparator("Ninvalid input: '&ame'");      // Mnemonic is 'a'
addSeparator("Save invalid input: '&as'");   // Mnemonic is the second 'a'
addSeparator("Lookinvalid input: '&'invalid input: '&Feel'"); // No mnemonic, text is "lookinvalid input: '&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)
      Deprecated.
      Adds a titled separator to the form using the specified constraints.

      addSeparator("Name",       CC.xy(1, 1)); // No Mnemonic
addSeparator("Ninvalid input: '&ame'",      CC.xy(1, 1)); // Mnemonic is 'a'
addSeparator("Save invalid input: '&as'",   CC.xy(1, 1)); // Mnemonic is the second 'a'
addSeparator("Lookinvalid input: '&'invalid input: '&Feel'", CC.xy(1, 1)); // No mnemonic, text is "lookinvalid input: '&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)
      Deprecated.
      Adds a titled separator to the form using the specified constraints.

      addSeparator("Name",       "1, 1"); // No Mnemonic
addSeparator("Ninvalid input: '&ame'",      "1, 1"); // Mnemonic is 'a'
addSeparator("Save invalid input: '&as'",   "1, 1"); // Mnemonic is the second 'a'
addSeparator("Lookinvalid input: '&'invalid input: '&Feel'", "1, 1"); // No mnemonic, text is "lookinvalid input: '&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)
      Deprecated.
      Adds a titled separator to the form that spans the specified columns.

      addSeparator("Name",       3); // No Mnemonic
addSeparator("Ninvalid input: '&ame'",      3); // Mnemonic is 'a'
addSeparator("Save invalid input: '&as'",   3); // Mnemonic is the second 'a'
addSeparator("Lookinvalid input: '&'invalid input: '&Feel'", 3); // No mnemonic, text is "lookinvalid input: '&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)
      Deprecated.
      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:

    • add

      public Component add(Component component, CellConstraints cellConstraints)
      Deprecated.
      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<PanelBuilder>
      Parameters:
      component - the component to add
      cellConstraints - the component's cell constraints
      Returns:
      the added component
      See Also:

    • manageLabelsAndComponents

      private void manageLabelsAndComponents(Component c)
      Deprecated.

    • isLabelForApplicable

      protected boolean isLabelForApplicable(JLabel label, Component component)
      Deprecated.
      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)
      Deprecated.
      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 JLabel getMostRecentlyAddedLabel()
      Deprecated.
      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(JLabel label)
      Deprecated.
      Sets the given label as most recently added label using a weak reference.
      Parameters:
      label - the label to be set

    • clearMostRecentlyAddedLabel

      private void clearMostRecentlyAddedLabel()
      Deprecated.
      Clears the reference to the most recently added mnemonic label.

    • checkConstraints

      private static void checkConstraints(CellConstraints c1, CellConstraints c2)
      Deprecated.