Class ListViewBuilder
- java.lang.Object
-
- com.jgoodies.forms.builder.ListViewBuilder
-
public final class ListViewBuilder extends java.lang.Object
Builds list/table views from a set of mandatory and optional components: label, filter/search, list (table), list buttons, list extras, details view (or preview).Examples:
return ListViewBuilder.create() .labelText("&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
Fields Modifier and Type Field Description private javax.swing.border.Border
border
private javax.swing.JComponent
detailsView
private ComponentFactory
factory
private javax.swing.JComponent
filterView
private java.lang.String
filterViewColSpec
private java.awt.FocusTraversalPolicy
focusTraversalPolicy
private FocusTraversalType
focusTraversalType
private boolean
honorsVisibility
private java.awt.Component
initialComponent
private javax.swing.JComponent
label
private javax.swing.JComponent
listBarView
private javax.swing.JComponent
listExtrasView
private javax.swing.JComponent
listStackView
private javax.swing.JComponent
listView
private java.lang.String
listViewRowSpec
private java.lang.String
namePrefix
private javax.swing.JComponent
panel
Holds the panel that has been lazily built in#buildPanel
.
-
Constructor Summary
Constructors Modifier Constructor Description private
ListViewBuilder()
Constructs a ListViewBuilder using the global default component factory.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description ListViewBuilder
border(javax.swing.border.Border border)
Sets an optional border that surrounds the list view including the label and details.javax.swing.JComponent
build()
Lazily builds and returns the list view panel.private javax.swing.JComponent
buildHeader()
private javax.swing.JComponent
buildOperations()
private javax.swing.JComponent
buildPanel()
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.static ListViewBuilder
create()
Creates and returns a ListViewBuilder using the global default component factory.ListViewBuilder
detailsView(javax.swing.JComponent detailsView)
Sets an optional details view that is located under the list view.ListViewBuilder
factory(ComponentFactory factory)
Setsfactory
as this builder's new component factory that is used to create the label or header components.ListViewBuilder
filterView(javax.swing.JComponent filterView)
Sets an optional view that will be placed in the upper right corner of the built list view panel.ListViewBuilder
filterViewColumn(java.lang.String colSpec, java.lang.Object... args)
Changes the FormLayout column specification used to lay out the filter view.ListViewBuilder
focusTraversalPolicy(java.awt.FocusTraversalPolicy policy)
Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider.ListViewBuilder
focusTraversalType(FocusTraversalType focusTraversalType)
private ComponentFactory
getFactory()
private boolean
hasDetails()
private boolean
hasFilter()
private boolean
hasHeader()
private boolean
hasLabel()
private boolean
hasListBar()
private boolean
hasListExtras()
private boolean
hasOperations()
private boolean
hasStack()
ListViewBuilder
headerText(java.lang.String markedText, java.lang.Object... args)
Creates a header label for the given marked text and sets it as label view.ListViewBuilder
honorVisibility(boolean b)
Specifies whether invisible components shall be taken into account by this builder for computing the layout size and setting component bounds.ListViewBuilder
initialComponent(javax.swing.JComponent initialComponent)
Sets the component that shall receive the focus if this panel's parent is made visible the first time.private void
invalidatePanel()
ListViewBuilder
label(javax.swing.JComponent labelView)
Sets the mandatory label view.ListViewBuilder
labelText(java.lang.String markedText, java.lang.Object... args)
Creates a plain label for the given marked text and sets it as label view.ListViewBuilder
listBar(javax.swing.JComponent... buttons)
Builds a button bar using the given buttons and sets it as list bar.ListViewBuilder
listBarView(javax.swing.JComponent listBarView)
Sets an optional list bar - often a button bar - that will be located in the lower left corner of the list view.ListViewBuilder
listExtrasView(javax.swing.JComponent listExtrasView)
Sets an optional view that is located in the lower right corner of the list view, aligned with the list bar.ListViewBuilder
listStack(javax.swing.JComponent... buttons)
Builds a button stack using the given buttons and sets it as list stack.ListViewBuilder
listStackView(javax.swing.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.ListViewBuilder
listView(javax.swing.JComponent listView)
Sets the given component as the the mandatory list view.ListViewBuilder
listViewRow(java.lang.String rowSpec, java.lang.Object... args)
Changes the FormLayout row specification used to lay out the list view.ListViewBuilder
namePrefix(java.lang.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(javax.swing.JComponent component, java.lang.String suffix)
ListViewBuilder
padding(java.lang.String paddingSpec, java.lang.Object... args)
Sets the panel's padding as an EmptyBorder using the given specification for the top, left, bottom, right margins in DLU.ListViewBuilder
padding(javax.swing.border.EmptyBorder padding)
Sets an optional padding (an empty border) that surrounds the list view including the label and details.
-
-
-
Field Detail
-
factory
private ComponentFactory factory
-
label
private javax.swing.JComponent label
-
filterView
private javax.swing.JComponent filterView
-
listView
private javax.swing.JComponent listView
-
listBarView
private javax.swing.JComponent listBarView
-
listExtrasView
private javax.swing.JComponent listExtrasView
-
detailsView
private javax.swing.JComponent detailsView
-
listStackView
private javax.swing.JComponent listStackView
-
border
private javax.swing.border.Border border
-
honorsVisibility
private boolean honorsVisibility
-
initialComponent
private java.awt.Component initialComponent
-
focusTraversalType
private FocusTraversalType focusTraversalType
-
focusTraversalPolicy
private java.awt.FocusTraversalPolicy focusTraversalPolicy
-
namePrefix
private java.lang.String namePrefix
-
filterViewColSpec
private java.lang.String filterViewColSpec
-
listViewRowSpec
private java.lang.String listViewRowSpec
-
panel
private javax.swing.JComponent panel
Holds the panel that has been lazily built in#buildPanel
.
-
-
Constructor Detail
-
ListViewBuilder
private ListViewBuilder()
Constructs a ListViewBuilder using the global default component factory. The factory is required bylabelText(String, Object...)
andheaderText(String, Object...)
.
-
-
Method Detail
-
create
public static ListViewBuilder 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
public ListViewBuilder border(javax.swing.border.Border border)
Sets an optional border that surrounds the list view including the label and details.- Parameters:
border
- the border to set
-
padding
public ListViewBuilder padding(javax.swing.border.EmptyBorder 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
public ListViewBuilder padding(java.lang.String paddingSpec, java.lang.Object... args)
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:
padding(EmptyBorder)
,Paddings.createPadding(String, Object...)
-
initialComponent
public ListViewBuilder initialComponent(javax.swing.JComponent 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(FocusTraversalType)
-
focusTraversalType
public ListViewBuilder focusTraversalType(FocusTraversalType focusTraversalType)
- Parameters:
focusTraversalType
- either: layout or container order- Returns:
- a reference to this builder
- See Also:
initialComponent(JComponent)
-
focusTraversalPolicy
public ListViewBuilder focusTraversalPolicy(java.awt.FocusTraversalPolicy policy)
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:
Container.setFocusTraversalPolicy(FocusTraversalPolicy)
,Container.setFocusTraversalPolicyProvider(boolean)
-
honorVisibility
public ListViewBuilder honorVisibility(boolean b)
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
public ListViewBuilder namePrefix(java.lang.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. the (header) label. The default name prefix is "ListView".- Parameters:
namePrefix
- the prefix to be used- Returns:
- a reference to this builder
-
factory
public ListViewBuilder factory(ComponentFactory 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
public ListViewBuilder label(javax.swing.JComponent labelView)
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
public ListViewBuilder labelText(java.lang.String markedText, java.lang.Object... args)
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:
String.format(String, Object...)
-
headerText
public ListViewBuilder headerText(java.lang.String markedText, java.lang.Object... args)
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:
String.format(String, Object...)
-
filterView
public ListViewBuilder filterView(javax.swing.JComponent 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
public ListViewBuilder filterViewColumn(java.lang.String colSpec, java.lang.Object... args)
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:
java.lang.NullPointerException
- ifcolSpec
isnull
-
listView
public ListViewBuilder listView(javax.swing.JComponent 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:
java.lang.NullPointerException
- iflistView
isnull
-
listViewRow
public ListViewBuilder listViewRow(java.lang.String rowSpec, java.lang.Object... args)
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:
java.lang.NullPointerException
- ifrowSpec
isnull
-
listBarView
public ListViewBuilder listBarView(javax.swing.JComponent 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
public ListViewBuilder listBar(javax.swing.JComponent... buttons)
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:
java.lang.NullPointerException
- ifbuttons
isnull
java.lang.IllegalArgumentException
- if no buttons are provided- See Also:
Forms.buttonBar(JComponent...)
-
listStackView
public ListViewBuilder listStackView(javax.swing.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. 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
public ListViewBuilder listStack(javax.swing.JComponent... buttons)
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:
java.lang.NullPointerException
- ifbuttons
isnull
java.lang.IllegalArgumentException
- if no buttons are provided- See Also:
Forms.buttonStack(JComponent...)
-
listExtrasView
public ListViewBuilder listExtrasView(javax.swing.JComponent 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
public ListViewBuilder detailsView(javax.swing.JComponent 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
public javax.swing.JComponent build()
Lazily builds and returns the list view panel.- Returns:
- the built panel
-
getFactory
private ComponentFactory getFactory()
-
invalidatePanel
private void invalidatePanel()
-
buildPanel
private javax.swing.JComponent buildPanel()
-
buildHeader
private javax.swing.JComponent buildHeader()
-
buildOperations
private javax.swing.JComponent 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
private void overrideNameIfBlank(javax.swing.JComponent component, java.lang.String suffix)
-
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.
-
-