com.jgoodies.forms.builder
Class ButtonBarBuilder2

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

Deprecated. Replaced by the ButtonBarBuilder

@Deprecated
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.border(Borders.DIALOG);

     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.18 $

Author:

Karsten Lentzsch

See Also:

ButtonStackBuilder, 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

ButtonBarBuilder2()
Deprecated. Constructs an empty ButtonBarBuilder2 on a JPanel.

ButtonBarBuilder2(JPanel panel)
Deprecated. Constructs an empty ButtonBarBuilder2 on the given panel.

Method Summary

ButtonBarBuilder2	addButton(Action... actions) Deprecated. Constructs an array of JButtons from the given Action array, and adds them as a sequence of related buttons separated by a default gap.
ButtonBarBuilder2	addButton(Action action) Deprecated. Adds a JButton for the given Action that has a minimum width specified by the LayoutStyle.getDefaultButtonWidth().
ButtonBarBuilder2	addButton(JComponent... buttons) Deprecated. Adds a sequence of related button components.
ButtonBarBuilder2	addButton(JComponent button) Deprecated. Adds a command button component that has a minimum width specified by the LayoutStyle.getDefaultButtonWidth().
ButtonBarBuilder2	addFixed(JComponent component) Deprecated. Adds a fixed size component with narrow margin.
ButtonBarBuilder2	addGlue() Deprecated. Adds a glue that will be given the extra space, if this button bar is larger than its preferred size.
ButtonBarBuilder2	addGrowing(JComponent... buttons) Deprecated. Adds a sequence of related growing buttons where each is separated by a default gap.
ButtonBarBuilder2	addGrowing(JComponent component) Deprecated. Adds a button or other component that grows if the container grows.
ButtonBarBuilder2	addRelatedGap() Deprecated. Adds the standard gap for related components.
ButtonBarBuilder2	addStrut(ConstantSize width) Deprecated. Adds a horizontal strut of the specified width.
ButtonBarBuilder2	addUnrelatedGap() Deprecated. Adds the standard gap for unrelated components.
static ButtonBarBuilder2	createLeftToRightBuilder() Deprecated. Creates and returns an empty ButtonBarBuilder2 with a left to right button order.
boolean	isLeftToRightButtonOrder() Deprecated. Returns whether button sequences will be ordered from left to right or from right to left.
ButtonBarBuilder2	setDefaultButtonBarGapBorder() Deprecated. Sets a default border that has a gap in the bar's north.
ButtonBarBuilder2	setLeftToRightButtonOrder(boolean newButtonOrder) Deprecated. 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, background, border, build, createButton, getColumn, getPanel, getRow, isLeftToRight, nextColumn, nextRow, opaque, setBackground, setBorder, setLeftToRight, setOpaque

Methods inherited from class com.jgoodies.forms.builder.AbstractBuilder

createComponentFactory, getColumnCount, getComponentFactory, getComponentFactoryDefault, getContainer, getLayout, getRowCount, setComponentFactory, setComponentFactoryDefault

Methods inherited from class java.lang.Object

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

Constructor Detail

ButtonBarBuilder2

public ButtonBarBuilder2()

Deprecated.

Constructs an empty ButtonBarBuilder2 on a JPanel.

ButtonBarBuilder2

public ButtonBarBuilder2(JPanel panel)

Deprecated.

Constructs an empty ButtonBarBuilder2 on the given panel.

Parameters:

panel - the layout container

Method Detail

createLeftToRightBuilder

public static ButtonBarBuilder2 createLeftToRightBuilder()

Deprecated.

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()

Deprecated.

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

setLeftToRightButtonOrder

public ButtonBarBuilder2 setLeftToRightButtonOrder(boolean newButtonOrder)

Deprecated.

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

Returns:

this builder

setDefaultButtonBarGapBorder

public ButtonBarBuilder2 setDefaultButtonBarGapBorder()

Deprecated.

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

Returns:

this builder

addGlue

public ButtonBarBuilder2 addGlue()

Deprecated.

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 ButtonBarBuilder2 addRelatedGap()

Deprecated.

Description copied from class: AbstractButtonPanelBuilder

Adds the standard gap for related components.

Specified by:

addRelatedGap in class AbstractButtonPanelBuilder

addUnrelatedGap

public ButtonBarBuilder2 addUnrelatedGap()

Deprecated.

Description copied from class: AbstractButtonPanelBuilder

Adds the standard gap for unrelated components.

Specified by:

addUnrelatedGap in class AbstractButtonPanelBuilder

addStrut

public ButtonBarBuilder2 addStrut(ConstantSize width)

Deprecated.

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)

addButton

public ButtonBarBuilder2 addButton(JComponent button)

Deprecated.

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.

Specified by:

addButton in class AbstractButtonPanelBuilder

Parameters:

button - the component to add

Returns:

this builder

Throws:

NullPointerException - if button is null

addButton

public ButtonBarBuilder2 addButton(JComponent... buttons)

Deprecated.

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.

Overrides:

addButton in class AbstractButtonPanelBuilder

Parameters:

buttons - an array of buttons to add

Returns:

this builder

Throws:

NullPointerException - if the button array or a button is null

IllegalArgumentException - if the button array is empty

See Also:

addButton(JComponent)

addButton

public ButtonBarBuilder2 addButton(Action action)

Deprecated.

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

Returns:

this builder

Throws:

NullPointerException - if action is null

See Also:

addButton(JComponent)

addButton

public ButtonBarBuilder2 addButton(Action... actions)

Deprecated.

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

addGrowing

public ButtonBarBuilder2 addGrowing(JComponent component)

Deprecated.

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

Returns:

this builder

addGrowing

public ButtonBarBuilder2 addGrowing(JComponent... buttons)

Deprecated.

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

Returns:

this builder

See Also:

LayoutStyle

addFixed

public ButtonBarBuilder2 addFixed(JComponent component)

Deprecated.

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

Returns:

this builder