Package swingtree

Class CellConf<C extends JComponent,V>

java.lang.Object
swingtree.CellConf<C,V>
Type Parameters:
V - The entry type of the entry of this CellConf.
public final class CellConf<C extends JComponent,V> extends Object
This class models the state of an individual table/tree/list/drop down cell alongside various properties that a cell should have, like for example the value of the cell, its position within the component as well as a view() (renderer/editor) in the form of an AWT Component which may or may not be replaced or modified.
The CellConf is exposed to the RenderAs.as(Configurator) method after a CellBuilder.when(Class) call as part of various cell builder APIs like:
When configuring your cell, you may use methods like view(Component) or renderer(Size,Consumer) to define how the cell should be rendered.

Note that the isEditing() flag determines two important modes in which this class is exposed to RenderAs.as(Configurator). If the isEditing() is true, then you are expected to configure a cell editor component for the view() property. If the isEditing() is false, then you are expected to configure a simple cell renderer component as the view() property.
Note that for each state of the isEditing() flag, the view component is persisted across multiple calls to the RenderAs.as(Configurator) method.

This design allows you to easily define and continuously update both a renderer and an editor for a cell on a single call to the RenderAs.as(Configurator) method, and then to update the renderer or editor in every subsequent call to the same method.

  • Method Details

    • getHost

      public C getHost()
      Returns the parent/host of this cell, i.e. the component which contains this cell, like a JComboBox, JTable or JList
      Returns:
      The owner of this cell, typically a table, list or combo box.

    • getListView

      public Optional<JList<?>> getListView()
      Some host components (see getHost(), use a JList in their look and feel to render cells. This is the case for the JComboBox component, which has a drop-down popup that is rendered through an internal JList which you can access through this method.

      But note that this JList is returned through an Optional because it may not exist for other host components like a JTable or JTree. In case of this cell being directly used for a JList, through UIForList.withCell(Configurator) or UIForList.withCells(Configurator), then both getHost() and this return the same JList instance.

      Returns:
      An optional containing a JList used for rendering this cell if this is called by a ListCellRenderer, and an Optional.empty() otherwise.

    • entry

      public Optional<V> entry()
      Returns the entry of this cell, which is the data that this cell represents. The entry is wrapped in an Optional to indicate that the entry may be null. A cell entry is typically a string, number or custom user object.
      Returns:
      An optional of the entry of this cell, or an empty optional if the entry is null.

    • entryAsString

      public String entryAsString()
      Returns the entry of this cell as a string. If the entry is null, then an empty string is returned. This method is useful when you want to display the entry of the cell as a string, and do not have a special meaning assigned to null entries. (Which is the preferred way to handle null entries)
      Returns:
      The entry of this cell as a string, or an empty string if the entry is null. Note that the string representation of the entry is obtained by calling the Object.toString() method on the entry.

    • isSelected

      public boolean isSelected()
      The flag returned by this method indicates whether this cell is selected or not. A cell is selected when the user interacts with it, like clicking on it or navigating to it using the keyboard. You may want to use this flag to change the appearance of the cell when it is selected. For example, you may want to highlight the cell by changing its background color.
      Returns:
      True if the cell is selected, false otherwise.

    • hasFocus

      public boolean hasFocus()
      Just like any other component, a cell may have focus or not. The focus is typically indicated by a border around the cell. It is an important property to consider when designing your cell renderer, as you may want to change the appearance of the cell when it has focus.
      Returns:
      True if the cell has focus, false otherwise.

    • isEditing

      public boolean isEditing()
      This method returns true if the cell is currently being edited. A cell is typically edited when the user double-clicks on it or presses the F2 key. When a cell is being edited, then the cell renderer wrapped by this cell will be used as an editor. You may want to use this flag to change the appearance of the cell when it is being edited. For example, you may want to show a text field instead of a label when the cell is being edited.
      Returns:
      True if the cell is being edited, false otherwise. Note that you can reliably say that when this flag is true, then the cell builder is being used to construct or maintain an editor.

    • isExpanded

      public boolean isExpanded()
      This method returns true if the cell is expanded, i.e. if it is a parent cell in a JTree. You may want to use this flag to change the appearance of the cell when it is expanded.You may, for example, want to show a different icon when the cell is expanded.
      Returns:
      True if the cell is expanded, false otherwise.

    • isLeaf

      public boolean isLeaf()
      This method returns true if the cell is a leaf, i.e. if it is a child cell in a JTree. You may want to use this flag to change the appearance of the cell when it is a leaf. You may, for example, want to show a different icon when the cell is a leaf.
      Returns:
      True if the cell is a leaf, false otherwise.

    • toolTips

      public List<String> toolTips()
      Exposes a list of tool tips that should be shown when the user hovers over the cell. The tool tips are strings that provide additional information about the cell to the user.
      Returns:
      An unmodifiable list of tool tips that should be shown when the user hovers over the cell.

    • row

      public int row()
      Gives you the row index of the cell in the table, list or drop down. It tells you the location of the cell in the vertical direction.
      Returns:
      The row index of the cell in the table, list or drop down.

    • column

      public int column()
      Gives you the column index of the cell in the table, list or drop down. It tells you the location of the cell in the horizontal direction.
      Returns:
      The column index of the cell in the table, list or drop down.

    • view

      public OptionalUI<Component> view()
      Returns the renderer/editor of this cell, which is the component that is used to display the cell to the user. The view is typically a label, text field or some other custom component. It is wrapped in an Optional to clearly indicate that it may be null.
      Note that in case of the isEditing() method returning true, the view component stored in this cell is used as an editor. If the cell is not being edited, then the component is used as a renderer.
      Two components are persisted across multiple calls to the CellBuilders RenderAs.as(Configurator) method, one for the renderer and one for the editor. (So technically there are two views)
      Also note that not all types of components are suitable to be used as editors. For example, a label is not suitable to be used as an editor. Instead, you should use a text field or a combo box as an editor.
      If a component is not suitable to be used as an editor, then it will simply be ignored in exchange for a default editor.
      Returns:
      An optional of the view of this cell, or an empty optional if the view is null. In case of the isEditing() method returning true, the component stored in this optional is used as an editor. The cell will remember the renderer and editor components across multiple calls to the CellBuilders RenderAs.as(Configurator) method.

    • updateView

      public CellConf<C,V> updateView(Configurator<OptionalUI<Component>> configurator)
      Allows you to configure the view of this cell by providing a configurator lambda, which takes an OptionalUI of the current renderer and returns a (potentially updated) OptionalUI of the new renderer.
      The benefit of using this method is that you can easily initialize the renderer with a new component through the OptionalUI.orGetUi(Supplier) method, and then update it in every refresh coll inside the OptionalUI.update(java.util.function.Function) method.
      This may look like the following: 
      
      UI.table()
      .withCell(cell -> cell
          .updateView( comp -> comp
              .update( r -> { r.setText(cell.entryAsString()); return r; } )
              .orGetUi( () -> UI.textField(cell.entryAsString()).withBackground(Color.CYAN) )
          )
      )
      // ...
      In this example, the view is initialized with a text field if it is not present, and then the text field is continuously updated with the entry of the cell.
      Parameters:
      configurator - The Configurator lambda which takes an OptionalUI of the current view and returns a (potentially updated or initialized) OptionalUI of the new view.
      Returns:
      An updated cell delegate object with the new view. If the configurator returns an empty optional, then the view of the cell will be reset to null.

    • view

      public CellConf<C,V> view(Component component)
      Creates an updated cell delegate object with the given component as the view (renderer/editor) of the cell. view is the component that is used to render the cell to the user. It is typically a label, text field or some other custom component.
      Note that in case of the isEditing() method returning true, this CellConf is used for constructing or maintaining an editor. If the cell is not being edited, then this CellConf is used for rendering.
      Either way, the component is memorized across multiple calls to the CellBuilders RenderAs.as(Configurator) method.
      A typical usage of this method may look something like this: 
      
      UI.table()
      .withCell(cell -> cell
          .view(new JLabel("Hello, World!" + cell.row()) )
      )
      // ...
      But keep in mind that in this example the label will be recreated on every refresh call, which is not very efficient. It is better to use the updateView(Configurator) method to initialize the view once and then update it in every refresh call.
      Parameters:
      component - The component to be used as the view of the cell.
      Returns:
      An updated cell delegate object with the new view to serve as the renderer/editor of the cell.

    • renderer

      public CellConf<C,V> renderer(Size cellSize, Consumer<Graphics2D> painter)
      Creates an updated cell delegate object with the supplied cell size and painter as the view (renderer/editor) of the cell. The painter is a lambda that takes a Graphics2D object and paints the cell with it. This method is useful when you want to create a custom cell renderer that paints the cell in a specific way. For example, you may want to paint the cell with a gradient background or a custom border.
      Note that in case of the isEditing() method returning true, this CellConf is used for constructing or maintaining an editor. If the cell is not being edited, then this CellConf is used for rendering.
      Either way, the component is memorized across multiple calls to the CellBuilders RenderAs.as(Configurator) method.
      Parameters:
      cellSize - The minimum and preferred size of the cell to be painted.
      painter - The lambda that paints the cell with a Graphics2D object.
      Returns:
      An updated cell delegate object with the new view to serve as the renderer/editor of the cell.

    • viewDefault

      public CellConf<C,V> viewDefault()
      Creates an updated cell delegate object with the default cell view / renderer component based on the DefaultListCellRenderer, DefaultTableCellRenderer and DefaultTreeCellRenderer classes.
      Returns:
      An updated cell delegate object with the default view component. This will override any custom view that was previously specified.

    • _withRenderer

      public CellConf<C,V> _withRenderer(@Nullable Component component)

    • toolTip

      public CellConf<C,V> toolTip(String toolTip)
      Creates a cell with an additional tool tip to be shown when the user hovers over the cell. The tool tips are strings that provide additional information about the cell to the user.
      Parameters:
      toolTip - The tool tip to be added to the list of tool tips.
      Returns:
      An updated cell delegate object with the new tool tip.

    • presentationEntry

      public Optional<Object> presentationEntry()
      The presentation entry is the first choice of the default cell view to be used for rendering and presentation to the user. If it does not exist then the regular cell entry is used for rendering by the default view. Note that if you supply your own custom view/renderer component, then the presentation entry is ignored.
      Returns:
      An optional of the presentation entry. It may be an empty optional if no presentation entry was specified.

    • presentationEntry

      public CellConf<C,V> presentationEntry(@Nullable Object toBeShown)
      The presentation entry is the first choice of the default cell view to be used for rendering and presentation to the user. By default, this entry is null, in which case it does not exist the regular cell entry is used for rendering by the default view. Note that if you supply a presentation value, then SwingTree will try to apply this value to the view component. (Which includes the editor and renderer components)
      Parameters:
      toBeShown - The object which should be used by the renderer to present to the user, typically a String.
      Returns:
      An updated cell delegate object with the new presentation entry.

    • entryToPresentation

      public CellConf<C,V> entryToPresentation(Function<@Nullable V,@Nullable Object> presenter)
      The presentation entry is the first choice of the default cell view to be used for rendering and presentation to the user. A common use case is to convert the cell entry to a presentation entry that is more suitable for the default view. This method allows you to convert the cell entry to a presentation entry by applying a function to it. The function takes the cell entry as an argument and returns the presentation entry. Note that if you supply a presentation value, then SwingTree will try to apply this value to the view component. (Which includes the editor and renderer components)
      Parameters:
      presenter - The function that converts the cell entry to a presentation entry.
      Returns:
      An updated cell delegate object with the new presentation entry.
      Throws:
      NullPointerException - If the presenter function is null.