Package ca.corbett.forms.fields

Class ListSubsetField<T>

java.lang.Object
ca.corbett.forms.fields.FormField
ca.corbett.forms.fields.ListSubsetField<T>
public class ListSubsetField<T> extends FormField
Represents a FormField that allows selection of a subset from a list. Two lists are shown: one with all available items, and another with the selected subset. Controls are provided such that users can move items between the two lists.

Sorting: by default, items in both lists maintain their original order as provided in the constructor. You can enable automatic sorting by calling setAutoSortingEnabled(true). When auto-sorting is enabled, items will be sorted in their natural order (assuming T implements Comparable) when items are moved between lists. You can provide a custom Comparator by calling setItemComparator() to control the sort order.

Controlling list size: you can control how many rows are visible in each list by calling setVisibleRowCount(). By default, both lists show 4 rows. You can also specify a fixed cell width by calling setFixedCellWidth(). By default, the fixed cell width is -1, which means the cell width will be automatically sized to fit the largest item in the list. Additionally, you have the option of calling setShouldExpand(true) to have the entire field expand horizontally to fill the available width of the form panel. This defaults to false, meaning the field will be just wide enough to display the two lists at their natural sizes.

Drag and drop: There are two uses of drag and drop within this component:

  • Users can drag items from one list to the other to move them between lists.
  • When auto-sorting is disabled, users can drag items within a list to reorder the items.
Since:
swing-extras 2.6
Author:
scorbo2

  • Field Details

    • DEFAULT_VISIBLE_ROW_COUNT

      public static final int DEFAULT_VISIBLE_ROW_COUNT
      See Also:

    • DEFAULT_FIXED_CELL_WIDTH

      public static final int DEFAULT_FIXED_CELL_WIDTH
      See Also:

  • Constructor Details

    • ListSubsetField

      public ListSubsetField(String label)
      Creates an empty ListSubsetField with the given field label.

    • ListSubsetField

      public ListSubsetField(String label, List<T> availableItems)
      Creates a ListSubsetField with the given label and list of available items. Nothing is selected by default.

    • ListSubsetField

      public ListSubsetField(String label, List<T> availableItems, List<T> selectedItems)
      Creates a ListSubsetField with the given label, list of available items, and list of selected items. The selected items will be removed from the available items, if present. The list of selected items may be empty, and may also reference items that are not present in the available items list. The field's list of items is always the union of the available items and the selected items.

  • Method Details

    • getAvailableItems

      public List<T> getAvailableItems()
      Gets the list of currently available items - that is, items that are still present in the left list. If the returned list is empty, then all items are selected.

    • getSelectedItems

      public List<T> getSelectedItems()
      Gets the list of currently selected items - that is, items that are present in the right list. If the returned list is empty, then no items are selected.

    • selectItems

      public ListSubsetField<T> selectItems(List<T> itemsToSelect)
      Programmatically select the given items. This will only select items that were not already selected. Any items not present in the available items list will be ignored.

    • clearSelection

      public ListSubsetField<T> clearSelection()
      Clears the current selection - this is equivalent to calling unselectAllItems().

    • selectItem

      public ListSubsetField<T> selectItem(T item)
      Allow callers to programmatically move an item to the right list (select it). Does nothing if the given item is not present in the available items list.

    • unselectItem

      public ListSubsetField<T> unselectItem(T item)
      Allow callers to programmatically move an item to the left list (unselect it). Does nothing if the given item is not present in the selected items list.

    • selectAllItems

      public ListSubsetField<T> selectAllItems()
      Allow callers to programmatically move all items right (select all).

    • unselectAllItems

      public ListSubsetField<T> unselectAllItems()
      Allow callers to programmatically move all items left (unselect all).

    • getVisibleRowCount

      public int getVisibleRowCount()
      Gets the current visible row count. The default count is 4. Internally, we return the visible row count for the available list, but the two lists are kept in sync, so they will always be the same.

    • setVisibleRowCount

      public ListSubsetField<T> setVisibleRowCount(int count)
      Sets the desired visible row count. The default count is 4. Both the available list and the selected list will be set to this value.

    • setCellRenderer

      public ListSubsetField<T> setCellRenderer(ListCellRenderer<T> renderer)
      You can optionally set a custom cell renderer if your list items have special display requirements. Both the available list and the selected list will be set to use this renderer.

    • getCellRenderer

      public ListCellRenderer<? super T> getCellRenderer()
      Returns the effective list cell renderer. Internally, we return the renderer for the available list, but the two lists are kept in sync, so both lists use the same renderer.

    • getItemComparator

      public Comparator<T> getItemComparator()
      Returns the comparator used to sort items when they are added to either list. If null, the natural ordering of the items is used. The default value is null.

    • setItemComparator

      public ListSubsetField<T> setItemComparator(Comparator<T> comparator)
      Sets the comparator used to sort items when they are added to either list. If null, the natural ordering of the items is used.

    • isAutoSortingEnabled

      public boolean isAutoSortingEnabled()
      Returns whether auto-sorting is enabled for both lists. When enabled, items are sorted when moved between lists. When disabled (default), items maintain their original order.

    • setAutoSortingEnabled

      public ListSubsetField<T> setAutoSortingEnabled(boolean enabled)
      Sets whether auto-sorting is enabled for both lists. When enabled, items are sorted when moved between lists. When disabled (default), items maintain their original order.

      Note: Enabling auto-sorting will immediately sort both lists. Disabling auto-sorting will not change the current ordering of items.

      Note: Enabling auto-sorting will automatically disable the ability to drag items within a list to re-order the list. When auto-sorting is disabled, users can drag items within a list to change their order.

    • getFixedCellWidth

      public int getFixedCellWidth()
      Returns the pixel width of each list cell. A value of -1 here means the list cells will auto-size their widths based on the width of the longest item in the list. Internally, we return the fixed cell width for the available list, but the two lists are kept in sync, so both lists have the same fixed cell width. The default value is -1.

    • setFixedCellWidth

      public ListSubsetField<T> setFixedCellWidth(int width)
      Sets the pixel width of each list cell. The default value is -1, which will set each cell's width to the width of the largest item. Both the available list and the selected list will be set to this value.

    • isMultiLine

      public boolean isMultiLine()
      ListSubsetFields occupy more than one form row (at least, generally speaking, that statement is true - you could of course set a visibleRowCount of 1, but why would you do that).
      Overrides:
      isMultiLine in class FormField

    • setShouldExpand

      public ListSubsetField setShouldExpand(boolean should)
      Sets whether this field should expand horizontally to fill available form panel width. The default is false, meaning the field will be just wide enough to display the two lists at their natural sizes.

    • shouldExpand

      public boolean shouldExpand()
      Overridden here to allow optional width expansion of the field to fill the form panel's width. The default is false.
      Overrides:
      shouldExpand in class FormField