Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.jgoodies.forms.builder
Class ButtonBarBuilder2

    java.lang.Object
      com.jgoodies.forms.builder.AbstractButtonPanelBuilder
          com.jgoodies.forms.builder.ButtonBarBuilder2

    public class ButtonBarBuilder2

extends AbstractButtonPanelBuilder

A non-visual builder for building consistent button bars that comply with popular style guides. Utilizes the JGoodies `FormLayout` and honors the platform's `LayoutStyle` regarding button sizes, gap widths, and the default button order.

This is an improved version of the older `ButtonBarBuilder`. The ButtonBarBuilder2 has a simpler, safer, and more convenient API, see below for a comparison.

ButtonBarBuilder2 vs. ButtonBarBuilder:
ButtonBarBuilder2 uses only 3 component types that can be added: button, standard, and growing button, where ButtonBarBuilder has button, fixed, and growing. Also, the ButtonBarBuilder2 doesn't group buttons. The layout of the ButtonBarBuilder and ButtonBarBuilder2 is the same if all buttons are smaller than `LayoutStyle.getDefaultButtonWidth()`. If some buttons are wider, ButtonBarBuilder2 will make only these buttons wider, where the old ButtonBarBuilder makes all (gridded) buttons wider.

Examples:

     // Build a right-aligned bar for: OK, Cancel, Apply
     ButtonBarBuilder2 builder = new ButtonBarBuilder2();
     builder.addGlue();
     builder.addButton(okButton);
     builder.addRelatedGap();
     builder.addButton(cancelButton);
     builder.addRelatedGap();
     builder.addButton(applyButton);
     return builder.getPanel();

     // Add a sequence of related buttons
     ButtonBarBuilder2 builder = new ButtonBarBuilder2();
     builder.addGlue();
     builder.addButton(okButton, cancelButton, applyButton);
     return builder.getPanel();

     // Add a sequence of related buttons for given Actions
     ButtonBarBuilder2 builder = new ButtonBarBuilder2();
     builder.addGlue();
     builder.addButton(okAction, cancelAction, applyAction);
     return builder.getPanel();

Buttons are added to a builder individually or as a sequence. To honor the platform's button order (left-to-right vs. right-to-left) this builder uses the leftToRightButtonOrder property. It is initialized with the current LayoutStyle's button order, which in turn is left-to-right on most platforms and right-to-left on the Mac OS X. Builder methods that create sequences of buttons (e.g. `addButton(JComponent[])` honor the button order. If you want to ignore the default button order, you can either add individual buttons, or create a ButtonBarBuilder2 instance with the order set to left-to-right. For the latter see `createLeftToRightBuilder()`. Also see the button order example below.

Example:
The following example builds a button bar with Help button on the left-hand side and OK, Cancel, Apply buttons on the right-hand side.

     private JPanel createHelpOKCancelApplyBar(
             JButton help, JButton ok, JButton cancel, JButton apply) {
         ButtonBarBuilder2 builder = new ButtonBarBuilder2();
         builder.addButton(help);
         builder.addUnrelatedGap();
         builder.addGlue();
         builder.addButton(new JButton[]{ok, cancel, apply});
         return builder.getPanel();
     }

Button Order Example:
The following example builds three button bars where one honors the platform's button order and the other two ignore it.

     public JComponent buildPanel() {
         FormLayout layout = new FormLayout("pref");
         DefaultFormBuilder rowBuilder = new DefaultFormBuilder(layout);
         rowBuilder.setDefaultDialogBorder();

         rowBuilder.append(buildButtonSequence(new ButtonBarBuilder2()));
         rowBuilder.append(buildButtonSequence(ButtonBarBuilder2.createLeftToRightBuilder()));
         rowBuilder.append(buildIndividualButtons(new ButtonBarBuilder2()));

         return rowBuilder.getPanel();
     }

     private Component buildButtonSequence(ButtonBarBuilder2 builder) {
         builder.addButton(new JButton[] {
                 new JButton("One"),
                 new JButton("Two"),
                 new JButton("Three")
         });
         return builder.getPanel();
     }

     private Component buildIndividualButtons(ButtonBarBuilder2 builder) {
         builder.addButton(new JButton("One"));
         builder.addRelatedGap();
         builder.addButton(new JButton("Two"));
         builder.addRelatedGap();
         builder.addButton(new JButton("Three"));
         return builder.getPanel();
     }

Version:
  $Revision: 1.14 $
Author:
  Karsten Lentzsch
See Also:
  `ButtonStackBuilder`, `ButtonBarFactory`, `LayoutStyle`

Field Summary

Fields inherited from class com.jgoodies.forms.builder.AbstractButtonPanelBuilder
`NARROW_KEY`

Constructor Summary
`ButtonBarBuilder2()` Constructs an empty ButtonBarBuilder2 on a JPanel.
`ButtonBarBuilder2(JPanel panel)` Constructs an empty ButtonBarBuilder2 on the given panel.

Method Summary
`void` | `addButton(Action action)` Adds a JButton for the given Action that has a minimum width specified by the `LayoutStyle.getDefaultButtonWidth()`.
`void` | `addButton(Action[] actions)` Adds a sequence of related JButtons built from the given Actions that are separated by the default gap as specified by `LayoutStyle.getRelatedComponentsPadX()`.
`void` | `addButton(Action action1, Action action2)` Adds a sequence of related JButtons built from the given Actions.
`void` | `addButton(Action action1, Action action2, Action action3)` Adds a sequence of related JButtons built from the given Actions.
`void` | `addButton(Action action1, Action action2, Action action3, Action action4)` Adds a sequence of related JButtons built from the given Actions.
`void` | `addButton(Action action1, Action action2, Action action3, Action action4, Action action5)` Adds a sequence of related JButtons built from the given Actions.
`void` | `addButton(JComponent button)` Adds a command button component that has a minimum width specified by the `LayoutStyle.getDefaultButtonWidth()`.
`void` | `addButton(JComponent[] buttons)` Adds a sequence of related button components.
`void` | `addButton(JComponent button1, JComponent button2)` Adds a sequence of related button components.
`void` | `addButton(JComponent button1, JComponent button2, JComponent button3)` Adds a sequence of related button components.
`void` | `addButton(JComponent button1, JComponent button2, JComponent button3, JComponent button4)` Adds a sequence of related button components.
`void` | `addButton(JComponent button1, JComponent button2, JComponent button3, JComponent button4, JComponent button5)` Adds a sequence of related button components.
`void` | `addFixed(JComponent component)` Adds a fixed size component with narrow margin.
`void` | `addGlue()` Adds a glue that will be given the extra space, if this button bar is larger than its preferred size.
`void` | `addGrowing(JComponent component)` Adds a button or other component that grows if the container grows.
`void` | `addGrowing(JComponent[] buttons)` Adds a sequence of related growing buttons where each is separated by a default gap.
`void` | `addRelatedGap()` Adds the standard horizontal gap for related components.
`void` | `addStrut(ConstantSize width)` Adds a horizontal strut of the specified width.
`void` | `addUnrelatedGap()` Adds the standard horizontal gap for unrelated components.
`static ButtonBarBuilder2` | `createLeftToRightBuilder()` Creates and returns an empty ButtonBarBuilder2 with a left to right button order.
`boolean` | `isLeftToRightButtonOrder()` Returns whether button sequences will be ordered from left to right or from right to left.
`void` | `setDefaultButtonBarGapBorder()` Sets a default border that has a gap in the bar's north.
`void` | `setLeftToRightButtonOrder(boolean newButtonOrder)` Sets the order for button sequences to either left to right, or right to left.

Methods inherited from class com.jgoodies.forms.builder.AbstractButtonPanelBuilder
`add, appendColumn, appendGlueColumn, appendGlueRow, appendRelatedComponentsGapColumn, appendRelatedComponentsGapRow, appendRow, appendUnrelatedComponentsGapColumn, appendUnrelatedComponentsGapRow, getColumn, getContainer, getLayout, getPanel, isLeftToRight, nextColumn, nextRow, setBackground, setBorder, setLeftToRight, setOpaque`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### ButtonBarBuilder2

    public ButtonBarBuilder2()

  Constructs an empty ButtonBarBuilder2 on a JPanel.

### ButtonBarBuilder2

    public ButtonBarBuilder2(JPanel panel)

  Constructs an empty ButtonBarBuilder2 on the given panel.

  Parameters:
    `panel` - the layout container

Method Detail

### createLeftToRightBuilder

    public static ButtonBarBuilder2 createLeftToRightBuilder()

  Creates and returns an empty ButtonBarBuilder2 with a left to right button order.

  Returns:
    a button bar builder with button order set to left-to-right

### isLeftToRightButtonOrder

    public boolean isLeftToRightButtonOrder()

  Returns whether button sequences will be ordered from left to right or from right to left.

  Returns:
    true if button sequences are ordered from left to right
  See Also:
    `LayoutStyle.isLeftToRightButtonOrder()`

### setLeftToRightButtonOrder

    public void setLeftToRightButtonOrder(boolean newButtonOrder)

  Sets the order for button sequences to either left to right, or right to left.

  Parameters:
    `newButtonOrder` - true if button sequences shall be ordered from left to right
  See Also:
    `LayoutStyle.isLeftToRightButtonOrder()`

### setDefaultButtonBarGapBorder

    public void setDefaultButtonBarGapBorder()

  Sets a default border that has a gap in the bar's north.

### addGlue

    public void addGlue()

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

### addRelatedGap

    public void addRelatedGap()

  Adds the standard horizontal gap for related components.

  See Also:
    `LayoutStyle.getRelatedComponentsPadX()`

### addUnrelatedGap

    public void addUnrelatedGap()

  Adds the standard horizontal gap for unrelated components.

  See Also:
    `LayoutStyle.getUnrelatedComponentsPadX()`

### addStrut

    public void 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
  See Also:
    `ColumnSpec.createGap(ConstantSize)`

### addButton

    public void addButton(JComponent button)

  Adds a command 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.

  Parameters:
    `button` - the component to add
  Throws:
    `NullPointerException` - if `button` is `null`

### addButton

    public void addButton(JComponent button1,
                          JComponent button2)

  Adds a sequence of related button components. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

  This method is equivalent to `addButton(new JComponent[]{button1, button2});`

  Parameters:
    `button1` - the first button to add
    `button2` - the second button to add
  Throws:
    `NullPointerException` - if a button is `null`
  See Also:
    `addButton(JComponent[])`

### addButton

    public void addButton(JComponent button1,
                          JComponent button2,
                          JComponent button3)

  Adds a sequence of related button components. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

  This method is equivalent to `addButton(new JComponent[]{button1, button2, button3});`

  Parameters:
    `button1` - the first button to add
    `button2` - the second button to add
    `button3` - the third button to add
  Throws:
    `NullPointerException` - if a button is `null`
  See Also:
    `addButton(JComponent[])`

### addButton

    public void addButton(JComponent button1,
                          JComponent button2,
                          JComponent button3,
                          JComponent button4)

  Adds a sequence of related button components. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

  This method is equivalent to `addButton(new JComponent[]{button1, button2, button3, button4});`

  Parameters:
    `button1` - the first button to add
    `button2` - the second button to add
    `button3` - the third button to add
    `button4` - the fourth button to add
  Throws:
    `NullPointerException` - if a button is `null`
  See Also:
    `addButton(JComponent[])`

### addButton

    public void addButton(JComponent button1,
                          JComponent button2,
                          JComponent button3,
                          JComponent button4,
                          JComponent button5)

  Adds a sequence of related button components. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

  This method is equivalent to `addButton(new JComponent[]{button1, button2, button3, button4, button5});`

  Parameters:
    `button1` - the first button to add
    `button2` - the second button to add
    `button3` - the third button to add
    `button4` - the fourth button to add
    `button5` - the fifth button to add
  Throws:
    `NullPointerException` - if a button is `null`
  See Also:
    `addButton(JComponent[])`

### addButton

    public void addButton(JComponent[] buttons)

  Adds a sequence of related button components. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

  Uses this builder's button order (left-to-right vs. right-to-left). If you want to use a fixed order, add individual buttons instead.

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

  Parameters:
    `buttons` - an array of buttons to add
  Throws:
    `NullPointerException` - if the button array or a button is `null`
    `IllegalArgumentException` - if the button array is empty
  See Also:
    `addButton(JComponent)`

### addButton

    public void addButton(Action action)

  Adds a JButton for the given Action that has a minimum width specified by the `LayoutStyle.getDefaultButtonWidth()`.

  Parameters:
    `action` - the action that describes the button to add
  Throws:
    `NullPointerException` - if `action` is `null`
  See Also:
    `addButton(JComponent)`

### addButton

    public void addButton(Action action1,
                          Action action2)

  Adds a sequence of related JButtons built from the given Actions. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

  This method is equivalent to `addButton(new Action[]{action1, action2});`

  Parameters:
    `action1` - describes the first button to add
    `action2` - describes the second button to add
  Throws:
    `NullPointerException` - if an Action is `null`
  See Also:
    `addButton(Action[])`, `addButton(JComponent[])`

### addButton

    public void addButton(Action action1,
                          Action action2,
                          Action action3)

  Adds a sequence of related JButtons built from the given Actions. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

  This method is equivalent to `addButton(new Action[]{action1, action2, action3});`

  Parameters:
    `action1` - describes the first button to add
    `action2` - describes the second button to add
    `action3` - describes the third button to add
  Throws:
    `NullPointerException` - if an Action is `null`
  See Also:
    `addButton(Action[])`, `addButton(JComponent[])`

### addButton

    public void addButton(Action action1,
                          Action action2,
                          Action action3,
                          Action action4)

  Adds a sequence of related JButtons built from the given Actions. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

  This method is equivalent to `addButton(new Action[]{action1, action2, action3, action4});`

  Parameters:
    `action1` - describes the first button to add
    `action2` - describes the second button to add
    `action3` - describes the third button to add
    `action4` - describes the fourth button to add
  Throws:
    `NullPointerException` - if an Action is `null`
  See Also:
    `addButton(Action[])`, `addButton(JComponent[])`

### addButton

    public void addButton(Action action1,
                          Action action2,
                          Action action3,
                          Action action4,
                          Action action5)

  Adds a sequence of related JButtons built from the given Actions. Each button has the minimum width as specified by `LayoutStyle.getDefaultButtonWidth()`. The gap width between the buttons is `LayoutStyle.getRelatedComponentsPadX()`.

  This method is equivalent to `addButton(new Action[]{action1, action2, action3, action4, action5});`

  Parameters:
    `action1` - describes the first button to add
    `action2` - describes the second button to add
    `action3` - describes the third button to add
    `action4` - describes the fourth button to add
    `action5` - describes the fifth button to add
  Throws:
    `NullPointerException` - if an Action is `null`
  See Also:
    `addButton(Action[])`, `addButton(JComponent[])`

### addButton

    public void addButton(Action[] actions)

  Adds a sequence of related JButtons built from the given Actions that are separated by the default gap as specified by `LayoutStyle.getRelatedComponentsPadX()`.

  Uses this builder's button order (left-to-right vs. right-to-left). If you want to use a fixed order, add individual Actions instead.

  Parameters:
    `actions` - the Actions that describe the buttons to add
  Throws:
    `NullPointerException` - if the Action array or an Action is `null`
    `IllegalArgumentException` - if the Action array is empty
  See Also:
    `addButton(JComponent[])`

### addGrowing

    public void addGrowing(JComponent component)

  Adds a button or other 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

### addGrowing

    public void addGrowing(JComponent[] buttons)

  Adds a sequence of related growing buttons where each is separated by a default gap. Honors this builder's button order. If you want to use a fixed left to right order, add individual buttons.

  Parameters:
    `buttons` - an array of buttons to add
  See Also:
    `LayoutStyle`

### addFixed

    public void addFixed(JComponent component)

  Adds a fixed size component with narrow margin. Unlike the gridded components, this component keeps its individual preferred dimension.

  Parameters:
    `component` - the component to add

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2009 JGoodies Karsten Lentzsch. All Rights Reserved.