Class ListViewBuilder
Examples:
return ListViewBuilder.create()
.labelText("invalid input: '&Contacts':")
.listView(contactsTable)
.listBar(newButton, editButton, deleteButton)
.build();
return ListViewBuilder.create()
.padding(Paddings.DLU14)
.label(contactsLabel)
.filterView(contactsSearchField)
.listView(contactsTable)
.listBar(newButton, editButton, deleteButton, null, printButton)
.detailsView(contactDetailsView)
.build();
For more examples see the JGoodies Showcase application.- Since:
- 1.9
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Border
private JComponent
private ComponentFactory
private JComponent
private String
private FocusTraversalPolicy
private FocusTraversalType
private boolean
private Component
private JComponent
private JComponent
private JComponent
private JComponent
private JComponent
private String
private String
private JComponent
Holds the panel that has been lazily built in#buildPanel
. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Constructs a ListViewBuilder using the global default component factory. -
Method Summary
Modifier and TypeMethodDescriptionSets an optional border that surrounds the list view including the label and details.build()
Lazily builds and returns the list view panel.private JComponent
private JComponent
private JComponent
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.static ListViewBuilder
create()
Creates and returns a ListViewBuilder using the global default component factory.detailsView
(JComponent detailsView) Sets an optional details view that is located under the list view.factory
(ComponentFactory factory) Setsfactory
as this builder's new component factory that is used to create the label or header components.filterView
(JComponent filterView) Sets an optional view that will be placed in the upper right corner of the built list view panel.filterViewColumn
(String colSpec, Object... args) Changes the FormLayout column specification used to lay out the filter view.Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider.focusTraversalType
(FocusTraversalType focusTraversalType) private ComponentFactory
private boolean
private boolean
private boolean
private boolean
hasLabel()
private boolean
private boolean
private boolean
private boolean
hasStack()
headerText
(String markedText, Object... args) Creates a header label for the given marked text and sets it as label view.honorVisibility
(boolean b) Specifies whether invisible components shall be taken into account by this builder for computing the layout size and setting component bounds.initialComponent
(JComponent initialComponent) Sets the component that shall receive the focus if this panel's parent is made visible the first time.private void
label
(JComponent labelView) Sets the mandatory label view.Creates a plain label for the given marked text and sets it as label view.listBar
(JComponent... buttons) Builds a button bar using the given buttons and sets it as list bar.listBarView
(JComponent listBarView) Sets an optional list bar - often a button bar - that will be located in the lower left corner of the list view.listExtrasView
(JComponent listExtrasView) Sets an optional view that is located in the lower right corner of the list view, aligned with the list bar.listStack
(JComponent... buttons) Builds a button stack using the given buttons and sets it as list stack.listStackView
(JComponent listStackView) Sets an optional list stack - often a stack of buttons - that will be located on the right-hand side of the list view.listView
(JComponent listView) Sets the given component as the the mandatory list view.listViewRow
(String rowSpec, Object... args) Changes the FormLayout row specification used to lay out the list view.namePrefix
(String namePrefix) Sets the prefix that is prepended to the component name of components that have no name set or that are are implicitly created by this builder, e.g.private void
overrideNameIfBlank
(JComponent component, String suffix) 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 an optional padding (an empty border) that surrounds the list view including the label and details.
-
Field Details
-
factory
-
label
-
filterView
-
listView
-
listBarView
-
listExtrasView
-
detailsView
-
listStackView
-
border
-
honorsVisibility
private boolean honorsVisibility -
initialComponent
-
focusTraversalType
-
focusTraversalPolicy
-
namePrefix
-
filterViewColSpec
-
listViewRowSpec
-
panel
Holds the panel that has been lazily built in#buildPanel
.
-
-
Constructor Details
-
ListViewBuilder
private ListViewBuilder()Constructs a ListViewBuilder using the global default component factory. The factory is required bylabelText(String, Object...)
andheaderText(String, Object...)
.
-
-
Method Details
-
create
Creates and returns a ListViewBuilder using the global default component factory. The factory is required bylabelText(String, Object...)
andheaderText(String, Object...)
.- Returns:
- the ListViewBuilder
-
border
Sets an optional border that surrounds the list view including the label and details.- Parameters:
border
- the border to set
-
padding
Sets an optional padding (an empty border) that surrounds the list view including the label and details.- Parameters:
padding
- the white space to use around the list view panel- Since:
- 1.9
-
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:
-
initialComponent
Sets the component that shall receive the focus if this panel's parent is made visible the first time.- Parameters:
initialComponent
- the component that shall receive the focus if the panel is made visible the first time- Returns:
- a reference to this builder
- See Also:
-
focusTraversalType
- Parameters:
focusTraversalType
- either: layout or container order- Returns:
- a reference to this builder
- See Also:
-
focusTraversalPolicy
Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider. Hence, this call is 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
- See Also:
-
honorVisibility
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.A typical use case for ignoring the visibility is here: if the list selection is empty, the details view is made invisible to hide the then obsolete read-only labels. If visibility is honored, the list view would grow and shrink on list selection. If ignored, the layout remains stable.
- 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
-
namePrefix
Sets the prefix that is prepended to the component name of components that have no name set or that are are implicitly created by this builder, e.g. the (header) label. The default name prefix is "ListView".- Parameters:
namePrefix
- the prefix to be used- Returns:
- a reference to this builder
-
factory
Setsfactory
as this builder's new component factory that is used to create the label or header components. 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 the header or label- Returns:
- a reference to this builder
-
label
Sets the mandatory label view. Useful to set a bound label that updates its text when the list content changes, for example to provide the number of list elements.- Parameters:
labelView
- the component that shall label the list view, often a bound label- Returns:
- a reference to this builder
-
labelText
Creates a plain label for the given marked text and sets it as label view. If no arguments are provided, the plain String is used. Otherwise the string will be formatted usingString.format
with the given arguments. Equivalent to:label(aComponentFactory.createLabel(Strings.get(markedText, args)));
- Parameters:
markedText
- the label's text, may contain a mnemonic markerargs
- optional format arguments forwarded toString#format
- Returns:
- a reference to this builder
- See Also:
-
headerText
Creates a header label for the given marked text and sets it as label view. If no arguments are provided, the plain String is used. Otherwise the string will be formatted usingString.format
with the given arguments. Equivalent to:labelView(aComponentFactory.createHeaderLabel(Strings.get(markedText, args)));
- Parameters:
markedText
- the label's text, may contain a mnemonic markerargs
- optional format arguments forwarded toString#format
- Returns:
- a reference to this builder
- See Also:
-
filterView
Sets an optional view that will be placed in the upper right corner of the built list view panel. This can be a search field, a panel with filtering check boxes ("Only valid items"), etc.- Parameters:
filterView
- the view to be added.- Returns:
- a reference to this builder
-
filterViewColumn
Changes the FormLayout column specification used to lay out the filter view. The default value is"[100dlu, p]"
, which is a column where the width is determined by the filter view's preferred width, but a minimum width of 100dlu is ensured. The filter view won't grow horizontally, if the container gets more space.- Parameters:
colSpec
- specifies the horizontal layout of the filter viewargs
- optionalcolSpec
format arguments forwarded toString#format
- Returns:
- a reference to this builder
- Throws:
NullPointerException
- ifcolSpec
isnull
-
listView
Sets the given component as the the mandatory list view. IflistView
is a JTable, JList, or JTree, it is automatically wrapped with a JScrollPane, before the scroll pane is set as list view.- Parameters:
listView
- the component to be used as scrollable list view- Returns:
- a reference to this builder
- Throws:
NullPointerException
- iflistView
isnull
-
listViewRow
Changes the FormLayout row specification used to lay out the list view. The default value is"fill:[100dlu, pref]:grow"
, which is a row that is filled by the list view; the height is determined by the list view's preferred height, but a minimum of 100dlu is ensured. The list view grows vertically, if the container gets more vertical space.Examples:
.listViewRow("fill:100dlu"); // fixed height .listViewRow("f:100dlu:g"); // fixed start height, grows .listViewRow("f:p"); // no minimum height
- Parameters:
rowSpec
- specifies the vertical layout of the list viewargs
- optionalrowSpec
format arguments forwarded toString#format
- Returns:
- a reference to this builder
- Throws:
NullPointerException
- ifrowSpec
isnull
-
listBarView
Sets an optional list bar - often a button bar - that will be located in the lower left corner of the list view. If the list bar view consists only of buttons, uselistBar(JComponent...)
instead.- Parameters:
listBarView
- the component to set- Returns:
- a reference to this builder
-
listBar
Builds a button bar using the given buttons and sets it as list bar. Although JButtons are expected, any JComponent is accepted to allow custom button component types.Equivalent to
listBarView(Forms.buttonBar(buttons))
.- Parameters:
buttons
- the buttons in the list bar- Returns:
- a reference to this builder
- Throws:
NullPointerException
- ifbuttons
isnull
IllegalArgumentException
- if no buttons are provided- See Also:
-
listStackView
Sets an optional list stack - often a stack of buttons - that will be located on the right-hand side of the list view. If the list stack view consists only of buttons, uselistStack(JComponent...)
instead.- Parameters:
listStackView
- the component to set- Returns:
- a reference to this builder
-
listStack
Builds a button stack using the given buttons and sets it as list stack. Although JButtons are expected, any JComponent is accepted to allow custom button component types.Equivalent to
listStackView(Forms.buttonStack(buttons))
.- Parameters:
buttons
- the buttons in the list stack- Returns:
- a reference to this builder
- Throws:
NullPointerException
- ifbuttons
isnull
IllegalArgumentException
- if no buttons are provided- See Also:
-
listExtrasView
Sets an optional view that is located in the lower right corner of the list view, aligned with the list bar.- Parameters:
listExtrasView
- the component to set- Returns:
- a reference to this builder
-
detailsView
Sets an optional details view that is located under the list view. Often this is the details view or preview of a master-details view.- Parameters:
detailsView
- the component to set- Returns:
- a reference to this builder
-
build
Lazily builds and returns the list view panel.- Returns:
- the built panel
-
getFactory
-
invalidatePanel
private void invalidatePanel() -
buildPanel
-
buildHeader
-
buildOperations
-
hasLabel
private boolean hasLabel() -
hasFilter
private boolean hasFilter() -
hasHeader
private boolean hasHeader() -
hasListBar
private boolean hasListBar() -
hasListExtras
private boolean hasListExtras() -
hasOperations
private boolean hasOperations() -
hasStack
private boolean hasStack() -
hasDetails
private boolean hasDetails() -
overrideNameIfBlank
-
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.
-