Package com.jgoodies.forms.builder

Class 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

    • 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)
      Sets factory 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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • 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

      • 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.

    • Method Detail

      • 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 use
        args - optional format arguments, used if paddingSpec 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)

      • 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 to true invisible components will be ignored by the layout. If set to false 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 to false (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

      • 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 using String.format with the given arguments. Equivalent to: 
         label(aComponentFactory.createLabel(Strings.get(markedText, args)));
        Parameters:
        markedText - the label's text, may contain a mnemonic marker
        args - optional format arguments forwarded to String#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 using String.format with the given arguments. Equivalent to: 
         labelView(aComponentFactory.createHeaderLabel(Strings.get(markedText, args)));
        Parameters:
        markedText - the label's text, may contain a mnemonic marker
        args - optional format arguments forwarded to String#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 view
        args - optional colSpec format arguments forwarded to String#format
        Returns:
        a reference to this builder
        Throws:
        java.lang.NullPointerException - if colSpec is null

      • listView

        public ListViewBuilder listView​(javax.swing.JComponent listView)
        Sets the given component as the the mandatory list view. If listView 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 - if listView is null

      • 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 view
        args - optional rowSpec format arguments forwarded to String#format
        Returns:
        a reference to this builder
        Throws:
        java.lang.NullPointerException - if rowSpec is null

      • 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, use listBar(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 - if buttons is null
        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, use listStack(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 - if buttons is null
        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

      • 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.