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

com.jgoodies.forms.builder

## Class ButtonBarBuilder

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

-     public final class ButtonBarBuilder
      extends AbstractButtonPanelBuilder<ButtonBarBuilder>

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

  Examples:

       // 1) Build and return a bar with three related buttons
       return ButtonBarBuilder.create()
           .addButton(newButton)
           .addRelatedGap()
           .addButton(editButton)
           .addRelatedGap()
           .addButton(deleteButton)
           .build();

       // 2) Short hand for example 1)
       return ButtonBarBuilder.create()
           .addButton(newButton, editButton, deleteButton)
           .build();

       // 3) Build and return a bar with two sections
       return ButtonBarBuilder.create()
           .addButton(newButton, editButton, deleteButton)
           .addUnrelatedGap()
           .addButton(moveUpButton, moveDownButton)
           .build();

       // 4) Short hand for example 3)
       return ButtonBarBuilder.create()
           .addButton(newButton, editButton, deleteButton,
                      null,
                      moveUpButton, moveDownButton)
           .build();

       // 5) Build and return a complex button bar
       return ButtonBarBuilder.create()
           .addButton(newButton, editButton, deleteButton)
           .addUnrelatedGap()
           .addButton(moveUpButton, moveDownButton)
           .addGlue()
           .addGrowing(legendComponent)
           .build();

  Since:
    1.6
  Version:
    $Revision: 1.18 $
  Author:
    Karsten Lentzsch
  See Also:
    `ButtonStackBuilder`, `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
    `ButtonBarBuilder()` Constructs an empty ButtonBarBuilder on a JPanel.
    `ButtonBarBuilder(JPanel panel)` Constructs an empty ButtonBarBuilder on the given panel.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ButtonBarBuilder` | `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.
    `ButtonBarBuilder` | `addButton(JComponent... buttons)` Adds one or many sequences of related buttons.
    `ButtonBarBuilder` | `addButton(JComponent button)` Adds a button component that has a minimum width specified by the `LayoutStyle.getDefaultButtonWidth()`.
    `ButtonBarBuilder` | `addFixed(JComponent component)` Adds a fixed size component with narrow margin.
    `ButtonBarBuilder` | `addGlue()` Adds a glue that will be given the extra space, if this button bar is larger than its preferred size.
    `ButtonBarBuilder` | `addGrowing(JComponent component)` Adds a component that grows if the container grows.
    `ButtonBarBuilder` | `addRelatedGap()` Adds the standard horizontal gap for related components.
    `ButtonBarBuilder` | `addStrut(ConstantSize width)` Adds a horizontal strut of the specified width.
    `ButtonBarBuilder` | `addUnrelatedGap()` Adds the standard horizontal gap for unrelated components.
    `static ButtonBarBuilder` | `create()`

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

    - #### ButtonBarBuilder

          public ButtonBarBuilder()

      Constructs an empty ButtonBarBuilder on a JPanel.

    - #### ButtonBarBuilder

          public ButtonBarBuilder(JPanel panel)

      Constructs an empty ButtonBarBuilder on the given panel.
      Parameters:
        `panel` - the layout container

  - ### Method Detail

    - #### create

          public static ButtonBarBuilder create()

      Returns:
        an empty ButtonBarBuilder on a JPanel
      Since:
        1.8

    - #### addButton

          public ButtonBarBuilder 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<ButtonBarBuilder>`
      Parameters:
        `button` - the component to add
      Returns:
        this builder
      Throws:
        `NullPointerException` - if `button` is `null`

    - #### addButton

          public ButtonBarBuilder 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<ButtonBarBuilder>`
      Parameters:
        `buttons` - the buttons to add
      Returns:
        this builder
      See Also:
        `AbstractButtonPanelBuilder.addButton(JComponent)`

    - #### addButton

          public ButtonBarBuilder 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<ButtonBarBuilder>`
      Parameters:
        `actions` - an array of buttons to add

    - #### addFixed

          public ButtonBarBuilder addFixed(JComponent component)

      Adds a fixed size component with narrow margin. Unlike the buttons, this component is laid out without a minimum width. In other words, the width is determined only by the component's preferred width.
      Parameters:
        `component` - the component to add
      Returns:
        this builder

    - #### addGrowing

          public ButtonBarBuilder addGrowing(JComponent component)

      Adds a component that grows if the container grows. The component's initial size (before it grows) is specified by the `LayoutStyle.getDefaultButtonWidth()`.
      Parameters:
        `component` - the component to add
      Returns:
        this builder

    - #### addGlue

          public ButtonBarBuilder addGlue()

      Adds a glue that will be given the extra space, if this button bar is larger than its preferred size.
      Returns:
        this builder

    - #### addRelatedGap

          public ButtonBarBuilder addRelatedGap()

      Adds the standard horizontal gap for related components.
      Specified by:
        `addRelatedGap` in class `AbstractButtonPanelBuilder<ButtonBarBuilder>`
      Returns:
        this builder
      See Also:
        `LayoutStyle.getRelatedComponentsPadX()`

    - #### addUnrelatedGap

          public ButtonBarBuilder addUnrelatedGap()

      Adds the standard horizontal gap for unrelated components.
      Specified by:
        `addUnrelatedGap` in class `AbstractButtonPanelBuilder<ButtonBarBuilder>`
      Returns:
        this builder
      See Also:
        `LayoutStyle.getUnrelatedComponentsPadX()`

    - #### addStrut

          public ButtonBarBuilder addStrut(ConstantSize width)

      Adds a horizontal strut of the specified width. For related and unrelated components use `addRelatedGap()` and `addUnrelatedGap()` respectively.
      Parameters:
        `width` - describes the gap width
      Returns:
        this builder
      See Also:
        `ColumnSpec.createGap(ConstantSize)`

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