com.jgoodies.forms.builder

## Class I15dPanelBuilder

- java.lang.Object
- - com.jgoodies.forms.builder.AbstractBuilder
  - - com.jgoodies.forms.builder.AbstractFormBuilder
    - - com.jgoodies.forms.builder.PanelBuilder
      - - com.jgoodies.forms.builder.I15dPanelBuilder

- Direct Known Subclasses:
    DefaultFormBuilder

      public class I15dPanelBuilder
      extends PanelBuilder

  A general purpose builder class that uses the FormLayout to lay out JPanels. In addition to its superclass `PanelBuilder` this class provides convenience behavior to map resource keys to their associated internationalized (i15d) strings when adding labels, titles and titled separators.

  The localized texts used in methods `#addI15d*` can be marked texts, i.e. strings with an optional mnemonic marker. See the `MnemonicUtils` class comment for details.

  For debugging purposes you can automatically set a tooltip for the created labels that show its resource key. In case of an inproper resource localization, the label will show the wrong text, and the tooltip will help you identify the resource key with the broken localization. This feature can be enabled by calling `setDebugToolTipsEnabled`. If you want to enable it in a deployed application, you can set the system parameter `I15dPanelBuilder.debugToolTipsEnabled` to "true".

  Subclasses must implement the conversion from resource key to the localized string in `#getI15dString(String)`. For example class I15dPanelBuilder gets a ResourceBundle during construction, and requests strings from that bundle.

  Since:
    1.1
  Version:
    $Revision: 1.12 $
  Author:
    Karsten Lentzsch
  See Also:
    `ResourceBundle`

- - ### Field Summary

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

      `currentCellConstraints`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `I15dPanelBuilder(FormLayout layout, ResourceBundle bundle)` Constructs an I15dPanelBuilder for the given layout and resource bundle.
    `I15dPanelBuilder(FormLayout layout, ResourceBundle bundle, JPanel container)` Constructs an I15dPanelBuilder for the given FormLayout, resource bundle, and layout container.
    `I15dPanelBuilder(FormLayout layout, com.jgoodies.common.internal.StringResourceAccessor localizer)` Constructs an I15dPanelBuilder for the given FormLayout, resource bundle, and layout container.
    `I15dPanelBuilder(FormLayout layout, com.jgoodies.common.internal.StringResourceAccessor localizer, JPanel container)` Constructs an I15dPanelBuilder for the given FormLayout, resource bundle, and layout container.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `JLabel` | `addI15dLabel(String resourceKey, CellConstraints constraints)` Adds an internationalized (i15d) textual label to the form using the specified constraints.
    `JLabel` | `addI15dLabel(String resourceKey, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)` Adds an internationalized (i15d) label and component to the panel using the given cell constraints.
    `JLabel` | `addI15dLabel(String resourceKey, String encodedConstraints)` Adds an internationalized (i15d) textual label to the form using the specified constraints.
    `JLabel` | `addI15dROLabel(String resourceKey, CellConstraints constraints)` Adds an internationalized (i15d) textual label to the form using the specified constraints that is intended to label a read-only component.
    `JLabel` | `addI15dROLabel(String resourceKey, CellConstraints labelConstraints, Component component, CellConstraints componentConstraints)` Adds an internationalized (i15d) label and component to the panel using the given cell constraints.
    `JLabel` | `addI15dROLabel(String resourceKey, String encodedConstraints)` Adds an internationalized (i15d) textual label to the form using the specified constraints that is intended to label a read-only component.
    `JComponent` | `addI15dSeparator(String resourceKey, CellConstraints constraints)` Adds an internationalized (i15d) titled separator to the form using the specified constraints.
    `JComponent` | `addI15dSeparator(String resourceKey, String encodedConstraints)` Adds an internationalized (i15d) titled separator to the form using the specified constraints.
    `JLabel` | `addI15dTitle(String resourceKey, CellConstraints constraints)` Adds a title to the form using the specified constraints.
    `JLabel` | `addI15dTitle(String resourceKey, String encodedConstraints)` Adds a title to the form using the specified constraints.
    `I15dPanelBuilder` | `background(Color background)` Sets the panel's background color and the panel to be opaque.
    `I15dPanelBuilder` | `border(Border border)` Sets the panel's border.
    `I15dPanelBuilder` | `border(String emptyBorderSpec)` Sets the panel's border as an EmptyBorder using the given specification for the top, left, bottom, right in DLU.
    `I15dPanelBuilder` | `debugToolTipsEnabled(boolean b)`
    `I15dPanelBuilder` | `focusTraversal(FocusTraversalPolicy policy)` Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider.
    `protected String` | `getResourceString(String key)` Looks up and returns the internationalized (i15d) string for the given resource key, for example from a `ResourceBundle` or `ResourceMap`.
    `protected boolean` | `isDebugToolTipsEnabled()`
    `I15dPanelBuilder` | `opaque(boolean b)` Sets the panel's opaque state.

    - ### Methods inherited from class com.jgoodies.forms.builder.PanelBuilder

      `add, add, addLabel, addLabel, addLabel, addLabel, addROLabel, addROLabel, addROLabel, addROLabel, addSeparator, addSeparator, addSeparator, addSeparator, addTitle, addTitle, addTitle, build, getPanel, isLabelForApplicable, labelForFeatureEnabled, setBorder, setDefaultDialogBorder, setLabelFor, setOpaque`

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

    - #### I15dPanelBuilder

          public I15dPanelBuilder(FormLayout layout,
                          ResourceBundle bundle)

      Constructs an I15dPanelBuilder for the given layout and resource bundle. Uses an instance of JPanel as layout container.
      Parameters:
        `layout` - the FormLayout used to layout the container
        `bundle` - the ResourceBundle used to look up i15d strings
      Throws:
        `NullPointerException` - if `layout` or `bundle`, is `null`

    - #### I15dPanelBuilder

          public I15dPanelBuilder(FormLayout layout,
                          ResourceBundle bundle,
                          JPanel container)

      Constructs an I15dPanelBuilder for the given FormLayout, resource bundle, and layout container.
      Parameters:
        `layout` - the FormLayout used to layout the container
        `bundle` - the ResourceBundle used to lookup i15d strings
        `container` - the layout container
      Throws:
        `NullPointerException` - if `layout`, `bundle`, or `container` is `null`

    - #### I15dPanelBuilder

          public I15dPanelBuilder(FormLayout layout,
                          com.jgoodies.common.internal.StringResourceAccessor localizer)

      Constructs an I15dPanelBuilder for the given FormLayout, resource bundle, and layout container.
      Parameters:
        `layout` - the FormLayout used to layout the container
        `localizer` - used to lookup i15d strings
      Throws:
        `NullPointerException` - if `layout` is `null`

    - #### I15dPanelBuilder

          public I15dPanelBuilder(FormLayout layout,
                          com.jgoodies.common.internal.StringResourceAccessor localizer,
                          JPanel container)

      Constructs an I15dPanelBuilder for the given FormLayout, resource bundle, and layout container.
      Parameters:
        `layout` - the FormLayout used to layout the container
        `localizer` - used to lookup i15d strings
        `container` - the layout container
      Throws:
        `NullPointerException` - if `layout` or `container` is `null`

  - ### Method Detail

    - #### background

          public I15dPanelBuilder background(Color background)

      Description copied from class: `PanelBuilder`
      Sets the panel's background color and the panel to be opaque.
      Overrides:
        `background` in class `PanelBuilder`
      Parameters:
        `background` - the color to set as new background
      See Also:
        `JComponent.setBackground(Color)`

    - #### border

          public I15dPanelBuilder border(Border border)

      Description copied from class: `PanelBuilder`
      Sets the panel's border.
      Overrides:
        `border` in class `PanelBuilder`
      Parameters:
        `border` - the border to set
      See Also:
        `JComponent.setBorder(Border)`

    - #### border

          public I15dPanelBuilder border(String emptyBorderSpec)

      Description copied from class: `PanelBuilder`
      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))`.

      Overrides:
        `border` in class `PanelBuilder`
      Parameters:
        `emptyBorderSpec` - describes the top, left, bottom, right sizes of the EmptyBorder to create
      See Also:
        `Borders.createEmptyBorder(String)`

    - #### opaque

          public I15dPanelBuilder opaque(boolean b)

      Description copied from class: `PanelBuilder`
      Sets the panel's opaque state.
      Overrides:
        `opaque` in class `PanelBuilder`
      Parameters:
        `b` - true for opaque, false for non-opaque
      See Also:
        `JComponent.setOpaque(boolean)`

    - #### focusTraversal

          public I15dPanelBuilder focusTraversal(FocusTraversalPolicy policy)

      Description copied from class: `PanelBuilder`
      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);

      Overrides:
        `focusTraversal` in class `PanelBuilder`
      Parameters:
        `policy` - the focus traversal policy that will manage keyboard traversal of the children in this builder's panel
      See Also:
        `Container.setFocusTraversalPolicy(FocusTraversalPolicy)`, `Container.setFocusTraversalPolicyProvider(boolean)`

    - #### debugToolTipsEnabled

          public I15dPanelBuilder debugToolTipsEnabled(boolean b)

    - #### addI15dLabel

          public final JLabel addI15dLabel(String resourceKey,
                            CellConstraints constraints)

      Adds an internationalized (i15d) textual label to the form using the specified constraints.
      Parameters:
        `resourceKey` - the resource key for the label's text
        `constraints` - the label's cell constraints
      Returns:
        the added label

    - #### addI15dLabel

          public final JLabel addI15dLabel(String resourceKey,
                            String encodedConstraints)

      Adds an internationalized (i15d) textual label to the form using the specified constraints.
      Parameters:
        `resourceKey` - the resource key for the label's text
        `encodedConstraints` - a string representation for the constraints
      Returns:
        the added label

    - #### addI15dLabel

          public final JLabel addI15dLabel(String resourceKey,
                            CellConstraints labelConstraints,
                            Component component,
                            CellConstraints componentConstraints)

      Adds an internationalized (i15d) label and component to the panel using the given cell constraints. Sets the 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.addI15dLabel("name.key",
                       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.addI15dLabel("name.key",
                       CC.xy(1, 7).clone(), // cloned before the next modification
                       nameField,
                       CC.xy(3, 7)          // sets this instance to (3, 7)
                      );

      Parameters:
        `resourceKey` - the resource key for the label
        `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)`

    - #### addI15dROLabel

          public final JLabel addI15dROLabel(String resourceKey,
                              CellConstraints constraints)

      Adds an internationalized (i15d) textual label to the form using the specified constraints that is intended to label a read-only component.
      Parameters:
        `resourceKey` - the resource key for the label's text
        `constraints` - the label's cell constraints
      Returns:
        the added label
      Since:
        1.3

    - #### addI15dROLabel

          public final JLabel addI15dROLabel(String resourceKey,
                              String encodedConstraints)

      Adds an internationalized (i15d) textual label to the form using the specified constraints that is intended to label a read-only component.
      Parameters:
        `resourceKey` - the resource key for the label's text
        `encodedConstraints` - a string representation for the constraints
      Returns:
        the added label
      Since:
        1.3

    - #### addI15dROLabel

          public final JLabel addI15dROLabel(String resourceKey,
                              CellConstraints labelConstraints,
                              Component component,
                              CellConstraints componentConstraints)

      Adds an internationalized (i15d) label and component to the panel using the given cell constraints. Intended for read-only components. Sets the 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.addI15dROLabel("name.key",
                       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.addI15dROLabel("name.key",
                       CC.xy(1, 7).clone(), // cloned before the next modification
                       nameField,
                       CC.xy(3, 7)          // sets this instance to (3, 7)
                      );

      Better:

           builder.addI15dROLabel("name.key",
                       CC.xy(1, 7)          // creates a CellConstraints object
                       nameField,
                       CC.xy(3, 7)          // creates another CellConstraints object
                      );

      Parameters:
        `resourceKey` - the resource key for the label
        `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)`

    - #### addI15dSeparator

          public final JComponent addI15dSeparator(String resourceKey,
                                    CellConstraints constraints)

      Adds an internationalized (i15d) titled separator to the form using the specified constraints.
      Parameters:
        `resourceKey` - the resource key for the separator title
        `constraints` - the separator's cell constraints
      Returns:
        the added titled separator

    - #### addI15dSeparator

          public final JComponent addI15dSeparator(String resourceKey,
                                    String encodedConstraints)

      Adds an internationalized (i15d) titled separator to the form using the specified constraints.
      Parameters:
        `resourceKey` - the resource key for the separator title
        `encodedConstraints` - a string representation for the constraints
      Returns:
        the added titled separator

    - #### addI15dTitle

          public final JLabel addI15dTitle(String resourceKey,
                            CellConstraints constraints)

      Adds a title to the form using the specified constraints.
      Parameters:
        `resourceKey` - the resource key for the separator title
        `constraints` - the separator's cell constraints
      Returns:
        the added title label

    - #### addI15dTitle

          public final JLabel addI15dTitle(String resourceKey,
                            String encodedConstraints)

      Adds a title to the form using the specified constraints.
      Parameters:
        `resourceKey` - the resource key for the separator title
        `encodedConstraints` - a string representation for the constraints
      Returns:
        the added title label

    - #### isDebugToolTipsEnabled

          protected final boolean isDebugToolTipsEnabled()

    - #### getResourceString

          protected final String getResourceString(String key)

      Looks up and returns the internationalized (i15d) string for the given resource key, for example from a `ResourceBundle` or `ResourceMap`.
      Parameters:
        `key` - the key to look for in the resource map
      Returns:
        the associated internationalized string, or the resource key itself in case of a missing resource
      Throws:
        `IllegalStateException` - if the localization is not possible, for example, because no ResourceBundle or StringLocalizer has been set

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