Module is.codion.common.model
Package is.codion.common.model.component.tree

Interface TreeSelection<T>

Type Parameters:
T - the item type
All Superinterfaces:
MultiSelection<T>, SingleSelection<T>
All Known Subinterfaces:
FilterTreeSelection<T>
public interface TreeSelection<T> extends MultiSelection<T>

The selection of a FilterTreeModel, over its visible nodes, addressed by row via the indexes, by item via the items, and by node via path() and paths().

The same item may appear in several places in a tree. Selecting by item selects one node holding it, while the paths address particular nodes. A node hidden below a collapsed ancestor, selected by item or by path, has its ancestors expanded, so that it can be selected right away. A node not yet in the model, its parent not loaded, is selected via set(NodePath), which loads as needed and selects it once it is visible, or by item, in case the model provides the paths of items, see FilterTreeModel.Builder.path(Function).

See Also:

  • Method Details

    • item

      Value<T> item()

      Returns the Value controlling the selected item.

      Notifies when the selected item changes, and when the instance the selection refers to is replaced, as happens when the items are refreshed or replaced, the replacement being the same item by equals() but not the same object.

      Setting an item selects one node holding it, in order of preference:

      1. a visible node holding the same instance, an already selected one first, keeping the selection in place
      2. a visible node holding an equal item, an already selected one first
      3. a node hidden below a collapsed ancestor, one holding the same instance, otherwise the first one holding an equal item, depth first, its ancestors expanded
      An item not in the model, or excluded, clears the selection. Use path() for a particular node, and set(NodePath) for a node not yet loaded.

      A change vetoed via MultiSelection.changing() leaves the ancestors expanded.

      The selection moving between nodes holding the same item instance changes path(), not the item.

      Specified by:
      item in interface SingleSelection<T>
      Returns:
      the Value controlling the selected item

    • items

      MultiSelection.Items<T> items()

      The items of the selected nodes, in row order, an item selected in several places appearing once for each.

      Each item set or added selects a node of its own, as item() does, an item not in the model having its ancestors expanded and loaded in case the model provides its path, ignoring an item not in the model otherwise, or excluded, while MultiSelection.Items.remove(Object) and MultiSelection.Items.contains(Object) cover every selected node holding it, so that set(get()) leaves the selection as is. Restoring prefers neither selected nor hidden nodes. Use paths() for particular nodes.

      Specified by:
      items in interface MultiSelection<T>
      Returns:
      the selected items, the items of the selected nodes

    • path

      Value<NodePath<T>> path()

      The path of the selected node, as item() is its item.

      Setting the path of a node hidden below a collapsed ancestor expands its ancestors and selects it, while the path of a node not in the model, or excluded, clears the selection. Use set(NodePath) for a node not yet loaded.

      Returns:
      the Value controlling the path of the selected node

    • paths

      MultiSelection.Items<NodePath<T>> paths()

      The paths of the selected nodes, in row order, as items() are their items.

      Setting or adding the paths of nodes hidden below collapsed ancestors expands their ancestors and selects them, while the paths of nodes not in the model, or excluded, are ignored. Use set(NodePath) for a node not yet loaded.

      Returns:
      the MultiSelection.Items controlling the paths of the selected nodes

    • set

      void set(NodePath<T> path)

      Selects the node identified by the given path once it is visible, replacing the selection, expanding its ancestors and loading as needed. The node itself is not expanded. Where path() takes effect right away, on a node in the model, this takes effect once the nodes on the path have been loaded, before this method returns when loading synchronously.

      A node which exists but is not visible, being excluded or below a node collapsed since, is replaced by its nearest visible ancestor. In case the path turns out not to exist, or can not be loaded further, a load failing or a node being a leaf according to the leaves function, the deepest node on the path which does exist is selected, or its nearest visible ancestor. The selection is left as is in case no node on the path is in the model.

      A pending selection is cancelled by a selection change from outside, by the application or the user, and replaced by another one, while loading and refreshing do not cancel it. A selection change vetoed via MultiSelection.changing() ends it unselected.

      Parameters:
      path - the path of the node to select
      Throws:
      IllegalArgumentException - in case of the root path
      See Also: