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.
Note: Since the Forms 1.2, it is recommended to use
the
ButtonBarBuilder2
that comes with a smaller, safer, better,
and more convenient API. The ButtonBarBuilder will be marked as deprecated
in the Forms 2.0.
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 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.addUnrelatedGap();
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();
}
addFixed
public void addFixed(JComponent component)
Adds a fixed size component. Unlike the gridded components,
this component keeps its individual preferred dimension.
component
- the component to add
addFixedNarrow
public void addFixedNarrow(JComponent component)
Adds a fixed size component with narrow margins. 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 box is larger than its preferred size.
addGridded
public void addGridded(JComponent component)
Adds a gridded component, i.e. a component that will get
the same dimension as all other gridded components.
component
- the component to add
addGriddedButtons
public void addGriddedButtons(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.
buttons
- an array of buttons to add
addGriddedGrowing
public void addGriddedGrowing(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.
component
- the component to add
addGriddedGrowingButtons
public void addGriddedGrowingButtons(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.
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 ButtonBarBuilder createLeftToRightBuilder()
Creates and returns a ButtonBarBuilder
with
initialized 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