Class FormBuilder
FormLayout
to lay out and populate JPanel
s. It provides the following features:
- Short code, good readability.
- Layout and panel building in a single class.
- Layout construction easier to understand (compared to FormLayout constructors).
- Implicitly creates frequently used components such as labels.
- Convenience code for adding button bars, radio button groups, etc.
- Can add components only if a condition evaluates to
true
. - Toolkit-independent code, see
focusTraversalType
vs.focusTraversalPolicy
.
The FormBuilder is the working horse
for forms and panels where more specialized builders such as the
ListViewBuilder
or the ButtonBarBuilder
are inappropriate.
Since FormBuilder supports the frequently used methods for setting up
and configuring a FormLayout, the vast majority of forms can be built
with just the FormBuilder. In other words, you will typically not
work with FormLayout instances directly.
Forms are built as a two-step process: first, you setup and configure the layout, then add the components.
Example: (creates a panel with 3 columns and 3 rows)
return FormBuilder.create() .columns("left:pref, $lcgap, 50dlu, $rgap, default") .rows("p, $lg, p, $lg, p") .padding(Paddings.DIALOG) .add("invalid input: '&Title':") .xy (1, 1) .add(titleField) .xywh(3, 1, 3, 1) .add("invalid input: '&Price':") .xy (1, 3) .add(priceField) .xy (3, 3) .add("invalid input: '&Author':") .xy (1, 5) .add(authorField) .xy (3, 5) .add(browseButton).xy (5, 5) .build();FormBuilder provides convenience methods for adding labels, titles, and titled separators. These components will be created by the builder's component factory that can be set via
factory(ComponentFactory)
,
and that is by default initialized from
FormsSetup.getComponentFactoryDefault()
.
The text arguments passed to the methods #addLabel
,
#addTitle
, and #addSeparator
can contain
an optional mnemonic marker. The mnemonic and mnemonic index
are indicated by a single ampersand (&). For example
"&Saveinvalid input: '"', or "Save &asinvalid input: '"'.
To use the ampersand itself duplicate it, for example
"Look&&Feelinvalid input: '"'.
Feature Overview:
.columns("pref, $lcgap, %sdlu, p, p", "50") // Format string
.columnGroup(4, 5) // Grouping short hand
.debug(true) // Installs FormDebugPanel
.add("Title:") .xy(1, 1) // Implicitly created label
.add("invalid input: '&Price':") .xy(1, 1) // Label with mnemonic
.add(hasCountry, combo).xy(3, 1) // Conditional adding
.add(aTable) .xywh(1, 1, 3, 5) // Auto-wrapped with scrollpane
.addScrolled(aTextArea).xywh(1, 1, 1, 3) // scrollpane shorthand
.addBar(newBtn, editBtn, deleteBtn).xy(1, 5) // button bar
.addBar(landscapeRadio, portraitRadio).xy(1, 1) // Radio button bar
- Since:
- 1.9
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
static interface
Describes a view that can be integrated into an existing form usingadd(FormBuildingView)
.static enum
private static final class
static final class
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate ColumnSpec[]
private boolean
private FormBuilder.LabelType
private ComponentFactory
private FocusTraversalPolicy
private FocusTraversalType
private JComponent
private static final String
A JComponent client property that is used to determine the label labeling a component.private boolean
The instance value for the setLabelFor feature.private FormLayout
private LayoutMap
private WeakReference
Refers to the most recently added label.private int
private int
private JPanel
private RowSpec[]
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionadd
(boolean expression, FormBuilder.FormBuildingView view) Builds the given view into this FormBuilder's form, ifexpression
istrue
.The first of two steps for conditionally adding a component to the form.The first of two steps for conditionally adding a textual label to the form.The first of two steps for conditionally adding an icon label to the form.Builds the given view into this FormBuilder's form.The first of two steps for adding a component to this builder's panel.The first of two steps for adding a textual label to the form.The first of two steps for adding an icon label to the form.The first of two steps for conditionally adding a button bar to the form.The first of two steps for conditionally adding a check box bar to the form.addBar
(boolean expression, JRadioButton... radioButtons) The first of two steps for conditionally adding a radio button bar to this builder's panel.The first of two steps for adding a button bar to this builder's panel.The first of two steps for adding a check box bar to this builder's panel.addBar
(JRadioButton... radioButtons) The first of two steps for adding a radio button bar to this builder's panel.protected FormBuilder.ComponentAdder
(package private) void
addImpl
(Component component, CellConstraints rawConstraints) The first of two steps for conditionally adding a plain label to the form.The first of two steps for adding a plain label to the form.The first of two steps for conditionally adding a component to the form.The first of two steps for adding a component to this builder's panel.addROLabel
(boolean expression, String markedText, Object... args) The first of two steps for conditionally adding a textual label to the form that is intended for labeling read-only components.addROLabel
(String markedText, Object... args) The first of two steps for adding a textual label to the form that is intended for labeling read-only components.addScrolled
(boolean expression, Component c) The first of two steps for conditionally adding the given component wrapped with a JScrollPane to this builder's panel.The first of two steps for adding the given component wrapped with a JScrollPane to this builder's panel.addSeparator
(boolean expression, String markedText, Object... args) The first of two steps for conditionally adding a titled separator to the form.addSeparator
(String markedText, Object... args) The first of two steps for adding a titled separator to the form.The first of two steps for conditionally adding a button stack to this builder's panel.The first of two steps for conditionally adding a check box stack to this builder's panel.addStack
(boolean expression, JRadioButton... radioButtons) The first of two steps for conditionally adding a radio button stack to this builder's panel.The first of two steps for adding a button stack to this builder's panel.The first of two steps for adding a check box stack to this builder's panel.addStack
(JRadioButton... radioButtons) The first of two steps for adding a radio button stack to this builder's panel.The first of two steps for conditionally adding a title label to the form.The first of two steps for adding a title label to the form.appendColumns
(String encodedColumnSpecs, Object... args) Appends the given columns to this builder's layout.appendRows
(String encodedRowSpecs, Object... args) Appends the given rows to this builder's layout.background
(Color background) Sets the panel's background color and the panel to be opaque.Deprecated.Sets the panel's border.build()
Returns the panel used to build the form.private void
Checks that if the API user has set a focus traversal policy, no focus traversal type and no initial component has been set.private void
Clears the reference to the most recently added mnemonic label.columnGroup
(int... columnIndices) Configures this builder's layout to group (make equally wide) the columns with the given indices.columnGroups
(int[]... multipleColumnGroups) Configures this builder's layout to group (make equally wide) the columns per array of column indices.Configures this builder's layout columns using a comma-separated string of column specifications.static FormBuilder
create()
Creates and return a new FormBuilder instance.debug
(boolean b) Enables or disables the display of layout debug information.defaultLabelType
(FormBuilder.LabelType newValue) Sets a new value for the default label type that is used to determine whetheradd(String, Object...)
delegates toaddLabel(String, Object...)
oraddROLabel(String, Object...)
.factory
(ComponentFactory factory) Setsfactory
as this builder's new component factory that is used when adding implicitly created components such as labels, titles, or titled separators.focusGroup
(AbstractButton... buttons) Tries to build a focus group for the given buttons.Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider.focusTraversalType
(FocusTraversalType focusTraversalType) Sets either a layout or container order focus traversal policy.protected ComponentFactory
protected FormLayout
protected LayoutMap
private JLabel
Returns the most recently added JLabel that has a mnemonic set - if any,null
, if none has been set, or if it has been cleared after setting an association before, or if it has been cleared by the garbage collector.getPanel()
Returns the panel used to build the form.honorsVisibility
(boolean b) Specifies whether invisible components shall be taken into account by this builder for computing the layout size and setting component bounds.honorsVisibility
(JComponent c, boolean b) Configures how this builder's layout shall handle the visibility of the given component.initialComponent
(JComponent initialComponent) Sets a component that should receive the focus when a Window is made visible for the first time.private static boolean
isLabelForApplicable
(JLabel label, Component component) Checks and answers whether the given component shall be set as component for a previously added label usingJLabel.setLabelFor(Component)
.private boolean
labelForFeatureEnabled
(boolean b) Enables or disables the setLabelFor feature for this builder.layout
(FormLayout layout) Setslayout
as the layout to use by this builder.Configures this builder's FormLayout to use the given layout map for expanding layout variables.private void
Sets the name of the panel this builder works with.offset
(int offsetX, int offsetY) When adding components, the cell constraints origin are moved along the X and Y axis using an offset as specified byoffsetX
andoffsetY
respectively.opaque
(boolean b) Sets the panel's opaque state.Sets the panel's padding as an EmptyBorder using the given specification for the top, left, bottom, right margins in DLU.padding
(EmptyBorder padding) Sets the panel's padding, an empty border.Setspanel
as the panel that this builder shall work with.rowGroup
(int... rowIndices) Configures this builder's layout to group (make equally high) the rows with the given indices.rowGroups
(int[]... multipleRowGroups) Configures this builder's layout to group (make equally wide) the rows per array of row indices.Configures this builder's layout rows using a comma-separated string of row specifications.The string can be a format string and will then use the optional format arguments, seeString.format(String, Object...)
.private static void
setLabelFor
(JLabel label, Component component) Setslabel
as labeling label forcomponent
or an appropriate child.private void
setMostRecentlyAddedLabel
(JLabel label) Sets the given label as most recently added label using a weak reference.private void
translate
(int dX, int dY) Moves the cell constraints offset along the X and Y axis as specified bydx
anddy
respectively.
-
Field Details
-
LABELED_BY_PROPERTY
A JComponent client property that is used to determine the label labeling a component. Copied from the JLabel class.- See Also:
-
layoutMap
-
columnSpecs
-
rowSpecs
-
layout
-
panel
-
initialComponent
-
focusTraversalType
-
focusTraversalPolicy
-
debug
private boolean debug -
offsetX
private int offsetX -
offsetY
private int offsetY -
labelForFeatureEnabled
private boolean labelForFeatureEnabledThe instance value for the setLabelFor feature. Is initialized using the global default.- See Also:
-
defaultLabelType
-
factory
-
mostRecentlyAddedLabelReference
Refers to the most recently added label. Used to invokeJLabel.setLabelFor(java.awt.Component)
for the next component added to the panel that is applicable for this feature (for example focusable). After the association has been set, the reference will be cleared.- See Also:
-
-
Constructor Details
-
FormBuilder
protected FormBuilder()
-
-
Method Details
-
create
Creates and return a new FormBuilder instance. -
build
Returns the panel used to build the form. Intended to return the panel in build methods.- Returns:
- the panel used by this builder to build the form
-
layoutMap
Configures this builder's FormLayout to use the given layout map for expanding layout variables.Example:
return FormBuilder.create() .columns("left:pref, $lcgap, 200dlu") .rows("p, $lg, p, $lg, p") .layoutMap(aCustomLayoutMap) ...
- Parameters:
layoutMap
- expands layout column and row variables- Returns:
- a reference to this builder
-
columns
Configures this builder's layout columns using a comma-separated string of column specifications. The string can be a format string and will then use the optional format arguments, seeString.format(String, Object...)
.Examples:
.columns("left:90dlu, 3dlu, 200dlu") .columns("left:90dlu, 3dlu, %sdlu", "200") // Format string .columns("$label, $lcgap, 200dlu") // Layout variables
- Parameters:
encodedColumnSpecs
- a comma-separated list of column specificationsargs
- optional format arguments- Returns:
- a reference to this builder
- See Also:
-
appendColumns
Appends the given columns to this builder's layout. The columns to append are provided as a comma-separated string of column specifications. The string can be a format string and will then use the optional format arguments, seeString.format(String, Object...)
.Examples:
.appendColumns("50dlu, 3dlu, 50dlu") .appendColumns("%sdlu, 3dlu, %sdlu", "50") // Format string .appendColumns("$button, $rgap, $button") // Layout variable
- Parameters:
encodedColumnSpecs
- a comma-separated list of column specificationsargs
- optional format arguments- Returns:
- a reference to this builder
- See Also:
-
rows
Configures this builder's layout rows using a comma-separated string of row specifications.The string can be a format string and will then use the optional format arguments, seeString.format(String, Object...)
.Examples:
.rows("p, 3dlu, p, 14dlu, p") .rows("p, 3dlu, p, %sdlu, p", "14") // Format string .rows("p, $pg, p, $pg, p") // Layout variables
- Parameters:
encodedRowSpecs
- a comma-separated list of row specificationsargs
- optional format arguments- Returns:
- a reference to this builder
- See Also:
-
appendRows
Appends the given rows to this builder's layout. The rows to append are provided as a comma-separated string of row specifications. The string can be a format string and will then use the optional format arguments, seeString.format(String, Object...)
.Examples:
.appendRows("10dlu, p, 3dlu, p") .appendRows("%sdlu, p, 3dlu, p", "10") // Format string .appendRows("10dlu, p, $lg, p") // Layout variable
- Parameters:
encodedRowSpecs
- a comma-separated list of row specificationsargs
- optional format arguments- Returns:
- a reference to this builder
- See Also:
-
columnGroup
Configures this builder's layout to group (make equally wide) the columns with the given indices.Examples:
.columnGroup(3, 5)
- Parameters:
columnIndices
- the indices of the columns to group- Returns:
- a reference to this builder
-
columnGroups
Configures this builder's layout to group (make equally wide) the columns per array of column indices.Examples:
.columnGroups(new int[]{3, 5}, new int[]{7, 9})
- Parameters:
multipleColumnGroups
- multiple arrays of column indices- Returns:
- a reference to this builder
-
rowGroup
Configures this builder's layout to group (make equally high) the rows with the given indices.Examples:
.rowGroup(3, 5)
- Parameters:
rowIndices
- the indices of the rows to group- Returns:
- a reference to this builder
-
rowGroups
Configures this builder's layout to group (make equally wide) the rows per array of row indices.Examples:
.rowGroups(new int[]{3, 5}, new int[]{7, 9})
- Parameters:
multipleRowGroups
- multiple arrays of row indices- Returns:
- a reference to this builder
-
honorsVisibility
Specifies whether invisible components shall be taken into account by this builder for computing the layout size and setting component bounds. If set totrue
invisible components will be ignored by the layout. If set tofalse
components will be taken into account regardless of their visibility. Visible components are always used for sizing and positioning.The default value for this setting is
true
. It is useful to set the value tofalse
(in other words to ignore the visibility) if you switch the component visibility dynamically and want the container to retain the size and component positions.- Parameters:
b
-true
to honor the visibility, i.e. to exclude invisible components from the sizing and positioning,false
to ignore the visibility, in other words to layout visible and invisible components- Returns:
- a reference to this builder
- See Also:
-
honorsVisibility
Configures how this builder's layout shall handle the visibility of the given component.- Parameters:
c
- the component to configureb
-true
to usec
for layout computations only if visible,false
to takec
into account even if invisible- Returns:
- a reference to this builder
- See Also:
-
layout
Setslayout
as the layout to use by this builder.- Parameters:
layout
- the layout to be used by this builder- Returns:
- a reference to this builder
-
panel
Setspanel
as the panel that this builder shall work with.- Parameters:
panel
- the panel to work with- Returns:
- a reference to this builder
-
debug
Enables or disables the display of layout debug information. If enabled, the layout grid lines will be painted with red lines. By default the debug mode is disabled.- Parameters:
b
-true
to paint grid lines,false
to disable it- Returns:
- a reference to this builder
- See Also:
-
name
Sets the name of the panel this builder works with.- Parameters:
panelName
- the name to set- Returns:
- a reference to this builder
-
background
Sets the panel's background color and the panel to be opaque.- Parameters:
background
- the color to set as new background- Returns:
- a reference to this builder
- See Also:
-
border
Sets the panel's border. If you just want to wrap a panel with white space, usepadding(EmptyBorder)
instead.- Parameters:
border
- the border to set- Returns:
- a reference to this builder
- See Also:
-
border
Deprecated.Usepadding(String, Object...)
insteadSets the panel's padding as an EmptyBorder using the given specification for the top, left, bottom, right margins in DLU. For example "1dlu, 2dlu, 3dlu, 4dlu" sets a padding with 1dlu in the top, 2dlu in the left side, 3dlu at the bottom, and 4dlu in the right hand side.Equivalent to
setPadding(Paddings.createPadding(paddingSpec))
.- Parameters:
paddingSpec
- describes the top, left, bottom, right margins of the padding (an EmptyBorder) to use- Returns:
- a reference to this builder
- See Also:
-
padding
Sets the panel's padding, an empty border.- Parameters:
padding
- the white space around this form- Returns:
- a reference to this builder
- Since:
- 1.9
- See Also:
-
padding
Sets the panel's padding as an EmptyBorder using the given specification for the top, left, bottom, right margins in DLU. For example "1dlu, 2dlu, 3dlu, 4dlu" sets an empty border with 1dlu in the top, 2dlu in the left side, 3dlu at the bottom, and 4dlu in the right hand side.Equivalent to
padding(Paddings.createPadding(paddingSpec, args))
.- Parameters:
paddingSpec
- describes the top, left, bottom, right margins of the padding (an EmptyBorder) to useargs
- optional format arguments, used ifpaddingSpec
is a format string- Returns:
- a reference to this builder
- Since:
- 1.9
- See Also:
-
opaque
Sets the panel's opaque state.- Parameters:
b
- true for opaque, false for non-opaque- Returns:
- a reference to this builder
- See Also:
-
initialComponent
Sets a component that should receive the focus when a Window is made visible for the first time. For details seeFocusTraversalPolicy.getInitialComponent(java.awt.Window)
.- Parameters:
initialComponent
- the component that shall receive the focus- Returns:
- a reference to this builder
-
focusTraversalType
Sets either a layout or container order focus traversal policy. If the commercialJGContainerOrderFocusTraversalPolicy
andJGLayoutFocusTraversalPolicy
are in the class path, these will be used. Otherwise the standard SwingContainerOrderFocusTraversalPolicy
andLayoutFocusTraversalPolicy
respectively will be used.- Parameters:
focusTraversalType
- specifies the type: layout or container order- Returns:
- a reference to this builder
- Throws:
NullPointerException
- iffocusTraversalType
isnull
- See Also:
-
focusTraversalPolicy
Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider. You should favor setting the focus traversal policy type over setting a concrete policy, because the type is toolkit-independent and may be reused if your code is transferred to another toolkit.A call to this method is only necessary, if you set a custom Swing focus traversal policy other than
LayoutFocusTraversalPolicy
orContainerOrderFocusTraversalPolicy
(or their commercial replacementsJGLayoutFocusTraversalPolicy
orJGContainerOrderFocusTraversalPolicy
).Call to this method are equivalent to:
builder.getPanel().setFocusTraversalPolicy(policy); builder.getPanel().setFocusTraversalPolicyProvider(true);
- Parameters:
policy
- the focus traversal policy that will manage keyboard traversal of the children in this builder's panel- Returns:
- a reference to this builder
- Throws:
NullPointerException
- iffocusTraversalType
isnull
- See Also:
-
focusGroup
Tries to build a focus group for the given buttons. Within a focus group, focus can be transferred from one group member to another using the arrow keys.To succeed, the commercial
FocusTraversalUtils
class must be in the class path. To make focus grouping work, a focus traversal policy must be set that is capable of transferring focus with the arrow keys such asJGContainerOrderFocusTraversalPolicy
orJGLayoutFocusTraversalPolicy
.- Parameters:
buttons
- the buttons to be grouped- Returns:
- a reference to this builder
-
getPanel
Returns the panel used to build the form. Intended to access panel properties. For returning the built panel usebuild()
instead.- Returns:
- the panel used by this builder to build the form
- See Also:
-
factory
Setsfactory
as this builder's new component factory that is used when adding implicitly created components such as labels, titles, or titled separators. If not called, the default factory will be used that can be configured viaFormsSetup.setComponentFactoryDefault(ComponentFactory)
.- Parameters:
factory
- the factory to be used to create components- Returns:
- a reference to this builder
-
labelForFeatureEnabled
Enables or disables the setLabelFor feature for this builder. If enabled, a label that has just been added by this builder will be set as the label for the next component added by this builder.The value is initialized from the global default value
FormsSetup.getLabelForFeatureEnabledDefault()
. It is globally disabled by default.- Parameters:
b
-true
for enabled,false
for disabled- Returns:
- a reference to this builder
- See Also:
-
offset
When adding components, the cell constraints origin are moved along the X and Y axis using an offset as specified byoffsetX
andoffsetY
respectively.This operation is not cumulative. In other words, setting the offset overrides the previously set offset. For example:
builder .offset(0, 2) .offset(1, 3) .offset(4, 8)
ends with an offset of (4, 8).- Parameters:
offsetX
- the distance to move cell constraints along the X axisoffsetY
- the distance to move cell constraints along the Y axis- Returns:
- a reference to this builder
- See Also:
-
translate
Moves the cell constraints offset along the X and Y axis as specified bydx
anddy
respectively.This operation is cumulative for the offset. In other words, every translation is added to all previously set translations. For example:
builder .offset(0, 0) .translate(0, 2) .translate(1, 3) .translate(4, 8)
ends with an offset of (5, 13).- Parameters:
dX
- the distance to move the offset along the X axisdY
- the distance to move the offset along the Y axis- Returns:
- a reference to this builder
- See Also:
-
defaultLabelType
Sets a new value for the default label type that is used to determine whetheradd(String, Object...)
delegates toaddLabel(String, Object...)
oraddROLabel(String, Object...)
.- Parameters:
newValue
- the default label type- Returns:
- a reference to this builder
-
add
The first of two steps for adding a component to this builder's panel. This component will be added, once the cell constraints are specified.JTables, JLists, and JTrees will be automatically wrapped by a default JScrollPane. If no scroll pane is desired, use
addRaw(Component)
instead. If a scroll pane is desired for other components (frequent case are JTextAreas) useaddScrolled(Component)
.return FormBuilder.create() ... .add(nameField) .xy(1, 1) .add(countryCombo).xy(3, 3) ... .build();
If the label-for-feature is enabled, the most recently added label is tracked and associated with the next added component that is applicable for being set as component for the label.- Parameters:
c
- the component to add; will be wrapped if it is an instance of JTable, JList, or JTree- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addRaw
The first of two steps for adding a component to this builder's panel. This component will be added, once the cell constraints are specified.Unlike
add(Component)
, this method won't wrap JTables, JLists, and JTrees automatically with a JScrollPane. Useful for tables, list, and trees that either need no scroll pane, or have another kind of decoration.return FormBuilder.create() ... .addRaw(aTreeThatNeedsNoScrollPane).xy(1, 1) ... .build();
If the label-for-feature is enabled, the most recently added label is tracked and associated with the next added component that is applicable for being set as component for the label.- Parameters:
c
- the component to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addScrolled
The first of two steps for adding the given component wrapped with a JScrollPane to this builder's panel. The wrapped component will be added once the cell constraints have been specified. A frequent case for this method are JTextAreas that shall be scrolled.The layout is equivalent to:
return FormBuilder.create() ... .add(new JScrollPane(c)).xy(..., ...) ... .build();
- Parameters:
c
- the component to be wrapped and added- Returns:
- the fluent interface part used to set the cell constraints
-
addBar
The first of two steps for adding a button bar to this builder's panel. This bar will be added, once the cell constraints are specified.The buttons will be laid out horizontally in a subpanel, where all buttons use the platform's minimum width. If focus grouping is possible, focus can be transferred between buttons using the arrow keys.
return FormBuilder.create() ... .addBar(newButton, editButton, deleteButton).xy(1, 9) ... .build();
- Parameters:
buttons
- the buttons to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addBar
The first of two steps for adding a check box bar to this builder's panel. This bar will be added, once the cell constraints are specified.The check boxes will be laid out as a row in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys.
return FormBuilder.create() ... .addBar(visibleBox, editableBox, enabledBox).xy(1, 9) ... .build();
- Parameters:
checkBoxes
- the check boxes to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addBar
The first of two steps for adding a radio button bar to this builder's panel. This bar will be added, once the cell constraints are specified.The radio buttons will be laid out as a row in a subpanel. If focus grouping is possible, focus can be transferred between the radio buttons using the arrow keys. Also, focus will be transferred to/from the selected radio button of the group - if any.
return FormBuilder.create() ... .addBar(verticalRadio, horizontalRadio).xy(1, 9) ... .build();
- Parameters:
radioButtons
- the radio buttons to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addStack
The first of two steps for adding a button stack to this builder's panel. This stack will be added, once the cell constraints are specified.The buttons will be laid out vertically in a subpanel, where all buttons use the platform's minimum width. If focus grouping is possible, focus can be transferred between buttons using the arrow keys.
return FormBuilder.create() ... .addStack(newButton, editButton, deleteButton).xywh(5, 1, 1, 7) ... .build();
- Parameters:
buttons
- the buttons to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addStack
The first of two steps for adding a check box stack to this builder's panel. This stack will be added, once the cell constraints are specified.The check boxes will be laid out vertically in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys.
return FormBuilder.create() ... .addStack(visibleBox, editableBox, enabledBox).xywh(5, 1, 1, 7) ... .build();
- Parameters:
checkBoxes
- the check boxes to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addStack
The first of two steps for adding a radio button stack to this builder's panel. This stack will be added, once the cell constraints are specified.The radio buttons will be laid out vertically in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys. Also, focus will be transferred to/from the selected radio button of the group - if any.
return FormBuilder.create() ... .addStack(verticalRadio, horizontalRadio).xywh(5, 1, 1, 7) ... .build();
- Parameters:
radioButtons
- the radio buttons to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
add
Builds the given view into this FormBuilder's form.Note: This is an experimental feature that is not yet part of the public FormBuilder API. It may change without further notice.
- Parameters:
view
- the view to integrate- Returns:
- the fluent interface part used to set the view's origin
-
add
The first of two steps for adding a textual label to the form. Equivalent to:addLabel(markedLabelText, args)
oraddROLabel(markedLabelText, args)
depending on the current defaultLabelType. The label will be created and added, once the cell constraints are specified.return FormBuilder.create() ... .add("Name:") .xy(1, 1) // No Mnemonic .add("Ninvalid input: '&ame':") .xy(1, 1) // Mnemonic is 'a' .add("Save invalid input: '&as':") .xy(1, 1) // Mnemonic is the second 'a' .add("Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'" ... .build();
- Parameters:
markedLabelText
- the text of the label to be added, may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addLabel
The first of two steps for adding a plain label to the form. The label will be created and added, once the cell constraints are specified.return FormBuilder.create() ... .addLabel("Name:") .xy(1, 1) // No Mnemonic .addLabel("Ninvalid input: '&ame':") .xy(1, 1) // Mnemonic is 'a' .addLabel("Save invalid input: '&as':") .xy(1, 1) // Mnemonic is the second 'a' .addLabel("Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'" ... .build();
- Parameters:
markedText
- the label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addROLabel
The first of two steps for adding a textual label to the form that is intended for labeling read-only components. The label will be created and added, once the cell constraints are specified.The read-only labels created by the default component factory are slightly lighter than plain labels. This makes it easier to differ between the labeling text and the text value that is labeled.
return FormBuilder.create() ... .addROLabel("Name:") .xy(1, 1) // No Mnemonic .addROLabel("Ninvalid input: '&ame':") .xy(1, 1) // Mnemonic is 'a' .addROLabel("Save invalid input: '&as':") .xy(1, 1) // Mnemonic is the second 'a' .addROLabel("Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'" ... .build();
- Parameters:
markedText
- the label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addTitle
The first of two steps for adding a title label to the form. The title label will be created and added, once the cell constraints are specified.return FormBuilder.create() ... .addTitle("Name") .xy(1, 1) // No mnemonic .addTitle("Ninvalid input: '&ame'") .xy(1, 1) // Mnemonic is 'a' .addTitle("Lookinvalid input: '&'invalid input: '&Feel'").xy(1, 1) // No mnemonic, text is Lookinvalid input: '&Feel' ... .build();
- Parameters:
markedText
- the title label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addSeparator
The first of two steps for adding a titled separator to the form. The separator will be created and added, once the cell constraints are specified.return FormBuilder.create() ... .addSeparator("Name") .xyw(1, 1, 3) // No Mnemonic .addSeparator("Ninvalid input: '&ame'") .xyw(1, 1, 3) // Mnemonic is 'a' .addSeparator("Lookinvalid input: '&'invalid input: '&Feel'").xyw(1, 1, 3) // No mnemonic, text is "lookinvalid input: '&feel'" ... .build();
- Parameters:
markedText
- the separator label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
add
The first of two steps for adding an icon label to the form. The icon label will be added, once the cell constraints are specified. Ifimage
is null, nothing will be added.- Parameters:
image
- the image to be displayed by the added label- Returns:
- the fluent interface part used to set the cell constraints
- Since:
- 1.9
- See Also:
-
add
The first of two steps for conditionally adding a component to the form. The component will be added, once the cell constraints are specified, but only ifexpression
istrue
.JTables, JLists, and JTrees will be automatically wrapped by a default JScrollPane. If no scroll pane is desired, use
addRaw(boolean, Component)
instead. If a scroll pane is desired for other components (frequent case are JTextAreas) useaddScrolled(boolean, Component)
.return FormBuilder.create() ... .add(nameField) .xy(1, 1) .add(hasCountry, countryCombo).xy(3, 3) ... .build();
If the label-for-feature is enabled, the most recently added label is tracked and associate with the next added component that is applicable for being set as component for the label.- Parameters:
expression
- the precondition for adding the componentc
- the component to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addRaw
The first of two steps for conditionally adding a component to the form. This component will be added, once the cell constraints are specified.Unlike
add(boolean, Component)
, this method won't wrap JTables, JLists, and JTrees automatically with a JScrollPane. Useful for tables, list, and trees that either need no scroll pane, or have another kind of decoration.return FormBuilder.create() ... .addRaw(showTree, aTreeThatNeedsNoScrollPane).xy(1, 1) ... .build();
If the label-for-feature is enabled, the most recently added label is tracked and associated with the next added component that is applicable for being set as component for the label.- Parameters:
expression
- the precondition for adding the componentc
- the component to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addScrolled
The first of two steps for conditionally adding the given component wrapped with a JScrollPane to this builder's panel. The wrapped component will be added once the cell constraints have been specified. A frequent case for this method are JTextAreas that shall be scrolled.The layout is equivalent to:
return FormBuilder.create() ... .add(expression, new JScrollPane(c)).xy(..., ...) ... .build();
- Parameters:
expression
- the precondition for adding the componentc
- the component to be wrapped and added- Returns:
- the fluent interface part used to set the cell constraints
-
addBar
The first of two steps for conditionally adding a button bar to the form. This bar will be added, once the cell constraints are specified.The buttons will be laid out horizontally in a subpanel, where all buttons use the platform's minimum width. If focus grouping is possible, focus can be transferred between buttons using the arrow keys.
return FormBuilder.create() ... .addBar(!readOnly, newButton, editButton, deleteButton).xy(1, 9) ... .build();
- Parameters:
expression
- the precondition for adding the barbuttons
- the buttons to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addBar
The first of two steps for conditionally adding a check box bar to the form. This bar will be added, once the cell constraints are specified.The check boxes will be laid out as a row in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys.
return FormBuilder.create() ... .addBar(!readOnly, visibleBox, editableBox, enabledBox).xy(1, 9) ... .build();
- Parameters:
expression
- the precondition for adding the barcheckBoxes
- the check boxes to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addBar
The first of two steps for conditionally adding a radio button bar to this builder's panel. This bar will be added, once the cell constraints are specified.The radio buttons will be laid out as a row in a subpanel. If focus grouping is possible, focus can be transferred between the radio buttons using the arrow keys. Also, focus will be transferred to/from the selected radio button of the group - if any.
return FormBuilder.create() ... .add ( readOnly, orientationText) .xy(1, 9) .addBar(!readOnly, verticalRadio, horizontalRadio).xy(1, 9) ... .build();
- Parameters:
expression
- the precondition for adding the barradioButtons
- the radio buttons to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addStack
The first of two steps for conditionally adding a button stack to this builder's panel. This stack will be added, once the cell constraints are specified.The buttons will be laid out vertically in a subpanel, where all buttons use the platform's minimum width. If focus grouping is possible, focus can be transferred between buttons using the arrow keys.
return FormBuilder.create() ... .addStack(!readOnly, newButton, editButton, deleteButton).xywh(5, 1, 1, 7) ... .build();
- Parameters:
expression
- the precondition for adding the stackbuttons
- the buttons to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addStack
The first of two steps for conditionally adding a check box stack to this builder's panel. This stack will be added, once the cell constraints are specified.The check boxes will be laid out vertically in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys.
return FormBuilder.create() ... .addStack(!readOnly, visibleBox, editableBox, enabledBox).xywh(5, 1, 1, 7) ... .build();
- Parameters:
expression
- the precondition for adding the stackcheckBoxes
- the check boxes to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addStack
The first of two steps for conditionally adding a radio button stack to this builder's panel. This stack will be added, once the cell constraints are specified.The radio buttons will be laid out vertically in a subpanel. If focus grouping is possible, focus can be transferred between the check boxes using the arrow keys. Also, focus will be transferred to/from the selected radio button of the group - if any.
return FormBuilder.create() ... .addStack(!readOnly, verticalRadio, horizontalRadio).xywh(5, 1, 1, 7) ... .build();
- Parameters:
expression
- the precondition for adding the stackradioButtons
- the radio buttons to add- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
add
Builds the given view into this FormBuilder's form, ifexpression
istrue
.- Parameters:
expression
- the precondition for adding the viewview
- the view to integrate- Returns:
- the fluent interface part used to set the view's origin
-
add
The first of two steps for conditionally adding a textual label to the form. Equivalent to:addLabel(expression, markedLabelText, args)
oraddROLabel(expression, markedLabelText, args)
depending on the current defaultLabelType. The label will be created and added, once the cell constraints are specified.return FormBuilder.create() ... .add(condition, "Name:") .xy(1, 1) // No Mnemonic .add(condition, "Ninvalid input: '&ame':") .xy(1, 1) // Mnemonic is 'a' .add(condition, "Save invalid input: '&as':") .xy(1, 1) // Mnemonic is the second 'a' .add(condition, "Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'" ... .build();
- Parameters:
expression
- the precondition for adding the labelmarkedLabelText
- the text of the label to be added, may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addLabel
The first of two steps for conditionally adding a plain label to the form. The label will be created and added, once the cell constraints are specified.return FormBuilder.create() ... .addLabel(condition, "Name:") .xy(1, 1) // No Mnemonic .addLabel(condition, "Ninvalid input: '&ame':") .xy(1, 1) // Mnemonic is 'a' .addLabel(condition, "Save invalid input: '&as':") .xy(1, 1) // Mnemonic is the second 'a' .addLabel(condition, "Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'" ... .build();
- Parameters:
expression
- the precondition for adding the labelmarkedText
- the label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addROLabel
The first of two steps for conditionally adding a textual label to the form that is intended for labeling read-only components. The label will be created and added, once the cell constraints are specified.The read-only labels created by the default component factory are slightly lighter than plain labels. This makes it easier to differ between the labeling text and the text value that is labeled.
return FormBuilder.create() ... .addROLabel(condition, "Name:") .xy(1, 1) // No Mnemonic .addROLabel(condition, "Ninvalid input: '&ame':") .xy(1, 1) // Mnemonic is 'a' .addROLabel(condition, "Save invalid input: '&as':") .xy(1, 1) // Mnemonic is the second 'a' .addROLabel(condition, "Lookinvalid input: '&'invalid input: '&Feel':").xy(1, 1) // No mnemonic, text is "lookinvalid input: '&feel'" ... .build();
- Parameters:
expression
- the precondition for adding the read-only labelmarkedText
- the label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addTitle
The first of two steps for conditionally adding a title label to the form. The title label will be created and added, once the cell constraints are specified.return FormBuilder.create() ... .addTitle(condition, "Name") .xy(1, 1) // No mnemonic .addTitle(condition, "Ninvalid input: '&ame'") .xy(1, 1) // Mnemonic is 'a' .addTitle(condition, "Lookinvalid input: '&'invalid input: '&Feel'").xy(1, 1) // No mnemonic, text is Lookinvalid input: '&Feel' ... .build();
- Parameters:
expression
- the precondition for adding the titlemarkedText
- the title label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
addSeparator
public FormBuilder.ComponentAdder addSeparator(boolean expression, String markedText, Object... args) The first of two steps for conditionally adding a titled separator to the form. The separator will be created and added, once the cell constraints are specified.return FormBuilder.create() ... .addSeparator(condition, "Name") .xyw(1, 1, 3) // No Mnemonic .addSeparator(condition, "Ninvalid input: '&ame'") .xyw(1, 1, 3) // Mnemonic is 'a' .addSeparator(condition, "Lookinvalid input: '&'invalid input: '&Feel'").xyw(1, 1, 3) // No mnemonic, text is "lookinvalid input: '&feel'" ... .build();
- Parameters:
expression
- the precondition for adding the separatormarkedText
- the separator label's text - may contain an ampersand (&) to mark a mnemonic, and it may be a format stringargs
- optional format arguments- Returns:
- the fluent interface part used to set the cell constraints
- See Also:
-
add
The first of two steps for conditionally adding an icon label to the form. The icon label will be added, once the cell constraints are specified. Ifimage
is null, nothing will be added.- Parameters:
expression
- the precondition for adding the iconimage
- the image to be displayed by the added label- Returns:
- the fluent interface part used to set the cell constraints
- Since:
- 1.9
- See Also:
-
getLayoutMap
-
getLayout
-
getFactory
-
addImpl
-
addImpl
-
manageLabelsAndComponents
-
isLabelForApplicable
Checks and answers whether the given component shall be set as component for a previously added label usingJLabel.setLabelFor(Component)
. This default implementation checks whether the component is focusable, and - if a JComponent - whether it is already labeled by a JLabel. Subclasses may override.- Parameters:
label
- the candidate for labelingcomponent
component
- the component that could be labeled bylabel
- Returns:
- true if focusable, false otherwise
-
setLabelFor
Setslabel
as labeling label forcomponent
or an appropriate child. In case of a JScrollPane as given component, this default implementation labels the view of the scroll pane's viewport.- Parameters:
label
- the labeling labelcomponent
- the component to be labeled, or the parent of the labeled component
-
getMostRecentlyAddedLabel
Returns the most recently added JLabel that has a mnemonic set - if any,null
, if none has been set, or if it has been cleared after setting an association before, or if it has been cleared by the garbage collector.- Returns:
- the most recently added JLabel that has a mnemonic set
and has not been associated with a component applicable for this
feature.
null
otherwise.
-
setMostRecentlyAddedLabel
Sets the given label as most recently added label using a weak reference.- Parameters:
label
- the label to be set
-
clearMostRecentlyAddedLabel
private void clearMostRecentlyAddedLabel()Clears the reference to the most recently added mnemonic label. -
isLeftToRight
private boolean isLeftToRight() -
checkValidFocusTraversalSetup
private void checkValidFocusTraversalSetup()Checks that if the API user has set a focus traversal policy, no focus traversal type and no initial component has been set. -
setupFocusTraversalPolicyAndProvider
private void setupFocusTraversalPolicyAndProvider()
-
padding(String, Object...)
instead