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();
}
addButton
public void addButton(Action action)
action
- the action that describes the button to add
addButton
public void addButton(Action action1,
Action action2)
action1
- describes the first button to addaction2
- describes the second button to add
addButton
public void addButton(Action action1,
Action action2,
Action action3)
action1
- describes the first button to addaction2
- describes the second button to addaction3
- describes the third button to add
addButton
public void addButton(Action action1,
Action action2,
Action action3,
Action action4)
action1
- describes the first button to addaction2
- describes the second button to addaction3
- describes the third button to addaction4
- describes the fourth button to add
addButton
public void addButton(Action action1,
Action action2,
Action action3,
Action action4,
Action action5)
action1
- describes the first button to addaction2
- describes the second button to addaction3
- describes the third button to addaction4
- describes the fourth button to addaction5
- describes the fifth button to add
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.
actions
- the Actions that describe the buttons to add
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.
button
- the component to add
addButton
public void addButton(JComponent button1,
JComponent button2)
button1
- the first button to addbutton2
- the second button to add
addButton
public void addButton(JComponent button1,
JComponent button2,
JComponent button3)
button1
- the first button to addbutton2
- the second button to addbutton3
- the third button to add
addButton
public void addButton(JComponent button1,
JComponent button2,
JComponent button3,
JComponent button4)
button1
- the first button to addbutton2
- the second button to addbutton3
- the third button to addbutton4
- the fourth button to add
addButton
public void addButton(JComponent button1,
JComponent button2,
JComponent button3,
JComponent button4,
JComponent button5)
button1
- the first button to addbutton2
- the second button to addbutton3
- the third button to addbutton4
- the fourth button to addbutton5
- the fifth button to add
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.
buttons
- an array of buttons to add
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.
component
- the component to add
addGlue
public void addGlue()
Adds a glue that will be given the extra space,
if this button bar is larger than its preferred size.
addGrowing
public void addGrowing(JComponent component)
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.
buttons
- an array of buttons to add
addRelatedGap
public void addRelatedGap()
Adds the standard horizontal gap for related components.
addStrut
public void addStrut(ConstantSize width)
width
- describes the gap width
addUnrelatedGap
public void addUnrelatedGap()
Adds the standard horizontal gap for unrelated components.
createLeftToRightBuilder
public static ButtonBarBuilder2 createLeftToRightBuilder()
Creates and returns a ButtonBarBuilder2 with
a left to right button order.
- 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.
- true if button sequences are ordered from left to right
setDefaultButtonBarGapBorder
public void setDefaultButtonBarGapBorder()
Sets a default border that has a gap in the bar's north.
setLeftToRightButtonOrder
public void setLeftToRightButtonOrder(boolean newButtonOrder)
Sets the order for button sequences to either left to right,
or right to left.
newButtonOrder
- true if button sequences shall be ordered
from left to right