Package swingtree

Class UIForTree<I,N,T extends JTree>

java.lang.Object
swingtree.UIForAnything<UIForTree<I,N,T>,T,JComponent>
swingtree.UIForAnySwing<UIForTree<I,N,T>,T>
swingtree.UIForTree<I,N,T>
Type Parameters:
I - The identity type of the nodes, which selection paths are made of.
N - The common type of the nodes of the tree managed by this builder.
T - The type of the JTree instance which will be managed by this builder.
public final class UIForTree<I,N,T extends JTree> extends UIForAnySwing<UIForTree<I,N,T>,T>
A SwingTree builder node designed for configuring JTree instances.

The recommended way to get one is UIFactoryMethods.tree(Var, Configurator), which binds the tree to a single property holding a deeply immutable, nested data structure and a TreeConf saying which parts of it to zoom into: 


  UI.tree(fileSystem, conf -> conf
      .nodesOf(Dir.class, dir -> dir
          .children(Dir::entries, Dir::withEntries)
          .text(Dir::name, Dir::withName)
      )
      .nodesOf(Doc.class, doc -> doc.text(Doc::name))
  )
  .withSelection(selectedNode);
Where the data has no single root but several top level nodes, UIFactoryMethods.trees(Var, Configurator) binds a Var<Tuple<N>> of them instead. The builder returned is this same one, and everything below configures both forms alike.

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<T> _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<UIForTree<I,N,T extends JTree>,T extends JTree,JComponent>
      Returns:
      The state of the builder.

    • _newBuilderWithState

      protected UIForTree<I,N,T> _newBuilderWithState(swingtree.BuilderState<T> 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<UIForTree<I,N,T extends JTree>,T extends JTree,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.

    • withModel

      public final UIForTree<I,N,T> withModel(TreeModel model)
      Installs a plain Swing TreeModel, which is the escape hatch for a tree whose contents genuinely do not live in a property, or which already has a model you want to keep. A tree installed like this takes no part in any of the property binding this builder otherwise offers.

      Installing one on a tree built by UI.tree(rootProperty, ..) replaces the bound model, which leaves the binding with nothing to drive; SwingTree says so in the log rather than leaving you to work out why the tree stopped following the property. Build the tree with UIFactoryMethods.of(JTree) instead when the contents are not a property.

      Parameters:
      model - The TreeModel to install.
      Returns:
      This builder node, to allow for method chaining.

    • withSelection

      public final UIForTree<I,N,T> withSelection(sprouts.Var<sprouts.Tuple<I>> selection)
      Binds the selected position of the tree to a mutable property holding a path of ids, which keeps the two in sync in both directions: selecting a node writes the path leading to it into the property, and assigning a path selects the node it names, opening every branch above it and scrolling it into view. 
      
  Var<Tuple<String>> selectedPath = vm.zoomTo(Move::selectedPath, Move::withSelectedPath);

  UI.tree(move, conf -> ..).withSelection(selectedPath);
  //  nothing selected   ->  Tuple.of(String.class)
  //  the root           ->  ["move"]
  //  the kettle         ->  ["move", "kitchen", "appliances", "kettle"]
      A selection is a position, and only a path names a position. A node value cannot: the same value may sit in several places at once, and a tree only requires its ids to be unique among siblings, so two folders may each hold a notes.txt. A path of ids has nothing to be ambiguous about, needs no search to resolve, and carries no data which could contradict the tree.

      The empty tuple means nothing is selected, so there is no null to handle. To get at the node a path names — for a detail view, say — ask the configuration: TreeConf.nodeAt(Object, Tuple) and TreeConf.nodesAlong(Object, Tuple).

      On a tree bound through UIFactoryMethods.trees(Var, Configurator) the first id names a top level node rather than a root, so its paths are one element shorter and no path at all names the forest. Resolve them with TreeConf.nodeAt(Tuple, Tuple).

      Binding a single path this way also puts the tree into single selection mode. Use withSelectionPaths(Var) for a tree the user may select several nodes in.

      Parameters:
      selection - A property holding the ids leading to the selected node.
      Returns:
      This builder node, to allow for method chaining.

    • withSelection

      public final UIForTree<I,N,T> withSelection(sprouts.Val<sprouts.Tuple<I>> selection)
      Binds the selected position of the tree to a read only property holding a path of ids, so that the tree follows the property but a selection made by the user is not written back. See withSelection(Var) for why a selection is a path.
      Parameters:
      selection - A read only property holding the ids leading to the selected node.
      Returns:
      This builder node, to allow for method chaining.

    • withSelectionPaths

      public final UIForTree<I,N,T> withSelectionPaths(sprouts.Var<sprouts.Tuple<sprouts.Tuple<I>>> selection)
      Binds every selected position of the tree to a mutable property holding one path of ids per selected node, which also puts the tree into a mode where the user may select any number of nodes. The two stay in sync in both directions, just like withSelection(Var).
      Parameters:
      selection - A property holding one path of ids per selected node.
      Returns:
      This builder node, to allow for method chaining.

    • onSelection

      public final UIForTree<I,N,T> onSelection(sprouts.Action<TreeSelectionDelegate<I,N>> action)
      Registers an action which is invoked whenever the selection of the tree changes. The action receives a TreeSelectionDelegate speaking in your own node values, so there is never a reason to reach into the tree's own path objects. 
      
  UI.tree(fileSystem, conf -> ..)
  .onSelection( it -> it.lead().ifPresent(node -> open(node)) );
      For the common case of mirroring the selection into a view model, prefer withSelection(Var), which needs no action at all.
      Parameters:
      action - The action to invoke when the selection changes.
      Returns:
      This builder node, to allow for method chaining.

    • withRootVisible

      public final UIForTree<I,N,T> withRootVisible(boolean rootVisible)
      Decides whether the root node of the bound structure is drawn as a row of its own. Hiding it also turns on the handles of the level below, so that what is now the first visible level can still be opened.

      A tree bound through UIFactoryMethods.trees(Var, Configurator) has no root node, so there is nothing here to show: showing it is ignored and reported in the log, and hiding it was already the case.

      Parameters:
      rootVisible - True to show the root node.
      Returns:
      This builder node, to allow for method chaining.

    • isRootVisibleIf

      public final UIForTree<I,N,T> isRootVisibleIf(sprouts.Val<Boolean> rootVisible)
      Binds the visibility of the root node to a property, so that the tree can fold its root away and back in response to application state. A tree bound through UIFactoryMethods.trees(Var, Configurator) has no root node, so see withRootVisible(boolean) for what happens there.
      Parameters:
      rootVisible - A property telling whether the root node should be shown.
      Returns:
      This builder node, to allow for method chaining.

    • withRootHandlesVisible

      public final UIForTree<I,N,T> withRootHandlesVisible(boolean showsRootHandles)
      Decides whether the handles which expand and collapse a branch are drawn next to the top level nodes as well. Hiding the root turns these on, because they are then the only handles there are — and turning them off again on a tree with no visible root leaves the user nothing to click, so only do that where expansion is driven from code.
      Parameters:
      showsRootHandles - True to draw handles next to the top level nodes.
      Returns:
      This builder node, to allow for method chaining.

    • withRowHeight

      public final UIForTree<I,N,T> withRowHeight(int rowHeight)
      Sets the height of every row of the tree, in the same scale independent developer pixels the rest of SwingTree speaks in. Pass 0 to let each row take the height its own cell view asks for.
      Parameters:
      rowHeight - The height of a row.
      Returns:
      This builder node, to allow for method chaining.

    • withInitialExpansionDepth

      public final UIForTree<I,N,T> withInitialExpansionDepth(int depth)
      Expands every branch down to the given depth, once, at the point this builder method runs, where a depth of 1 opens the topmost visible level, 2 the level below that as well, and so on. This is a convenience for the initial view only: expansion the user performs afterwards is untouched by it, and so is everything the bound property grows later.

      Depth is counted from what is on screen, so a root hidden with withRootVisible(boolean) — and the absent root of a forest — does not count as a level. Call this after hiding the root, so that it knows.

      Parameters:
      depth - How many visible levels to expand.
      Returns:
      This builder node, to allow for method chaining.

    • withCells

      public final <V extends N> UIForTree<I,N,T> withCells(Configurator<CellBuilder<T,V>> renderBuilder)
      Use this to build a cell renderer covering several node types at once, through the same fluent API the list, combo box and table components expose: 
      
  UI.tree(fileSystem, conf -> ..)
  .withCells( it -> it
      .when(Dir.class).asText( cell -> cell.entry().map(Dir::name).orElse("") )
      .when(Doc.class).asComponent( cell -> myFancyRow(cell) )
  );
      Note that for a label and an icon there is no need to come here at all: declare them as part of the node's own rule with TreeNodeConf.text(java.util.function.Function) and TreeNodeConf.icon(java.util.function.Function). Reach for this method when a node needs a view a label cannot give it.

      The two mix freely: a node type this builder says nothing about keeps the label, icon and tool tip declared in its own rule, so covering one type here does not oblige you to cover the rest.

      Type Parameters:
      V - The type of the node values being rendered.
      Parameters:
      renderBuilder - Configures the cell renderer.
      Returns:
      This builder node, to allow for method chaining.

    • withCell

      public final <V extends N> UIForTree<I,N,T> withCell(Configurator<CellConf<T,V>> cellConfigurator)
      Configures a single cell view used for every node of the tree, which is the shorter form of withCells(Configurator) when there is no need to distinguish between node types.
      Type Parameters:
      V - The type of the node values being rendered.
      Parameters:
      cellConfigurator - Configures the cell view.
      Returns:
      This builder node, to allow for method chaining.

    • withCellRenderer

      public final UIForTree<I,N,T> withCellRenderer(TreeCellRenderer renderer)
      Installs a plain Swing TreeCellRenderer. A bound tree keeps internal handles inside its paths, so the renderer is wrapped in one which unwraps them first: what reaches your renderer is always your own node value.

      A renderer installed this way answers for every node, so the text(..), icon(..) and toolTip(..) rules declared per node type no longer apply. Use withCells(Configurator) to cover only some node types and leave the rest to their own rules.

      Parameters:
      renderer - The renderer to paint the nodes with.
      Returns:
      This builder node, to allow for method chaining.

    • withCellEditor

      public final UIForTree<I,N,T> withCellEditor(TreeCellEditor editor)
      Installs a plain Swing TreeCellEditor, replacing the in place rename the TreeNodeConf.text(java.util.function.Function, java.util.function.BiFunction) rule installs by itself.
      Parameters:
      editor - The editor to edit the nodes with.
      Returns:
      This builder node, to allow for method chaining.