Forms (JGoodies Forms 1.9 API)
Date: 2015-02-02

com.jgoodies.forms.factories

## Class Forms

- java.lang.Object
- - com.jgoodies.forms.factories.Forms

-     public final class Forms
      extends Object

  Provides convenience behavior for building frequently used categories of forms.
  Since:
    1.6
  Version:
    $Revision: 1.1 $
  Author:
    Karsten Lentzsch

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static JComponent` | `border(Border border, JComponent component)` Creates and returns a panel where `component` is surrounded by the given border.
    `static JComponent` | `border(String emptyBorderSpec, JComponent component)` Deprecated. Use `padding(JComponent,String, Object...)` instead
    `static JComponent` | `buttonBar(JComponent... buttons)` Creates and returns a panel where the given buttons are laid out horizontally using a ButtonBarBuilder.
    `static JComponent` | `buttonStack(JComponent... buttons)` Creates and returns a panel where the given buttons are laid out vertically using a ButtonStackBuilder.
    `static JComponent` | `centered(JComponent component)` Creates and returns a panel where `component` is centered.
    `static JComponent` | `checkBoxBar(JCheckBox... checkBoxes)` Builds and returns a panel where the given check boxes are laid out horizontally.
    `static JComponent` | `checkBoxStack(JCheckBox... checkBoxes)` Builds and returns a panel where the given check boxes are laid out vertically.
    `static JComponent` | `horizontal(String gapColSpec, JComponent... components)` Builds and returns a panel where the given components are laid out horizontally separated by gaps as described by the given FormLayout gap (column) specification.
    `static JComponent` | `padding(JComponent component, EmptyBorder padding)` Creates and returns a panel where `component` is surrounded by the given empty border.
    `static JComponent` | `padding(JComponent component, String paddingSpec, Object... args)` Creates and returns a panel where `component` is surrounded by white space (an empty border) as described by `paddingSpec`.
    `static JComponent` | `radioButtonBar(JRadioButton... radioButtons)` Builds and returns a panel where the given radio buttons are laid horizontally.
    `static JComponent` | `radioButtonStack(JRadioButton... radioButtons)` Builds and returns a panel where the given radio buttons are laid vertically.
    `static JComponent` | `single(String columnSpec, String rowSpec, JComponent component)` Creates and returns a panel where `component` is laid out using a FormLayout with the given column and row specifications.
    `static JComponent` | `vertical(String gapRowSpec, JComponent... components)` Builds and returns a panel where the given components are laid out vertically separated by gaps as described by the given FormLayout gap (row) specification.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### single

          public static JComponent single(String columnSpec,
                          String rowSpec,
                          JComponent component)

      Creates and returns a panel where `component` is laid out using a FormLayout with the given column and row specifications.

      >      Forms.single(  "left:150dlu",      "c:p",     component);
      >      Forms.single(  "fill:150dlu:grow", "f:20dlu", component);
      >      Forms.single("center:150dlu",      "b:p:g",   component);

      Parameters:
        `columnSpec` - a FormLayout column specification for a single column
        `rowSpec` - a FormLayout row specification for a single row
        `component` - the component to lay out
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `columnSpec`, `rowSpec`, or `component` is `null`
        `IllegalArgumentException` - if `columnSpec` or `rowSpec` is empty or whitespace

    - #### centered

          public static JComponent centered(JComponent component)

      Creates and returns a panel where `component` is centered. The panel grows both horizontally and vertically as its container grows.

      >      Forms.centered(anImageLabel);
      >      Forms.centered(anAnimatedPanel);

      Parameters:
        `component` - the component to center
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `component` is `null`

    - #### border

          public static JComponent border(Border border,
                          JComponent component)

      Creates and returns a panel where `component` is surrounded by the given border.

      >      Forms.border(new LineBorder(Color.GRAY), aComponent);

      Parameters:
        `border` - the border used to surround the component
        `component` - the component to wrap
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `border` or `component` is `null`

    - #### border

          @Deprecated
          public static JComponent border(String emptyBorderSpec,
                                     JComponent component)

      Deprecated. Use `padding(JComponent,String, Object...)` instead
      Creates and returns a panel where `component` is surrounded by an empty border as described by `emptyBorderSpec`.

      >      Forms.border("4dlu, 0, 4dlu, 8dlu", aComponent);
      >      Forms.border("10px 4px, 10px, 4px", aComponent);

      Parameters:
        `component` - the component to wrap
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `emptyBorderSpec` or `component` is `null`

    - #### padding

          public static JComponent padding(JComponent component,
                           EmptyBorder padding)

      Creates and returns a panel where `component` is surrounded by the given empty border.

      >      Forms.padding(aComponent, Paddings.DLU14);

      Parameters:
        `component` - the component to wrap
        `padding` - the empty border used to surround the component
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `border` or `component` is `null`

    - #### padding

          public static JComponent padding(JComponent component,
                           String paddingSpec,
                           Object... args)

      Creates and returns a panel where `component` is surrounded by white space (an empty border) as described by `paddingSpec`.

      >      Forms.padding(aComponent, "4dlu, 0, 4dlu,  8dlu");
      >      Forms.padding(aComponent, "10px 4px, 10px, %spx", left);

      Parameters:
        `component` - the component to wrap
        `paddingSpec` - describes the white space: top, left, bottom, right
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `paddingSpec` or `component` is `null`
      See Also:
        `padding(JComponent, EmptyBorder)`, `Paddings.createPadding(String, Object...)`

    - #### horizontal

          public static JComponent horizontal(String gapColSpec,
                              JComponent... components)

      Builds and returns a panel where the given components are laid out horizontally separated by gaps as described by the given FormLayout gap (column) specification.

      >      Forms.horizontal("4dlu",  component1, component2);
      >      Forms.horizontal("$rgap", component1, component2, component3);
      >      Forms.horizontal("0",     component1, component2, component3);

      Parameters:
        `gapColSpec` - describes the horizontal gap between the components
        `components` - the components to be laid out
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `components` is `null`
        `IllegalArgumentException` - if `components` is empty

    - #### vertical

          public static JComponent vertical(String gapRowSpec,
                            JComponent... components)

      Builds and returns a panel where the given components are laid out vertically separated by gaps as described by the given FormLayout gap (row) specification.

      >      Forms.vertical("4dlu",  component1, component2);
      >      Forms.vertical("$rgap", component1, component2, component3);
      >      Forms.vertical("0",     component1, component2, component3);

      Parameters:
        `gapRowSpec` - describes the vertical gap between the components
        `components` - the components to be laid out
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `components` is `null`
        `IllegalArgumentException` - if `components` is empty

    - #### buttonBar

          public static JComponent buttonBar(JComponent... buttons)

      Creates and returns a panel where the given buttons are laid out horizontally using a ButtonBarBuilder. Equivalent to:

      >      ButtonBarBuilder.create().addButton(buttons).build();

      If class `com.jgoodies.jsdl.common.focus.FocusTraversalUtils` from the JSDL Common library is in the class path, it is used to build a focus group for the buttons. Focus is transferred between the buttons with cursor-left/-right.

      Parameters:
        `buttons` - the buttons to add to the button bar
      Returns:
        the built button bar
      Throws:
        `NullPointerException` - if `buttons` is `null`
        `IllegalArgumentException` - if `buttons` is empty
      See Also:
        `ButtonBarBuilder`

    - #### buttonStack

          public static JComponent buttonStack(JComponent... buttons)

      Creates and returns a panel where the given buttons are laid out vertically using a ButtonStackBuilder. Equivalent to:

      >      ButtonStackBuilder.create().addButton(buttons).build();

      If class `com.jgoodies.jsdl.common.focus.FocusTraversalUtils` from the JSDL Common library is in the class path, it is used to build a focus group for the buttons. Focus is transferred between the buttons with cursor-left/-right.

      Parameters:
        `buttons` - the buttons to add to the button stack
      Returns:
        the built button stack
      Throws:
        `NullPointerException` - if `buttons` is `null`
        `IllegalArgumentException` - if `buttons` is empty
      Since:
        1.8
      See Also:
        `ButtonStackBuilder`

    - #### checkBoxBar

          public static JComponent checkBoxBar(JCheckBox... checkBoxes)

      Builds and returns a panel where the given check boxes are laid out horizontally.

      If class `com.jgoodies.jsdl.common.focus.FocusTraversalUtils` from the JSDL Common library is in the class path, it is used to group the radio buttons. Focus is transferred to/from the selected button in a group; and cursor-left/-right change the selection in the group.

      Parameters:
        `checkBoxes` - the check boxes to lay out in a row
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `checkBoxes` is `null`
        `IllegalArgumentException` - if `checkBoxes` is empty

    - #### checkBoxStack

          public static JComponent checkBoxStack(JCheckBox... checkBoxes)

      Builds and returns a panel where the given check boxes are laid out vertically.

      If class `com.jgoodies.jsdl.common.focus.FocusTraversalUtils` from the JSDL Common library is in the class path, it is used to group the radio buttons. Focus is transferred to/from the selected button in a group; and cursor-left/-right change the selection in the group.

      Parameters:
        `checkBoxes` - the check boxes to lay out in a stack
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `checkBoxes` is `null`
        `IllegalArgumentException` - if `checkBoxes` is empty
      Since:
        1.8

    - #### radioButtonBar

          public static JComponent radioButtonBar(JRadioButton... radioButtons)

      Builds and returns a panel where the given radio buttons are laid horizontally.

      If class `com.jgoodies.jsdl.common.focus.FocusTraversalUtils` from the JSDL Common library is in the class path, it is used to group the radio buttons. Focus is transferred to/from the selected button in a group; and cursor-left/-right change the selection in the group.

      Parameters:
        `radioButtons` - the radio buttons to lay out in a row
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `radioButtons` is `null`
        `IllegalArgumentException` - if `radioButtons` is empty

    - #### radioButtonStack

          public static JComponent radioButtonStack(JRadioButton... radioButtons)

      Builds and returns a panel where the given radio buttons are laid vertically.

      If class `com.jgoodies.jsdl.common.focus.FocusTraversalUtils` from the JSDL Common library is in the class path, it is used to group the radio buttons. Focus is transferred to/from the selected button in a group; and cursor-left/-right change the selection in the group.

      Parameters:
        `radioButtons` - the radio buttons to lay out in a stack
      Returns:
        the built panel
      Throws:
        `NullPointerException` - if `radioButtons` is `null`
        `IllegalArgumentException` - if `radioButtons` is empty
      Since:
        1.8

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