public final class DefaultFormBuilder extends I15dPanelBuilder
FormLayout
. This builder combines frequently used
panel building steps: add a new row, add a label, proceed to the next
data column, then add a component.
The extra value lies in the #append
methods that
append gap rows and component rows if necessary and then add
the given components. They are built upon the superclass behavior
#appendRow
and the set of #add
methods.
A set of component appenders allows to add a textual label and
associated component in a single step.
This builder can map resource keys to internationalized (i15d) texts
when creating text labels, titles and titled separators. Therefore
you must specify a ResourceBundle
in the constructor.
The builder methods throw an IllegalStateException
if one
of the mapping builder methods is invoked and no bundle has been set.
You can configure the build process by setting a leading column, enabling the row grouping and by modifying the gaps between normal lines and between paragraphs. The leading column will be honored if the cursor proceeds to the next row. All appended components start in the specified lead column, except appended separators that span all columns.
It is temptive to use the DefaultFormBuilder all the time and to let it add rows automatically. Use a simpler style if it increases the code readability. Explicit row specifications and cell constraints make your layout easier to understand - but harder to maintain. See also the accompanying tutorial sources and the Tips & Tricks that are part of the Forms documentation.
Sometimes a form consists of many standardized rows but has a few
rows that require a customization. The DefaultFormBuilder can do everything
that the superclasses AbstractFormBuilder
and PanelBuilder
can do;
among other things: appending new rows and moving the cursor.
Again, ask yourself if the DefaultFormBuilder is the appropriate builder.
As a rule of thumb you should have more components than builder commands.
There are different ways to add custom rows. Find below example code
that presents and compares the pros and cons of three approaches.
The texts for labels and titles can be marked texts,
i.e. strings with an optional mnemonic marker.
See the MnemonicUtils
class comment for details.
Example:
public void build() { FormLayout layout = new FormLayout( "right:max(40dlu;pref), 3dlu, 80dlu, 7dlu, " // 1st major colum + "right:max(40dlu;pref), 3dlu, 80dlu", // 2nd major column ""); // add rows dynamically DefaultFormBuilder builder = new DefaultFormBuilder(layout) .border(Borders.DIALOG); builder.appendSeparator("Flange"); builder.append("Identifier", identifierField); builder.nextLine(); builder.append("PTI [kW]", new JTextField()); builder.append("Power [kW]", new JTextField()); builder.append("s [mm]", new JTextField()); builder.nextLine(); builder.appendSeparator("Diameters"); builder.append("da [mm]", new JTextField()); builder.append("di [mm]", new JTextField()); builder.append("da2 [mm]", new JTextField()); builder.append("di2 [mm]", new JTextField()); builder.append("R [mm]", new JTextField()); builder.append("D [mm]", new JTextField()); builder.appendSeparator("Criteria"); builder.append("Location", buildLocationComboBox()); builder.append("k-factor", new JTextField()); builder.appendSeparator("Bolts"); builder.append("Material", ViewerUIFactory.buildMaterialComboBox()); builder.nextLine(); builder.append("Numbers", new JTextField()); builder.nextLine(); builder.append("ds [mm]", new JTextField()); }
Custom Row Example:
public JComponent buildPanel() { initComponents(); FormLayout layout = new FormLayout( "right:pref, 3dlu, default:grow", ""); DefaultFormBuilder builder = new DefaultFormBuilder(layout) .border(Borders.DIALOG) .rowGroupingEnabled(true); // In this approach, we add a gap and a custom row. // The advantage of this approach is, that we can express // the row spec and comment area cell constraints freely. // The disadvantage is the misalignment of the leading label. // Also the row's height may be inconsistent with other rows. builder.appendSeparator("Single Custom Row"); builder.append("Name", name1Field); builder.appendLineGapRow(); builder.appendRow(RowSpec.decode("top:31dlu")); // Assumes line is 14, gap is 3 builder.nextLine(2); builder.append("Comment"); builder.add(new JScrollPane(comment1Area), CC.xy(builder.getColumn(), builder.getRow(), "fill, fill")); builder.nextLine(); // In this approach, we append a standard row with gap before it. // The advantage is, that the leading label is aligned well. // The disadvantage is that the comment area now spans // multiple cells and is slightly less flexible. // Also the row's height may be inconsistent with other rows. builder.appendSeparator("Standard + Custom Row"); builder.append("Name", name2Field); builder.append("Comment"); builder.appendRow(RowSpec.decode("17dlu")); // Assumes line is 14, gap is 3 builder.add(new JScrollPane(comment2Area), CC.xywh(builder.getColumn(), builder.getRow(), 1, 2)); builder.nextLine(2); // In this approach, we append two standard rows with associated gaps. // The advantage is, that the leading label is aligned well, // and the height is consistent with other rows. // The disadvantage is that the comment area now spans // multiple cells and is slightly less flexible. builder.appendSeparator("Two Standard Rows"); builder.append("Name", name3Field); builder.append("Comment"); builder.nextLine(); builder.append(""); builder.nextRow(-2); builder.add(new JScrollPane(comment3Area), CC.xywh(builder.getColumn(), builder.getRow(), 1, 3)); return builder.build(); }
TODO: Consider adding a method for appending a component that spans the
remaining columns in the current row. Method name candidates are
#appendFullSpan
and #appendRemaining
.
AbstractFormBuilder
,
FormSpecs
,
FormLayout
currentCellConstraints
Constructor and Description |
---|
DefaultFormBuilder(FormLayout layout)
Constructs a
DefaultFormBuilder for the given
layout. |
DefaultFormBuilder(FormLayout layout,
JPanel container)
Constructs a
DefaultFormBuilder for the given
layout and panel. |
DefaultFormBuilder(FormLayout layout,
ResourceBundle bundle)
Constructs a
DefaultFormBuilder for the given
layout and resource bundle. |
DefaultFormBuilder(FormLayout layout,
ResourceBundle bundle,
JPanel container)
Constructs a
DefaultFormBuilder for the given
layout, resource bundle, and panel. |
DefaultFormBuilder(FormLayout layout,
com.jgoodies.common.internal.StringResourceAccessor localizer)
Constructs a
DefaultFormBuilder for the given
layout and resource bundle. |
DefaultFormBuilder(FormLayout layout,
com.jgoodies.common.internal.StringResourceAccessor localizer,
JPanel container)
Constructs a
DefaultFormBuilder for the given
layout, resource bundle, and panel. |
Modifier and Type | Method and Description |
---|---|
void |
append(Component component)
Adds a component to the panel using the default constraints
with a column span of 1.
|
void |
append(Component c1,
Component c2)
Adds two components to the panel; each component will span a single
data column.
|
void |
append(Component c1,
Component c2,
Component c3)
Adds three components to the panel; each component will span a single
data column.
|
void |
append(Component component,
int columnSpan)
Adds a component to the panel using the default constraints with
the given columnSpan.
|
JLabel |
append(String textWithMnemonic)
Adds a text label to the panel and proceeds to the next column.
|
JLabel |
append(String textWithMnemonic,
Component component)
Adds a text label and component to the panel.
|
JLabel |
append(String textWithMnemonic,
Component c,
boolean nextLine)
Adds a text label and component to the panel; the component will span
the specified number columns.
|
JLabel |
append(String textWithMnemonic,
Component c1,
Component c2)
Adds a text label and two components to the panel; each component
will span a single column.
|
JLabel |
append(String textWithMnemonic,
Component c1,
Component c2,
Component c3)
Adds a text label and three components to the panel; each component
will span a single column.
|
JLabel |
append(String textWithMnemonic,
Component c1,
Component c2,
Component c3,
Component c4)
Adds a text label and four components to the panel; each component
will span a single column.
|
JLabel |
append(String textWithMnemonic,
Component c1,
Component c2,
int colSpan)
Adds a text label and two components to the panel; each component
will span a single column.
|
JLabel |
append(String textWithMnemonic,
Component c,
int columnSpan)
Adds a text label and component to the panel; the component will span
the specified number columns.
|
JLabel |
appendI15d(String resourceKey)
Adds an internationalized (i15d) text label to the panel using
the given resource key and proceeds to the next column.
|
JLabel |
appendI15d(String resourceKey,
Component component)
Adds an internationalized (i15d) text label and component
to the panel.
|
JLabel |
appendI15d(String resourceKey,
Component component,
boolean nextLine)
Adds an internationalized (i15d) text label and component
to the panel.
|
JLabel |
appendI15d(String resourceKey,
Component c1,
Component c2)
Adds an internationalized (i15d) text label and two components
to the panel; each component will span a single column.
|
JLabel |
appendI15d(String resourceKey,
Component c1,
Component c2,
Component c3)
Adds an internationalized (i15d) text label and three components
to the panel; each component will span a single column.
|
JLabel |
appendI15d(String resourceKey,
Component c1,
Component c2,
Component c3,
Component c4)
Adds an internationalized (i15d) text label and four components
to the panel; each component will span a single column.
|
JLabel |
appendI15d(String resourceKey,
Component c1,
Component c2,
int colSpan)
Adds an internationalized (i15d) text label and two components
to the panel; each component will span a single column.
|
JLabel |
appendI15d(String resourceKey,
Component c,
int columnSpan)
Adds an internationalized (i15d) text label to the panel using
the given resource key; then proceeds to the next data column
and adds a component with the given column span.
|
JComponent |
appendI15dSeparator(String resourceKey)
Appends an internationalized titled separator for
the given resource key that spans all columns.
|
JLabel |
appendI15dTitle(String resourceKey)
Adds an internationalized title label to the panel and
proceeds to the next column.
|
void |
appendLineGapRow()
Appends a row with this builder's line gap size.
|
JComponent |
appendSeparator()
Adds a separator without text that spans all columns.
|
JComponent |
appendSeparator(String text)
Adds a separator with the given text that spans all columns.
|
JLabel |
appendTitle(String textWithMnemonic)
Adds a title label to the panel and proceeds to the next column.
|
DefaultFormBuilder |
background(Color background)
Sets the panel's background color and the panel to be opaque.
|
DefaultFormBuilder |
border(Border border)
Sets the panel's border.
|
DefaultFormBuilder |
border(String emptyBorderSpec)
Sets the panel's border as an EmptyBorder using the given specification
for the top, left, bottom, right in DLU.
|
DefaultFormBuilder |
defaultRowSpec(RowSpec defaultRowSpec)
Sets the row specification that shall be used for component rows.
|
RowSpec |
getDefaultRowSpec()
Deprecated.
Obsolete; will be deleted from the next version
|
protected int |
getLeadingColumn()
Returns the leading column.
|
int |
getLeadingColumnOffset()
Deprecated.
Obsolete; will be deleted from the next version
|
RowSpec |
getLineGapSpec()
Deprecated.
Obsolete; will be deleted from the next version
|
boolean |
isRowGroupingEnabled()
Deprecated.
Obsolete; will be deleted from the next version
|
DefaultFormBuilder |
leadingColumnOffset(int columnOffset)
Sets the offset of the leading column, often 0 or 1.
|
DefaultFormBuilder |
lineGapSize(ConstantSize lineGapSize)
Sets the size of gaps between component lines using the given
constant size.
|
DefaultFormBuilder |
opaque(boolean b)
Sets the panel's opaque state.
|
DefaultFormBuilder |
paragraphGapSize(ConstantSize paragraphGapSize)
Sets the size of gaps between paragraphs using the given
constant size.
|
DefaultFormBuilder |
rowGroupingEnabled(boolean enabled)
Enables or disables the grouping of new data rows.
|
void |
setDefaultRowSpec(RowSpec defaultRowSpec)
Deprecated.
Replaced by
defaultRowSpec(RowSpec) |
void |
setLeadingColumnOffset(int columnOffset)
Deprecated.
Replaced by
leadingColumnOffset(int) |
void |
setLineGapSize(ConstantSize lineGapSize)
Deprecated.
Replaced by
lineGapSize(ConstantSize) |
void |
setParagraphGapSize(ConstantSize paragraphGapSize)
Deprecated.
Replaced by
lineGapSize(ConstantSize) |
void |
setRowGroupingEnabled(boolean enabled)
Deprecated.
Replaced by
rowGroupingEnabled(boolean) |
addI15dLabel, addI15dLabel, addI15dLabel, addI15dROLabel, addI15dROLabel, addI15dROLabel, addI15dSeparator, addI15dSeparator, addI15dTitle, addI15dTitle, debugToolTipsEnabled, focusTraversal, getResourceString, isDebugToolTipsEnabled
add, add, addLabel, addLabel, addLabel, addLabel, addROLabel, addROLabel, addROLabel, addROLabel, addSeparator, addSeparator, addSeparator, addSeparator, addTitle, addTitle, addTitle, build, getPanel, isLabelForApplicable, labelForFeatureEnabled, setBorder, setDefaultDialogBorder, setLabelFor, setOpaque
add, add, appendColumn, appendColumn, appendGlueColumn, appendGlueRow, appendLabelComponentsGapColumn, appendParagraphGapRow, appendRelatedComponentsGapColumn, appendRelatedComponentsGapRow, appendRow, appendRow, appendUnrelatedComponentsGapColumn, appendUnrelatedComponentsGapRow, cellConstraints, createLeftAdjustedConstraints, getColumn, getColumnIncrementSign, getRow, isLeftToRight, nextColumn, nextColumn, nextLine, nextLine, nextRow, nextRow, setAlignment, setBounds, setColumn, setColumnSpan, setExtent, setHAlignment, setLeftToRight, setOrigin, setRow, setRowSpan, setVAlignment
createComponentFactory, getColumnCount, getComponentFactory, getContainer, getLayout, getRowCount, setComponentFactory
public DefaultFormBuilder(FormLayout layout)
DefaultFormBuilder
for the given
layout.layout
- the FormLayout
to be usedNullPointerException
- if layout
is null
public DefaultFormBuilder(FormLayout layout, JPanel container)
DefaultFormBuilder
for the given
layout and panel.layout
- the FormLayout
to be usedcontainer
- the layout containerNullPointerException
- if layout
or container
is null
public DefaultFormBuilder(FormLayout layout, ResourceBundle bundle)
DefaultFormBuilder
for the given
layout and resource bundle.layout
- the FormLayout
to be usedbundle
- the ResourceBundle
used to lookup i15d
stringsNullPointerException
- if layout
is null
public DefaultFormBuilder(FormLayout layout, ResourceBundle bundle, JPanel container)
DefaultFormBuilder
for the given
layout, resource bundle, and panel.layout
- the FormLayout
to be usedcontainer
- the layout containerbundle
- the ResourceBundle
used to lookup i15d
stringsNullPointerException
- if layout
or container
is null
public DefaultFormBuilder(FormLayout layout, com.jgoodies.common.internal.StringResourceAccessor localizer)
DefaultFormBuilder
for the given
layout and resource bundle.layout
- the FormLayout
to be usedlocalizer
- used to lookup i15d stringsNullPointerException
- if layout
is null
public DefaultFormBuilder(FormLayout layout, com.jgoodies.common.internal.StringResourceAccessor localizer, JPanel container)
DefaultFormBuilder
for the given
layout, resource bundle, and panel.layout
- the FormLayout
to be usedcontainer
- the layout containerlocalizer
- used to lookup i15d stringsNullPointerException
- if layout
or container
is null
public DefaultFormBuilder background(Color background)
PanelBuilder
background
in class I15dPanelBuilder
background
- the color to set as new backgroundJComponent.setBackground(Color)
public DefaultFormBuilder border(Border border)
PanelBuilder
border
in class I15dPanelBuilder
border
- the border to setJComponent.setBorder(Border)
public DefaultFormBuilder border(String emptyBorderSpec)
PanelBuilder
Equivalent to setBorder(Borders.createEmptyBorder(emptyBorderSpec))
.
border
in class I15dPanelBuilder
emptyBorderSpec
- describes the top, left, bottom, right sizes
of the EmptyBorder to createBorders.createEmptyBorder(String)
public DefaultFormBuilder opaque(boolean b)
PanelBuilder
opaque
in class I15dPanelBuilder
b
- true for opaque, false for non-opaqueJComponent.setOpaque(boolean)
public DefaultFormBuilder defaultRowSpec(RowSpec defaultRowSpec)
FormSpecs.PREF_ROWSPEC
by default.defaultRowSpec
- the RowSpec to be used for component rowspublic DefaultFormBuilder lineGapSize(ConstantSize lineGapSize)
Examples:
.lineGapSize(Sizes.ZERO); .lineGapSize(Sizes.DLUY9); .lineGapSize(Sizes.pixel(1));
lineGapSize
- the ConstantSize
that describes
the size of the gaps between component linespublic DefaultFormBuilder paragraphGapSize(ConstantSize paragraphGapSize)
Examples:
.setParagraphGapSize(Sizes.DLUY14); .setParagraphGapSize(Sizes.dluY(22)); .setParagraphGapSize(Sizes.pixel(42));
paragraphGapSize
- the ConstantSize
that describes
the size of the gaps between paragraphspublic DefaultFormBuilder leadingColumnOffset(int columnOffset)
columnOffset
- the new offset of the leading columnpublic DefaultFormBuilder rowGroupingEnabled(boolean enabled)
enabled
- indicates grouping enabled, false disabled@Deprecated public RowSpec getDefaultRowSpec()
RowSpec
used for component rows@Deprecated public void setDefaultRowSpec(RowSpec defaultRowSpec)
defaultRowSpec(RowSpec)
FormSpecs.PREF_ROWSPEC
by default.defaultRowSpec
- the RowSpec to be used for component rows@Deprecated public RowSpec getLineGapSpec()
RowSpec
that is used to separate component rows@Deprecated public void setLineGapSize(ConstantSize lineGapSize)
lineGapSize(ConstantSize)
Examples:
.setLineGapSize(Sizes.ZERO); .setLineGapSize(Sizes.DLUY9); .setLineGapSize(Sizes.pixel(1));
lineGapSize
- the ConstantSize
that describes
the size of the gaps between component lines@Deprecated public void setParagraphGapSize(ConstantSize paragraphGapSize)
lineGapSize(ConstantSize)
Examples:
.setParagraphGapSize(Sizes.DLUY14); .setParagraphGapSize(Sizes.dluY(22)); .setParagraphGapSize(Sizes.pixel(42));
paragraphGapSize
- the ConstantSize
that describes
the size of the gaps between paragraphs@Deprecated public int getLeadingColumnOffset()
@Deprecated public void setLeadingColumnOffset(int columnOffset)
leadingColumnOffset(int)
columnOffset
- the new offset of the leading column@Deprecated public boolean isRowGroupingEnabled()
@Deprecated public void setRowGroupingEnabled(boolean enabled)
rowGroupingEnabled(boolean)
enabled
- indicates grouping enabled, false disabledpublic final void appendLineGapRow()
public void append(Component component)
component
- the component to addpublic void append(Component component, int columnSpan)
component
- the component to appendcolumnSpan
- the column span used to addpublic void append(Component c1, Component c2)
c1
- the first component to addc2
- the second component to addpublic void append(Component c1, Component c2, Component c3)
c1
- the first component to addc2
- the second component to addc3
- the third component to addpublic JLabel append(String textWithMnemonic)
textWithMnemonic
- the label's text - may mark a mnemonicpublic JLabel append(String textWithMnemonic, Component component)
The created label is labeling the given component; so the component gets the focus if the (optional) label mnemonic is pressed.
textWithMnemonic
- the label's text - may mark a mnemoniccomponent
- the component to addpublic JLabel append(String textWithMnemonic, Component c, boolean nextLine)
The created label is labeling the given component; so the component gets the focus if the (optional) label mnemonic is pressed.
textWithMnemonic
- the label's text - may mark a mnemonicc
- the component to addnextLine
- true forces a next lineJLabel.setLabelFor(java.awt.Component)
public JLabel append(String textWithMnemonic, Component c, int columnSpan)
The created label is labeling the given component; so the component gets the focus if the (optional) label mnemonic is pressed.
textWithMnemonic
- the label's text - may mark a mnemonicc
- the component to addcolumnSpan
- number of columns the component shall spanJLabel.setLabelFor(java.awt.Component)
public JLabel append(String textWithMnemonic, Component c1, Component c2)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
textWithMnemonic
- the label's text - may mark a mnemonicc1
- the first component to addc2
- the second component to addpublic JLabel append(String textWithMnemonic, Component c1, Component c2, int colSpan)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
textWithMnemonic
- the label's text - may mark a mnemonicc1
- the first component to addc2
- the second component to addcolSpan
- the column span for the second componentpublic JLabel append(String textWithMnemonic, Component c1, Component c2, Component c3)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
textWithMnemonic
- the label's text - may mark a mnemonicc1
- the first component to addc2
- the second component to addc3
- the third component to addpublic JLabel append(String textWithMnemonic, Component c1, Component c2, Component c3, Component c4)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
textWithMnemonic
- the label's text - may mark a mnemonicc1
- the first component to addc2
- the second component to addc3
- the third component to addc4
- the fourth component to addpublic JLabel appendI15d(String resourceKey)
resourceKey
- the resource key for the the label's textpublic JLabel appendI15d(String resourceKey, Component component)
The created label is labeling the given component; so the component gets the focus if the (optional) label mnemonic is pressed.
resourceKey
- the resource key for the text to addcomponent
- the component to addpublic JLabel appendI15d(String resourceKey, Component component, boolean nextLine)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
resourceKey
- the resource key for the text to addcomponent
- the component to addnextLine
- true forces a next linepublic JLabel appendI15d(String resourceKey, Component c, int columnSpan)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
resourceKey
- the resource key for the text to addc
- the component to addcolumnSpan
- number of columns the component shall spanpublic JLabel appendI15d(String resourceKey, Component c1, Component c2)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
resourceKey
- the resource key for the text to addc1
- the first component to addc2
- the second component to addpublic JLabel appendI15d(String resourceKey, Component c1, Component c2, int colSpan)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
resourceKey
- the resource key for the text to addc1
- the first component to addc2
- the second component to addcolSpan
- the column span for the second componentpublic JLabel appendI15d(String resourceKey, Component c1, Component c2, Component c3)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
resourceKey
- the resource key for the text to addc1
- the first component to addc2
- the second component to addc3
- the third component to addpublic JLabel appendI15d(String resourceKey, Component c1, Component c2, Component c3, Component c4)
The created label is labeling the first component; so the component gets the focus if the (optional) label mnemonic is pressed.
resourceKey
- the resource key for the text to addc1
- the first component to addc2
- the second component to addc3
- the third component to addc4
- the third component to addpublic JLabel appendTitle(String textWithMnemonic)
textWithMnemonic
- the label's text - may mark a mnemonicpublic JLabel appendI15dTitle(String resourceKey)
resourceKey
- the resource key for the title's textpublic JComponent appendSeparator()
public JComponent appendSeparator(String text)
text
- the separator title textpublic JComponent appendI15dSeparator(String resourceKey)
resourceKey
- the resource key for the separator title's textprotected int getLeadingColumn()
getLeadingColumn
in class AbstractFormBuilder
Copyright © 2002-2014 JGoodies Software GmbH. All Rights Reserved.