com.jgoodies.forms.builder
Class ButtonBarBuilder

java.lang.Object
  com.jgoodies.forms.builder.AbstractFormBuilder
      com.jgoodies.forms.builder.PanelBuilder
          com.jgoodies.forms.builder.ButtonBarBuilder

public final class ButtonBarBuilder
extends PanelBuilder

A non-visual builder that assists you in building consistent button bars that comply with popular UI style guides. It utilizes the FormLayout. This class is in turn used by the ButtonBarFactory that provides an even higher level of abstraction for building consistent button bars.

Buttons added to the builder are either gridded or fixed and may fill their FormLayout cell or not. All gridded buttons get the same width, while fixed buttons use their own size. Gridded buttons honor the default minimum button width as specified by the current LayoutStyle.

You can set an optional hint for narrow margin for the fixed width buttons. This is useful if you want to lay out a button bar that includes a button with a long text. For example, in a bar with 'Copy to Clipboard', 'OK', 'Cancel' you may declare the clipboard button as a fixed size button with narrow margins, OK and Cancel as gridded. Gridded buttons are marked as narrow by default. 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.

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. addGriddedButtons(JButton[]) honor the button order. If you want to ignore the default button order, you can either add add individual buttons, or create a ButtonBarBuilder 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) {
     ButtonBarBuilder builder = new ButtonBarBuilder();
     builder.addGridded(help);
     builder.addRelatedGap();
     builder.addGlue();
     builder.addGriddedButtons(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 ButtonBarBuilder()));
     rowBuilder.append(buildButtonSequence(ButtonBarBuilder.createLeftToRightBuilder()));
     rowBuilder.append(buildIndividualButtons(new ButtonBarBuilder()));

     return rowBuilder.getPanel();
 }

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

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

Version:

$Revision: 55293 $

Author:

Karsten Lentzsch

See Also:

ButtonStackBuilder, ButtonBarFactory, LayoutStyle

Field Summary

private static ColumnSpec[]	COL_SPECS Specifies the columns of the initial FormLayout used in constructors.
private boolean	leftToRight Describes how sequences of buttons are added to the button bar: left-to-right or right-to-left.
private static java.lang.String	NARROW_KEY The client property key used to indicate that a button shall get narrow margins on the left and right hand side.
private static RowSpec[]	ROW_SPECS Specifies the FormLayout's the single button bar row.

Constructor Summary

ButtonBarBuilder()
Constructs an instance of ButtonBarBuilder on a JPanel using a preconfigured FormLayout as layout manager.

ButtonBarBuilder(javax.swing.JPanel panel)
Constructs an instance of ButtonBarBuilder on the given panel using a preconfigured FormLayout as layout manager.

Method Summary

void	addFixed(javax.swing.JComponent component) Adds a fixed size component.
void	addFixedNarrow(javax.swing.JComponent component) Adds a fixed size component with narrow margins.
void	addGlue() Adds a glue that will be given the extra space, if this box is larger than its preferred size.
void	addGridded(javax.swing.JComponent component) Adds a gridded component, i.e. a component that will get the same dimension as all other gridded components.
void	addGriddedButtons(javax.swing.JButton[] buttons) Adds a sequence of related gridded buttons each separated by a default gap.
void	addGriddedGrowing(javax.swing.JComponent component) Adds a gridded component that grows.
void	addGriddedGrowingButtons(javax.swing.JButton[] buttons) Adds a sequence of gridded buttons that grow where each is separated by a default gap.
void	addRelatedGap() Adds the standard gap for related components.
void	addStrut(ConstantSize size) Adds a strut of a specified size.
void	addUnrelatedGap() Adds the standard gap for unrelated components.
static ButtonBarBuilder	createLeftToRightBuilder() Creates and returns a ButtonBarBuilder with initialized 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.PanelBuilder

add, addLabel, addLabel, addLabel, addLabel, addSeparator, addSeparator, addSeparator, addSeparator, addTitle, addTitle, addTitle, getComponentFactory, getPanel, setBorder, setComponentFactory, setDefaultDialogBorder

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

add, add, add, appendColumn, appendColumn, appendGlueColumn, appendGlueRow, appendLabelComponentsGapColumn, appendParagraphGapRow, appendRelatedComponentsGapColumn, appendRelatedComponentsGapRow, appendRow, appendRow, appendUnrelatedComponentsGapColumn, appendUnrelatedComponentsGapRow, cellConstraints, createLeftAdjustedConstraints, getColumn, getColumnCount, getColumnIncrementSign, getContainer, getLayout, getLeadingColumn, getRow, getRowCount, isLeftToRight, nextColumn, nextColumn, nextLine, nextLine, nextRow, nextRow, setAlignment, setBounds, setColumn, setColumnSpan, setExtent, setHAlignment, setLeftToRight, setOrigin, setRow, setRowSpan, setVAlignment

Methods inherited from class java.lang.Object

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

Field Detail

COL_SPECS

private static final ColumnSpec[] COL_SPECS

Specifies the columns of the initial FormLayout used in constructors.

ROW_SPECS

private static final RowSpec[] ROW_SPECS

Specifies the FormLayout's the single button bar row.

NARROW_KEY

private static final java.lang.String NARROW_KEY

The client property key used to indicate that a button shall get narrow margins on the left and right hand side.

This optional setting will be honored by all JGoodies Look&Feel implementations. The Mac Aqua l&f uses narrow margins only. Other look&feel implementations will likely ignore this key and so may render a wider button margin.

See Also:

Constant Field Values

leftToRight

private boolean leftToRight

Describes how sequences of buttons are added to the button bar: left-to-right or right-to-left. This setting is initialized using the current LayoutStyle's button order. It is honored only by builder methods that build sequences of button, for example addGriddedButtons(JButton[]), and ignored if you add individual button, for example using addGridded(JComponent).

See Also:

AbstractFormBuilder.isLeftToRight(), AbstractFormBuilder.setLeftToRight(boolean), addGriddedButtons(JButton[]), addGriddedGrowingButtons(JButton[])

Constructor Detail

ButtonBarBuilder

public ButtonBarBuilder()

Constructs an instance of ButtonBarBuilder on a JPanel using a preconfigured FormLayout as layout manager.

ButtonBarBuilder

public ButtonBarBuilder(javax.swing.JPanel panel)

Constructs an instance of ButtonBarBuilder on the given panel using a preconfigured FormLayout as layout manager.

Parameters:

panel - the layout container

Method Detail

createLeftToRightBuilder

public static ButtonBarBuilder createLeftToRightBuilder()

Creates and returns a ButtonBarBuilder with initialized 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

Since:

1.0.3

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

Since:

1.0.3

See Also:

LayoutStyle.isLeftToRightButtonOrder()

setDefaultButtonBarGapBorder

public void setDefaultButtonBarGapBorder()

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

addGriddedButtons

public void addGriddedButtons(javax.swing.JButton[] buttons)

Adds a sequence of related gridded buttons each 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

addGriddedGrowingButtons

public void addGriddedGrowingButtons(javax.swing.JButton[] buttons)

Adds a sequence of gridded buttons that grow 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(javax.swing.JComponent component)

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

Parameters:

component - the component to add

addFixedNarrow

public void addFixedNarrow(javax.swing.JComponent component)

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

Parameters:

component - the component to add

addGridded

public void addGridded(javax.swing.JComponent component)

Adds a gridded component, i.e. a component that will get the same dimension as all other gridded components.

Parameters:

component - the component to add

addGriddedGrowing

public void addGriddedGrowing(javax.swing.JComponent component)

Adds a gridded component that grows. The component's initial size (before it grows) is the same as for all other gridded components.

Parameters:

component - the component to add

addGlue

public void addGlue()

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

addRelatedGap

public void addRelatedGap()

Adds the standard gap for related components.

addUnrelatedGap

public void addUnrelatedGap()

Adds the standard gap for unrelated components.

addStrut

public void addStrut(ConstantSize size)

Adds a strut of a specified size.

Parameters:

size - a ConstantSize that describes the gap's size