com.jgoodies.forms.builder

## Class ListViewBuilder

- java.lang.Object
- - com.jgoodies.forms.builder.ListViewBuilder

-     public final class ListViewBuilder
      extends 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 new ListViewBuilder()
           .label("&Contacts:")
           .listView(contactsTable)
           .listBar(newButton, editButton, deleteButton)
           .build();

       return new ListViewBuilder()
           .border(Borders.DLU14)
           .labelView(contactsLabel)
           .filterView(contactsSearchField)
           .listView(contactsTable)
           .listBar(newButton, editButton, deleteButton, null, printButton)
           .detailsView(contactDetailsView)
           .build();

  For more examples see the JGoodies Showcase application.
  Since:
    1.6
  Version:
    $Revision: 1.2 $
  Author:
    Karsten Lentzsch

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ListViewBuilder()` Constructs a ListViewBuilder using the AbstractBuilder's default component factory.
    `ListViewBuilder(ComponentFactory factory)` Constructs a ListViewBuilder using the given component factory.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ListViewBuilder` | `border(Border border)` Sets an optional border that surrounds the list view including the label and details.
    `JComponent` | `build()` Lazily builds and returns the list view panel.
    `ListViewBuilder` | `detailsView(JComponent detailsView)` Sets an optional details view that is located under the list view.
    `ListViewBuilder` | `filterView(JComponent filterView)` Sets an optional view that will be placed in the upper right corner of the built list view panel.
    `ListViewBuilder` | `filterViewColSpec(String colSpec)` Changes the FormLayout column specification used to lay out the filter view.
    `ListViewBuilder` | `focusTraversal(FocusTraversalPolicy policy)` Sets the panel's focus traversal policy and sets the panel as focus traversal policy provider.
    `ListViewBuilder` | `headerLabel(String markedText)` 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` | `label(String markedText)` Creates a plain label for the given marked text and sets it as label view.
    `ListViewBuilder` | `labelView(JComponent labelView)` Sets the mandatory label view.
    `ListViewBuilder` | `listBar(JComponent... buttons)` Builds a button bar using the given buttons and sets it as list bar.
    `ListViewBuilder` | `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.
    `ListViewBuilder` | `listExtrasView(JComponent listExtrasView)` Sets an optional view that is located in the lower right corner of the list view, aligned with the list bar.
    `ListViewBuilder` | `listView(JComponent listView)` Sets the given component as the the mandatory list view.
    `ListViewBuilder` | `listViewRowSpec(String rowSpec)` Changes the FormLayout row specification used to lay out the list view.
    `ListViewBuilder` | `namePrefix(String namePrefix)` Sets the prefix that is prepended to component name of components that have no name set or that are are implicitly created by this builder, e.g. the (header) label.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ListViewBuilder

          public ListViewBuilder()

      Constructs a ListViewBuilder using the AbstractBuilder's default component factory. The factory is required by `label(String)` and `headerLabel(String)`.

    - #### ListViewBuilder

          public ListViewBuilder(ComponentFactory factory)

      Constructs a ListViewBuilder using the given component factory. The factory is required by `label(String)` and `headerLabel(String)`.
      Parameters:
        `factory` - the component factory used to create labels and headers

  - ### Method Detail

    - #### border

          public ListViewBuilder border(Border border)

      Sets an optional border that surrounds the list view including the label and details.
      Parameters:
        `border` - the border to set

    - #### focusTraversal

          public ListViewBuilder focusTraversal(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
      Since:
        1.7.2
      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.

      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
      Since:
        1.7.1

    - #### namePrefix

          public ListViewBuilder namePrefix(String namePrefix)

      Sets the prefix that is prepended to 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
      Since:
        1.7.1

    - #### labelView

          public ListViewBuilder labelView(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

    - #### label

          public ListViewBuilder label(String markedText)

      Creates a plain label for the given marked text and sets it as label view. Equivalent to:

           labelView(aComponentFactory.createLabel(markedText));

      Parameters:
        `markedText` - the label's text, may contain a mnemonic marker

    - #### headerLabel

          public ListViewBuilder headerLabel(String markedText)

      Creates a header label for the given marked text and sets it as label view. Equivalent to:

           labelView(aComponentFactory.createHeaderLabel(markedText));

      Parameters:
        `markedText` - the label's text, may contain a mnemonic marker

    - #### filterView

          public ListViewBuilder filterView(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.

    - #### filterViewColSpec

          public ListViewBuilder filterViewColSpec(String colSpec)

      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
      Throws:
        `NullPointerException` - if `colSpec` is `null`

    - #### listView

          public ListViewBuilder listView(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
      Throws:
        `NullPointerException` - if `listView` is `null`

    - #### listViewRowSpec

          public ListViewBuilder listViewRowSpec(String rowSpec)

      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:

           .listViewRowSpec("fill:100dlu");  // fixed height
           .listViewRowSpec("f:100dlu:g");   // fixed start height, grows
           .listViewRowSpec("f:p");          // no minimum height

      Parameters:
        `rowSpec` - specifies the vertical layout of the list view
      Throws:
        `NullPointerException` - if `rowSpec` is `null`

    - #### listBarView

          public ListViewBuilder 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. If the list bar view consists only of buttons, use `listBar(JComponent...)` instead.
      Parameters:
        `listBarView` - the component to set

    - #### listBar

          public ListViewBuilder listBar(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.buildButtonBar(buttons))`.

      Parameters:
        `buttons` - the buttons in the list bar
      Throws:
        `NullPointerException` - if `buttons` is `null`
        `IllegalArgumentException` - if no buttons are provided
      See Also:
        `ButtonBarBuilder.addButton(JComponent...)`

    - #### listExtrasView

          public ListViewBuilder listExtrasView(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

    - #### detailsView

          public ListViewBuilder detailsView(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

    - #### build

          public JComponent build()

      Lazily builds and returns the list view panel.
      Returns:
        the built panel

Copyright © 2002-2014 JGoodies Software GmbH. All Rights Reserved.