com.jgoodies.forms.builder

## Class ButtonStackBuilder

- java.lang.Object
- - com.jgoodies.forms.builder.AbstractBuilder
  - - com.jgoodies.forms.builder.AbstractButtonPanelBuilder
    - - com.jgoodies.forms.builder.ButtonStackBuilder

-     public final class ButtonStackBuilder
      extends AbstractButtonPanelBuilder

  Builds consistent button stacks that comply with popular style guides. Utilizes the JGoodies `FormLayout` and honors the platform's `LayoutStyle` regarding button sizes, and gaps.

  This builder sets a hint for narrow margin for the gridded buttons. This can reduce the button stack's width if some buttons have long texts. For example, a stack with 'OK', 'Cancel', 'Configure…' will likely exceed the minimum button width. The narrow margins help getting narrow stacks. Note that some look&feels do not support the narrow margin feature, and conversely, others have only narrow margins. The JGoodies look&feels honor the setting, the Mac Aqua l&f uses narrow margins all the time.

  Example:
  The following example builds a button stack with Close, Up and Down, where Up and Down are related, and Close is not related to the other buttons, which makes a wide gap for the unrelated and a smaller gap for the related buttons.

       private JPanel createCloseUpDownButtonStack(
               JButton close, JButton up, JButton down) {
           return ButtonStackBuilder().create()
                      .addGridded(close)
                      .addUnrelatedGap()
                      .addGridded(up)
                      .addRelatedGap()
                      .addGridded(down)
                      .build();
       }

  Version:
    $Revision: 1.15 $
  Author:
    Karsten Lentzsch
  See Also:
    `ButtonBarBuilder`, `LayoutStyle`

- - ### Field Summary

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

      `focusGrouped`

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

      `currentCellConstraints`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ButtonStackBuilder()` Constructs a ButtonStackBuilder on a default JPanel using a pre-configured FormLayout as layout manager.
    `ButtonStackBuilder(JPanel panel)` Constructs a ButtonStackBuilder on the given panel using a pre-configured FormLayout as layout manager.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ButtonStackBuilder` | `addButton(Action... actions)` Constructs an array of JButtons from the given Action array, and adds them as a sequence of related buttons separated by a default gap.
    `ButtonStackBuilder` | `addButton(JComponent... buttons)` Adds one or many sequences of related buttons.
    `ButtonStackBuilder` | `addButton(JComponent button)` Adds a button component that has a minimum width specified by the `LayoutStyle.getDefaultButtonWidth()`.
    `ButtonStackBuilder` | `addFixed(JComponent component)` Adds a fixed size component.
    `ButtonStackBuilder` | `addGlue()` Adds a glue that will be given the extra space, if this box is larger than its preferred size.
    `ButtonStackBuilder` | `addRelatedGap()` Adds the standard gap for related components.
    `ButtonStackBuilder` | `addStrut(ConstantSize size)` Adds a strut of a specified size.
    `ButtonStackBuilder` | `addUnrelatedGap()` Adds the standard gap for unrelated components.
    `ButtonStackBuilder` | `background(Color background)` Sets the panel's background color and makes the panel opaque.
    `ButtonStackBuilder` | `border(Border border)` Sets the panel's border.
    `static ButtonStackBuilder` | `create()` Creates and returns an empty ButtonStackBuilder.
    `ButtonStackBuilder` | `opaque(boolean b)` Sets the panel's opaque state.

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

      `add, appendColumn, appendGlueColumn, appendGlueRow, appendRelatedComponentsGapColumn, appendRelatedComponentsGapRow, appendRow, appendUnrelatedComponentsGapColumn, appendUnrelatedComponentsGapRow, build, createButton, getColumn, getPanel, getRow, isLeftToRight, nextColumn, nextRow, setBackground, setBorder, setLeftToRight, setOpaque`

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

    - #### ButtonStackBuilder

          public ButtonStackBuilder()

      Constructs a ButtonStackBuilder on a default JPanel using a pre-configured FormLayout as layout manager.

    - #### ButtonStackBuilder

          public ButtonStackBuilder(JPanel panel)

      Constructs a ButtonStackBuilder on the given panel using a pre-configured FormLayout as layout manager.
      Parameters:
        `panel` - the layout container

  - ### Method Detail

    - #### create

          public static ButtonStackBuilder create()

      Creates and returns an empty ButtonStackBuilder.
      Returns:
        the created builder
      Since:
        1.8

    - #### addButton

          public ButtonStackBuilder addButton(JComponent button)

      Adds a button component that has a minimum width specified by the `LayoutStyle.getDefaultButtonWidth()`.

      Although a JButton is expected, any JComponent is accepted to allow custom button component types.

      Specified by:
        `addButton` in class `AbstractButtonPanelBuilder`
      Parameters:
        `button` - the component to add
      Returns:
        this builder
      Throws:
        `NullPointerException` - if `button` is `null`

    - #### addButton

          public ButtonStackBuilder addButton(JComponent... buttons)

      Description copied from class: `AbstractButtonPanelBuilder`
      Adds one or many sequences of related buttons. A new sequence starts when a button is `null`. The next sequence is separated by an unrelated gap. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

      Although JButtons are expected, general JComponents are accepted to allow custom button component types.

      Examples:

           builder.addButtons(newButton, editButton, deleteButton);
           builder.addButtons(newButton, editButton, deleteButton, null, printButton);

      Overrides:
        `addButton` in class `AbstractButtonPanelBuilder`
      Parameters:
        `buttons` - the buttons to add
      Returns:
        this builder
      See Also:
        `AbstractButtonPanelBuilder.addButton(JComponent)`

    - #### addButton

          public ButtonStackBuilder addButton(Action... actions)

      Description copied from class: `AbstractButtonPanelBuilder`
      Constructs an array of JButtons from the given Action array, and adds them as a sequence of related buttons separated by a default gap.
      Overrides:
        `addButton` in class `AbstractButtonPanelBuilder`
      Parameters:
        `actions` - an array of buttons to add

    - #### addFixed

          public ButtonStackBuilder addFixed(JComponent component)

      Adds a fixed size component.
      Parameters:
        `component` - the component to add

    - #### addGlue

          public ButtonStackBuilder addGlue()

      Adds a glue that will be given the extra space, if this box is larger than its preferred size.

    - #### addRelatedGap

          public ButtonStackBuilder addRelatedGap()

      Description copied from class: `AbstractButtonPanelBuilder`
      Adds the standard gap for related components.
      Specified by:
        `addRelatedGap` in class `AbstractButtonPanelBuilder`

    - #### addUnrelatedGap

          public ButtonStackBuilder addUnrelatedGap()

      Description copied from class: `AbstractButtonPanelBuilder`
      Adds the standard gap for unrelated components.
      Specified by:
        `addUnrelatedGap` in class `AbstractButtonPanelBuilder`

    - #### addStrut

          public ButtonStackBuilder addStrut(ConstantSize size)

      Adds a strut of a specified size.
      Parameters:
        `size` - a constant that describes the gap

    - #### background

          public ButtonStackBuilder background(Color background)

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

    - #### border

          public ButtonStackBuilder border(Border border)

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

    - #### opaque

          public ButtonStackBuilder opaque(boolean b)

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

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