Package ca.corbett.forms.fields

Class ListField<T>

java.lang.Object
ca.corbett.forms.fields.FormField
ca.corbett.forms.fields.ListField<T>
public class ListField<T> extends FormField
Wraps a JList to allow for multi-selection of some object type. A common use case would be ListField<String> to wrap a simple list of Strings. The underlying JList can be obtained by calling getList(), if you need to do custom styling or whatnot on the JList.

An important note about value changed events - this field's "value" is the list of selected items. Therefore, value changed events are only fired when the selection changes, and NOT when the list contents change. If you need to be notified when the list contents change, you will need to add a ListDataListener to the underlying ListModel yourself. You can do this by accessing the list model directly: 

myListField.getListModel().addListDataListener(...);

Or, you can use the addListDataListener() convenience method: 

myListField.addListDataListener(...);

Adding action buttons to a ListField

You can add action buttons to the ListField by using the addButton(Action) method. This works very similarly to ButtonField, in that you can control the alignment, hgap, and vgap of the button panel. ListField offers the option of placing the button panel either below the list (by default) or above the list, via the setButtonPosition() method. You can control the preferred size of buttons added to the button panel via the setButtonPreferredSize() method.

There are some built-in actions included with swing-extras that are useful for ListFields, such as ListItemRemoveAction, ListItemMoveAction, and ListItemClearAction. These are found in the ca.corbett.forms.actions package. Adding your own actions is very easy - you can use any Action instance, but you should consider extending the EnhancedAction class to make setting things like icons and tooltips easier. See the example actions in the built-in demo application on the "Forms: lists and panels" tab!

Since:
swing-extras 2.3
Author:
scorbo2

  • Field Details

  • Constructor Details

    • ListField

      public ListField(String label, List<T> items)
      If you supply a List of T, we will create and use a DefaultListModel implicitly. Use the overloaded constructor if you wish to use your own ListModel instead.

    • ListField

      public ListField(String label, DefaultListModel<T> listModel)
      If you supply a ListModel of T, we will use that instead of creating a DefaultListModel. Either way, you can retrieve the model after creation with the getListModel() method.

  • Method Details

    • getSelectionMode

      public int getSelectionMode()
      Gets the list selection model (allowable values are ListSelectionModel.SINGLE_SELECTION, ListSelectionModel.MULTIPLE_INTERVAL_SELECTION, and ListSelectionModel.SINGLE_INTERVAL_SELECTION).

    • setSelectionMode

      public ListField<T> setSelectionMode(int selectionMode)
      Sets the list selection model (allowable values are ListSelectionModel.SINGLE_SELECTION, ListSelectionModel.MULTIPLE_INTERVAL_SELECTION, and ListSelectionModel.SINGLE_INTERVAL_SELECTION). Any other value is ignored. The default value is MULTIPLE_INTERVAL_SELECTION.

    • getLayoutOrientation

      public int getLayoutOrientation()
      Gets the layout orientation (allowable values are JList.VERTICAL, JList.VERTICAL_WRAP, and JList.HORIZONTAL_WRAP).

    • setLayoutOrientation

      public ListField<T> setLayoutOrientation(int orientation)
      Sets the layout orientation (allowable values are JList.VERTICAL, JList.VERTICAL_WRAP, and JList.HORIZONTAL_WRAP). Any other value is ignored. The default value is VERTICAL.

    • setEnabled

      public FormField setEnabled(boolean isEnabled)
      Description copied from class: FormField
      Enables or disables all components in this field.

      Note: The help label is intentionally not disabled when the field is disabled. This is because the help label should always be visible and accessible to the user, even when the field itself is disabled. Descendant classes can override setEnabled() to implement their own handling if needed.

      Overrides:
      setEnabled in class FormField
      Parameters:
      isEnabled - whether to enable or disable the components.

    • getVisibleRowCount

      public int getVisibleRowCount()

    • setVisibleRowCount

      public ListField<T> setVisibleRowCount(int count)
      Sets the desired visible row count. The default count is 4.

    • getSelectedIndexes

      public int[] getSelectedIndexes()
      Returns an array of selected item indexes.

    • setSelectedIndexes

      public ListField<T> setSelectedIndexes(int[] selection)
      Sets the selected indexes for the list. Note: this may not do what you expect it to do depending on the current selection mode (default selection mode is MULTIPLE_INTERVAL_SELECTION, which allows multiple non-contiguous items to be selected).

      Passing null or an empty list will clear the selection.

    • setSelectedIndex

      public ListField<T> setSelectedIndex(int index)
      Sets a specific list index to select. If out of bounds, this call is ignored.

    • getList

      public JList<T> getList()
      Provides direct access to the underlying JList if needed.

    • getListModel

      public DefaultListModel<T> getListModel()
      Provides direct access to the underlying ListModel. By default (unless the constructor was given something else), this will return a DefaultListModel<T> instance.

    • addListDataListener

      public ListField<T> addListDataListener(ListDataListener listener)
      A convenience method to add a ListDataListener to the underlying ListModel. Important: If you add a ValueChangedListener to this ListField, that listener will only be notified when the selection changes, not when the list data changes. If you need to be notified when the list data changes, you must add a ListDataListener to the ListModel. This method makes that a bit easier.

    • removeListDataListener

      public ListField<T> removeListDataListener(ListDataListener listener)
      Convenience method to remove a ListDataListener from the underlying ListModel.

    • setCellRenderer

      public ListField<T> setCellRenderer(ListCellRenderer<T> renderer)
      You can optionally set a custom cell renderer if your list items have special display requirements.

    • getCellRenderer

      public ListCellRenderer<? super T> getCellRenderer()
      Returns the effective list cell renderer.

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

    • setFixedCellWidth

      public ListField<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.

    • setShouldExpand

      public void setShouldExpand(boolean should)
      Sets whether this list should expand horizontally to fill available form panel width. The default is false, meaning the list will be just wide enough to display the longest item.

    • isMultiLine

      public boolean isMultiLine()
      ListFields occupy more than one form row (generally - you can of course set a visibleRowCount of 1, but why would you do that).
      Overrides:
      isMultiLine in class FormField

    • shouldExpand

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

    • getButtonPosition

      public ListField.ButtonPosition getButtonPosition()
      Gets the position of the button panel (above or below the list).

    • setButtonPosition

      public ListField<T> setButtonPosition(ListField.ButtonPosition position)
      Sets the position of the button panel (above or below the list).

    • addButton

      public ListField<T> addButton(Action action)
      Adds an Action to the button panel. This will cause the button panel to become visible if it was not already.

    • setButtonPanelBorder

      public ListField<T> setButtonPanelBorder(Border border)
      Allows callers to set a border on the button panel. The default is no border.

    • getButtonPreferredSize

      public Dimension getButtonPreferredSize()
      Gets the preferred size of buttons in the button panel, or null if buttons should size to their content.

    • setButtonPreferredSize

      public ListField<T> setButtonPreferredSize(Dimension dim)
      Allow changing the preferred size of buttons in the button panel. By default, buttons will size to their content.

    • getButtonAlignment

      public int getButtonAlignment()
      One of FlowLayout's alignment options: LEFT, CENTER, RIGHT, LEADING, or TRAILING from the FlowLayout class.

    • setButtonAlignment

      public ListField<T> setButtonAlignment(int alignment)
      One of FlowLayout's alignment options: LEFT, CENTER, RIGHT, LEADING, or TRAILING from the FlowLayout class.

    • getButtonHgap

      public int getButtonHgap()
      Gets the horizontal gap between buttons.

    • getButtonVgap

      public int getButtonVgap()
      Gets the vertical gap between the list and the button panel.

    • setButtonHgap

      public ListField<T> setButtonHgap(int hgap)
      Sets the horizontal gap between buttons, and between buttons and the edge of the containing panel.

    • setButtonVgap

      public ListField<T> setButtonVgap(int vgap)
      Sets the vertical gap between buttons, and between buttons and the edge of the containing panel.

    • setButtonLayout

      public ListField<T> setButtonLayout(int alignment, int hgap, int vgap)
      A convenience method to set alignment, hgap, and vgap all at once.
      Parameters:
      alignment - One of the FlowLayout alignment options: LEFT, CENTER, RIGHT, LEADING, or TRAILING
      hgap - The horizontal gap between buttons, in pixels
      vgap - The vertical gap between the buttons and the list, in pixels
      Returns:
      this ListField instance, for call chaining

    • createDefaultListModel

      protected static <T> DefaultListModel<T> createDefaultListModel(List<T> items)