Package swingtree

Class UIForList<E,L extends JList<E>>

java.lang.Object
swingtree.UIForAnything<UIForList<E,L>,L,JComponent>
swingtree.UIForAnySwing<UIForList<E,L>,L>
swingtree.UIForList<E,L>
Type Parameters:
L - The type of the JList instance which will be managed by this builder.
public final class UIForList<E,L extends JList<E>> extends UIForAnySwing<UIForList<E,L>,L>
A SwingTree builder node designed for configuring JList instances.

Please take a look at the living swing-tree documentation where you can browse a large collection of examples demonstrating how to use the API of this class.

  • Method Details

    • _state

      protected swingtree.BuilderState<L> _state()
      Description copied from class: UIForAnything
      Returns the state of the builder, which is a container for the wrapped component as well as it's type and current EventProcessor.
      Specified by:
      _state in class UIForAnything<UIForList<E,L extends JList<E>>,L extends JList<E>,JComponent>
      Returns:
      The state of the builder.

    • _newBuilderWithState

      protected UIForList<E,L> _newBuilderWithState(swingtree.BuilderState<L> newState)
      Description copied from class: UIForAnything
      An internal wither method which creates a new builder instance with the provided BuilderState stored inside it.
      Specified by:
      _newBuilderWithState in class UIForAnything<UIForList<E,L extends JList<E>>,L extends JList<E>,JComponent>
      Parameters:
      newState - The new state which should be stored inside the new builder instance.
      Returns:
      A new builder instance with the provided state stored inside it.

    • withEntries

      public final UIForList<E,L> withEntries(List<E> entries)
      Takes the provided list of entry objects and sets them as JList data.
      Parameters:
      entries - The list of entries to set as data.
      Returns:
      This instance of the builder node.

    • withEntries

      @SafeVarargs public final UIForList<E,L> withEntries(E... entries)
      Takes the provided array of entry objects and sets them as JList data.
      Parameters:
      entries - The array of entries to set as data.
      Returns:
      This instance of the builder node.

    • withEntries

      public final UIForList<E,L> withEntries(sprouts.Vals<E> entries)
      Takes the provided observable property list of entries in the form of a Vals object and uses them as a basis for modelling the JList data. If the Vals object changes, the JList data will be updated accordingly, and vice versa.
      Parameters:
      entries - The Vals of entries to set as data model.
      Returns:
      This instance of the builder node to allow for builder-style fluent method chaining.

    • withSelection

      public final UIForList<E,L> withSelection(sprouts.Var<E> selection)
      Takes an observable property in the form of a Var object and uses it as a basis for modelling the JList selection. If the Var object changes, the JList selection will be updated accordingly, and vice versa. If you do not want this relationship to be bidirectional, use withSelection(Val) instead.
      Parameters:
      selection - The Var of entries to set as selection model.
      Returns:
      This instance of the builder node to allow for fluent method chaining.

    • withSelection

      public final UIForList<E,L> withSelection(sprouts.Val<E> selection)
      Takes an observable read-only property in the form of a Val object and uses it as a basis for modelling the JList selection. If the Val object changes, the JList selection will be updated accordingly. However, if the JList selection changes due to user interaction, the Val object will not be updated.
      Parameters:
      selection - The Val of entries to set as selection model.
      Returns:
      This instance of the builder node to allow for fluent method chaining.

    • withRenderComponent

      public final UIForList<E,L> withRenderComponent(ListEntryRenderer<E,L> renderer)
      The ListEntryRenderer passed to this method is a functional interface receiving a ListEntryDelegate instance and returns a JComponent, which is used to render each entry of the JList instance.
      A typical usage of this method would look like this: 
      
   listOf(vm.colors())
   .withRenderComponent( it -> new Component() {
     {@literal @}Override
     public void paint(Graphics g) {
       g.setColor(it.entry().orElse(Color.PINK));
       g.fillRect(0,0,getWidth(),getHeight());
     }
   })

      In this example, a new JList is created for the observable property list of colors, which is provided by the vm.colors() method. The entries of said list are individually exposed specified renderer lambda expression, which return a JComponent instance that is used by the JList to render each entry. In this case a colored rectangle is rendered for each entry.

      Note that the preferred way to build a list cell renderer for various item types is to use the withCell(Configurator) method, which provides a more rich and fluent builder API.

      Parameters:
      renderer - The ListEntryRenderer that will be used to supply JComponents responsible for rendering each entry of the JList instance.
      Returns:
      This instance of the builder node to allow for fluent method chaining.

    • onSelection

      public final UIForList<E,L> onSelection(sprouts.Action<ComponentDelegate<JList<E>,ListSelectionEvent>> action)
      Adds an Action event handler to the underlying JList through a ListSelectionListener, which will be called when a list selection has been made. {see JList#addListSelectionListener(ListSelectionListener)}.
      Parameters:
      action - The Action that will be notified.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withCellRenderer

      public final UIForList<E,L> withCellRenderer(ListCellRenderer<E> renderer)
      Sets the ListCellRenderer for the JList, which renders the list items by supplying a custom component for each item through the ListCellRenderer.getListCellRendererComponent(JList, Object, int, boolean, boolean) method.

      Also see withCells(Configurator) method, which is the preferred way to build a list cell renderer for various item types using a more rich and fluent builder API.

      Parameters:
      renderer - The ListCellRenderer that will be used to paint each cell in the list.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withCells

      public final <V extends E> UIForList<E,L> withCells(Configurator<CellBuilder<L,V>> renderBuilder)
      Use this to build a list cell renderer for various item types by defining a renderer for each type or using Object as a common type using the fluent builder API exposed to the Configurator lambda function passed to this method.
      This method is typically used when the list holds inhomogeneous item types which you want to be handled differently in the list view. 
      
  UI.list(new Object[]{":-)", 42L, 'ยง'})
  .withCells( it -> it
      .when(String.class).asText( cell -> "String: "+cell.getValue() )
      .when(Character.class).asText( cell -> "Char: "+cell.getValue() )
      .when(Number.class).asText( cell -> "Number: "+cell.getValue() )
  );
      Note that a similar API is also available for the JComboBox and JTable components, see UIForCombo.withCells(Configurator), UIForTable.withCells(Configurator) and UIForTable.withCellsForColumn(int, Configurator) for more information.

      Also see withCell(Configurator) method, which constitutes the preferred way to build a list cell renderer as it is simpler, more concise and less error-prone.

      Type Parameters:
      V - The type of the value that is being rendered in this combo box.
      Parameters:
      renderBuilder - A lambda function that configures the renderer for this combo box.
      Returns:
      This combo box instance for further configuration.

    • withCell

      public final <V extends E> UIForList<E,L> withCell(Configurator<CellConf<L,V>> cellConfigurator)
      Allows for the configuration of a cell view for the items of the JList instance. The Configurator lambda function passed to this method receives a CellConf exposing the current item value and the current selection state of the cell. You may update return an updated cell with a desired view component through methods like CellConf.view(Component) or CellConf.updateView(Configurator).

      Here code snippet demonstrating how this method may be used as part of a UI declaration: 

      
      UI.list(new Month[]{Month.JANUARY, Month.FEBRUARY, Month.MARCH})
      .withCell( cell -> cell
          .updateView( comp -> comp
              .orGet(JLabel::new) // initialize a new JLabel if not already present
              .updateIf(JLabel.class, tf -> {
                  tf.setText(cell.valueAsString().orElse(""));
                  tf.setBackground(cell.isSelected() ? Color.YELLOW : Color.WHITE);
                  return tf;
              })
          )
      )
      In this example, a new JList is created for an array of objects. The Configurator lambda function passed to the withCell(Configurator) method configures the cell view for each item in the list.
      Type Parameters:
      V - The type of the value that is being rendered in this combo box.
      Parameters:
      cellConfigurator - The Configurator lambda function that configures the cell view.
      Returns:
      This instance of the builder node to allow for fluent method chaining.