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

com.jgoodies.forms.builder

## Class ButtonStackBuilder

- java.lang.Object
- - com.jgoodies.forms.internal.AbstractBuilder<B>
  - - com.jgoodies.forms.internal.AbstractButtonPanelBuilder<ButtonStackBuilder>
    - - com.jgoodies.forms.builder.ButtonStackBuilder

-     public final class ButtonStackBuilder
      extends AbstractButtonPanelBuilder<ButtonStackBuilder>

  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.internal.AbstractButtonPanelBuilder

      `focusGrouped`

    - ### Fields inherited from class com.jgoodies.forms.internal.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.
    `static ButtonStackBuilder` | `create()` Creates and returns an empty ButtonStackBuilder.

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

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

    - ### Methods inherited from class com.jgoodies.forms.internal.AbstractBuilder

      `background, border, border, createComponentFactory, getColumnCount, getComponentFactory, getContainer, getLayout, getPanel, getRowCount, opaque, padding, padding, 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<ButtonStackBuilder>`
      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<ButtonStackBuilder>`
      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<ButtonStackBuilder>`
      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<ButtonStackBuilder>`

    - #### addUnrelatedGap

          public ButtonStackBuilder addUnrelatedGap()

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

    - #### addStrut

          public ButtonStackBuilder addStrut(ConstantSize size)

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

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