Module org.apache.sis.gui
Package org.apache.sis.gui.dataset

# Class ResourceTree

Object
Node
Parent
Region
Control
TreeView<Resource>
ResourceTree

All Implemented Interfaces:
  `Styleable`, `EventTarget`, `Skinnable`

public class ResourceTree extends TreeView<Resource>
A view of data `Resource`s organized as a tree. This view can be used for showing the content of one or many `DataStore`s. A resource can be added by a call to `addResource(Resource)` or loaded from a file by `loadResource(Object)`.

`ResourceTree` registers the necessarily handlers for making this view a target of "drag and drop" events. Users can drop files or URLs for opening data files.

## Limitations

- The `rootProperty` should be considered read-only. For changing content, use the `setResource(Resource)` instead.
- If the user selects "close" in the contextual menu, the resource is unconditionally closed (if it is an instance of `DataStore`). There is not yet a mechanism for keeping it open if the resource is shared by another `ResourceTree` instance.

Since:
  1.1

- ## Property Summary

  ### Properties inherited from class TreeView

  `cellFactory, editable, editingItem, expandedItemCount, fixedCellSize, focusModel, onEditCancel, onEditCommit, onEditStart, onScrollTo, root, selectionModel, showRoot`

  ### Properties inherited from class Control

  `contextMenu, skin, tooltip`

  ### Properties inherited from class Region

  `background, border, cacheShape, centerShape, height, insets, maxHeight, maxWidth, minHeight, minWidth, opaqueInsets, padding, prefHeight, prefWidth, scaleShape, shape, snapToPixel, width`

  ### Properties inherited from class Parent

  `needsLayout`

  ### Properties inherited from class Node

  `accessibleHelp, accessibleRoleDescription, accessibleRole, accessibleText, blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effectiveNodeOrientation, effect, eventDispatcher, focused, focusTraversable, focusVisible, focusWithin, hover, id, inputMethodRequests, layoutBounds, layoutX, layoutY, localToParentTransform, localToSceneTransform, managed, mouseTransparent, nodeOrientation, onContextMenuRequested, onDragDetected, onDragDone, onDragDropped, onDragEntered, onDragExited, onDragOver, onInputMethodTextChanged, onKeyPressed, onKeyReleased, onKeyTyped, onMouseClicked, onMouseDragEntered, onMouseDragExited, onMouseDragged, onMouseDragOver, onMouseDragReleased, onMouseEntered, onMouseExited, onMouseMoved, onMousePressed, onMouseReleased, onRotate, onRotationFinished, onRotationStarted, onScrollFinished, onScroll, onScrollStarted, onSwipeDown, onSwipeLeft, onSwipeRight, onSwipeUp, onTouchMoved, onTouchPressed, onTouchReleased, onTouchStationary, onZoomFinished, onZoom, onZoomStarted, opacity, parent, pickOnBounds, pressed, rotate, rotationAxis, scaleX, scaleY, scaleZ, scene, style, translateX, translateY, translateZ, viewOrder, visible`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class TreeView

  `TreeView​.EditEvent<T>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final ObjectProperty<EventHandler<ResourceEvent>>`
  `onResourceClosed`
  Function to be called after a resource has been closed from a file or URL.
  `final ObjectProperty<EventHandler<ResourceEvent>>`
  `onResourceLoaded`
  Function to be called after a resource has been loaded from a file or URL.

  ### Fields inherited from class Region

  `USE_COMPUTED_SIZE, USE_PREF_SIZE`

  ### Fields inherited from class Node

  `BASELINE_OFFSET_SAME_AS_HEIGHT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ResourceTree()`
  Creates a new tree of resources with initially no resource to show.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `addResource(Resource resource)`
  Adds a resource in this tree below previously added resources.
  `Resource`
  `getResource()`
  Returns the root `Resource` of this tree.
  `void`
  `loadResource(Object source)`
  Loads in a background thread the resources from the given source, then adds the resource to this tree.
  `void`
  `removeAndClose(Resource resource)`
  Removes the given resource from this tree and closes the resource if it is a `DataStore` instance.
  `void`
  `setResource(Resource resource)`
  Sets the root `Resource` of this tree.

  ### Methods inherited from class TreeView

  `cellFactoryProperty, createDefaultSkin, edit, editableProperty, editAnyEvent, editCancelEvent, editCommitEvent, editingItemProperty, editStartEvent, expandedItemCountProperty, fixedCellSizeProperty, focusModelProperty, getCellFactory, getClassCssMetaData, getControlCssMetaData, getEditingItem, getExpandedItemCount, getFixedCellSize, getFocusModel, getNodeLevel, getOnEditCancel, getOnEditCommit, getOnEditStart, getOnScrollTo, getRoot, getRow, getSelectionModel, getTreeItem, getTreeItemLevel, isEditable, isShowRoot, layoutChildren, onEditCancelProperty, onEditCommitProperty, onEditStartProperty, onScrollToProperty, queryAccessibleAttribute, refresh, rootProperty, scrollTo, selectionModelProperty, setCellFactory, setEditable, setFixedCellSize, setFocusModel, setOnEditCancel, setOnEditCommit, setOnEditStart, setOnScrollTo, setRoot, setSelectionModel, setShowRoot, showRootProperty`

  ### Methods inherited from class Control

  `computeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, computePrefHeight, computePrefWidth, contextMenuProperty, executeAccessibleAction, getBaselineOffset, getContextMenu, getCssMetaData, getInitialFocusTraversable, getSkin, getTooltip, isResizable, setContextMenu, setSkin, setTooltip, skinProperty, tooltipProperty`

  ### Methods inherited from class Region

  `backgroundProperty, borderProperty, cacheShapeProperty, centerShapeProperty, getBackground, getBorder, getHeight, getInsets, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpaqueInsets, getPadding, getPrefHeight, getPrefWidth, getShape, getUserAgentStylesheet, getWidth, heightProperty, insetsProperty, isCacheShape, isCenterShape, isScaleShape, isSnapToPixel, layoutInArea, layoutInArea, layoutInArea, layoutInArea, maxHeight, maxHeightProperty, maxWidth, maxWidthProperty, minHeight, minHeightProperty, minWidth, minWidthProperty, opaqueInsetsProperty, paddingProperty, positionInArea, positionInArea, prefHeight, prefHeightProperty, prefWidth, prefWidthProperty, resize, scaleShapeProperty, setBackground, setBorder, setCacheShape, setCenterShape, setHeight, setMaxHeight, setMaxSize, setMaxWidth, setMinHeight, setMinSize, setMinWidth, setOpaqueInsets, setPadding, setPrefHeight, setPrefSize, setPrefWidth, setScaleShape, setShape, setSnapToPixel, setWidth, shapeProperty, snappedBottomInset, snappedLeftInset, snappedRightInset, snappedTopInset, snapPosition, snapPositionX, snapPositionY, snapSize, snapSizeX, snapSizeY, snapSpace, snapSpaceX, snapSpaceY, snapToPixelProperty, widthProperty`

  ### Methods inherited from class Parent

  `getChildren, getChildrenUnmodifiable, getManagedChildren, getStylesheets, isNeedsLayout, layout, lookup, needsLayoutProperty, requestLayout, requestParentLayout, setNeedsLayout, updateBounds`

  ### Methods inherited from class Node

  `accessibleHelpProperty, accessibleRoleDescriptionProperty, accessibleRoleProperty, accessibleTextProperty, addEventFilter, addEventHandler, applyCss, autosize, blendModeProperty, boundsInLocalProperty, boundsInParentProperty, buildEventDispatchChain, cacheHintProperty, cacheProperty, clipProperty, computeAreaInScreen, contains, contains, cursorProperty, depthTestProperty, disabledProperty, disableProperty, effectiveNodeOrientationProperty, effectProperty, eventDispatcherProperty, fireEvent, focusedProperty, focusTraversableProperty, focusVisibleProperty, focusWithinProperty, getAccessibleHelp, getAccessibleRole, getAccessibleRoleDescription, getAccessibleText, getBlendMode, getBoundsInLocal, getBoundsInParent, getCacheHint, getClip, getContentBias, getCursor, getDepthTest, getEffect, getEffectiveNodeOrientation, getEventDispatcher, getId, getInitialCursor, getInputMethodRequests, getLayoutBounds, getLayoutX, getLayoutY, getLocalToParentTransform, getLocalToSceneTransform, getNodeOrientation, getOnContextMenuRequested, getOnDragDetected, getOnDragDone, getOnDragDropped, getOnDragEntered, getOnDragExited, getOnDragOver, getOnInputMethodTextChanged, getOnKeyPressed, getOnKeyReleased, getOnKeyTyped, getOnMouseClicked, getOnMouseDragEntered, getOnMouseDragExited, getOnMouseDragged, getOnMouseDragOver, getOnMouseDragReleased, getOnMouseEntered, getOnMouseExited, getOnMouseMoved, getOnMousePressed, getOnMouseReleased, getOnRotate, getOnRotationFinished, getOnRotationStarted, getOnScroll, getOnScrollFinished, getOnScrollStarted, getOnSwipeDown, getOnSwipeLeft, getOnSwipeRight, getOnSwipeUp, getOnTouchMoved, getOnTouchPressed, getOnTouchReleased, getOnTouchStationary, getOnZoom, getOnZoomFinished, getOnZoomStarted, getOpacity, getParent, getProperties, getPseudoClassStates, getRotate, getRotationAxis, getScaleX, getScaleY, getScaleZ, getScene, getStyle, getStyleableParent, getStyleClass, getTransforms, getTranslateX, getTranslateY, getTranslateZ, getTypeSelector, getUserData, getViewOrder, hasProperties, hoverProperty, idProperty, inputMethodRequestsProperty, intersects, intersects, isCache, isDisable, isDisabled, isFocused, isFocusTraversable, isFocusVisible, isFocusWithin, isHover, isManaged, isMouseTransparent, isPickOnBounds, isPressed, isVisible, layoutBoundsProperty, layoutXProperty, layoutYProperty, localToParent, localToParent, localToParent, localToParent, localToParent, localToParentTransformProperty, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToSceneTransformProperty, localToScreen, localToScreen, localToScreen, localToScreen, localToScreen, lookupAll, managedProperty, mouseTransparentProperty, nodeOrientationProperty, notifyAccessibleAttributeChanged, onContextMenuRequestedProperty, onDragDetectedProperty, onDragDoneProperty, onDragDroppedProperty, onDragEnteredProperty, onDragExitedProperty, onDragOverProperty, onInputMethodTextChangedProperty, onKeyPressedProperty, onKeyReleasedProperty, onKeyTypedProperty, onMouseClickedProperty, onMouseDragEnteredProperty, onMouseDragExitedProperty, onMouseDraggedProperty, onMouseDragOverProperty, onMouseDragReleasedProperty, onMouseEnteredProperty, onMouseExitedProperty, onMouseMovedProperty, onMousePressedProperty, onMouseReleasedProperty, onRotateProperty, onRotationFinishedProperty, onRotationStartedProperty, onScrollFinishedProperty, onScrollProperty, onScrollStartedProperty, onSwipeDownProperty, onSwipeLeftProperty, onSwipeRightProperty, onSwipeUpProperty, onTouchMovedProperty, onTouchPressedProperty, onTouchReleasedProperty, onTouchStationaryProperty, onZoomFinishedProperty, onZoomProperty, onZoomStartedProperty, opacityProperty, parentProperty, parentToLocal, parentToLocal, parentToLocal, parentToLocal, parentToLocal, pickOnBoundsProperty, pressedProperty, pseudoClassStateChanged, relocate, removeEventFilter, removeEventHandler, requestFocus, resizeRelocate, rotateProperty, rotationAxisProperty, scaleXProperty, scaleYProperty, scaleZProperty, sceneProperty, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, screenToLocal, screenToLocal, screenToLocal, setAccessibleHelp, setAccessibleRole, setAccessibleRoleDescription, setAccessibleText, setBlendMode, setCache, setCacheHint, setClip, setCursor, setDepthTest, setDisable, setDisabled, setEffect, setEventDispatcher, setEventHandler, setFocused, setFocusTraversable, setHover, setId, setInputMethodRequests, setLayoutX, setLayoutY, setManaged, setMouseTransparent, setNodeOrientation, setOnContextMenuRequested, setOnDragDetected, setOnDragDone, setOnDragDropped, setOnDragEntered, setOnDragExited, setOnDragOver, setOnInputMethodTextChanged, setOnKeyPressed, setOnKeyReleased, setOnKeyTyped, setOnMouseClicked, setOnMouseDragEntered, setOnMouseDragExited, setOnMouseDragged, setOnMouseDragOver, setOnMouseDragReleased, setOnMouseEntered, setOnMouseExited, setOnMouseMoved, setOnMousePressed, setOnMouseReleased, setOnRotate, setOnRotationFinished, setOnRotationStarted, setOnScroll, setOnScrollFinished, setOnScrollStarted, setOnSwipeDown, setOnSwipeLeft, setOnSwipeRight, setOnSwipeUp, setOnTouchMoved, setOnTouchPressed, setOnTouchReleased, setOnTouchStationary, setOnZoom, setOnZoomFinished, setOnZoomStarted, setOpacity, setPickOnBounds, setPressed, setRotate, setRotationAxis, setScaleX, setScaleY, setScaleZ, setStyle, setTranslateX, setTranslateY, setTranslateZ, setUserData, setViewOrder, setVisible, snapshot, snapshot, startDragAndDrop, startFullDrag, styleProperty, toBack, toFront, toString, translateXProperty, translateYProperty, translateZProperty, usesMirroring, viewOrderProperty, visibleProperty`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface Styleable

  `getStyleableNode`

- ## Field Details

  - ### onResourceLoaded

    public final ObjectProperty<EventHandler<ResourceEvent>> onResourceLoaded
    Function to be called after a resource has been loaded from a file or URL. The default value is `null`.
    See Also:
      - `loadResource(Object)`
      - `ResourceEvent​.LOADED`

  - ### onResourceClosed

    public final ObjectProperty<EventHandler<ResourceEvent>> onResourceClosed
    Function to be called after a resource has been closed from a file or URL. The default value is `null`.
    Since:
      1.2
    See Also:
      - `removeAndClose(Resource)`
      - `ResourceEvent​.CLOSED`

- ## Constructor Details

  - ### ResourceTree

    public ResourceTree()
    Creates a new tree of resources with initially no resource to show. For showing a resource, invoke `setResource(Resource)` after construction.

- ## Method Details

  - ### getResource

    public Resource getResource()
    Returns the root `Resource` of this tree. The returned value depends on how the resource was set:
    - If the resource was specified by `setResource(Resource)`, then this method returns that resource. This is often (but not necessarily) a `DataStore`.
    - If one or more resources were specified by `addResource(Resource)`, then this method returns an `Aggregate` of all added resources.
    Returns:
      root `Resource`, or `null` if none.

  - ### setResource

    public void setResource(Resource resource)
    Sets the root `Resource` of this tree. The root resource is typically, but not necessarily, a `DataStore` instance. If another root resource existed before this method call, it is discarded without being closed. Closing the previous resource is caller's responsibility.

    #### Modified tree view properties

    This method updates the `root` and `showRoot` properties of `TreeView` in an implementation-dependent way.
    Parameters:
      `resource` - the root resource to show, or `null` if none.
    See Also:
      - `addResource(Resource)`
      - `removeAndClose(Resource)`

  - ### addResource

    public boolean addResource(Resource resource)
    Adds a resource in this tree below previously added resources. This method does nothing if the given resource is already present in this tree.

    #### Modified tree view properties

    This method updates the `root` and `showRoot` properties of `TreeView` in an implementation-dependent way.
    Parameters:
      `resource` - the root resource to add, or `null` if none.
    Returns:
      `true` if the given resource has been added, or `false` if it was already presents or if the given resource is `null`.
    See Also:
      - `setResource(Resource)`
      - `removeAndClose(Resource)`

  - ### loadResource

    public void loadResource(Object source)
    Loads in a background thread the resources from the given source, then adds the resource to this tree. If the resource has already been loaded, then this method will use the existing instance instead of loading the data again.

    #### Notifications

    If `onResourceLoaded` has a non-null value, the `EventHandler` will be notified in JavaFX thread after the background thread finished to open the resource. If an exception occurs while opening the resource, then `EventHandler` is not notified and the error is reported in a dialog box instead.
    Parameters:
      `source` - the source of the resource to load. This is usually a `File` or `Path`.
    See Also:
      - `ResourceExplorer​.loadResources(Collection)`

  - ### removeAndClose

    public void removeAndClose(Resource resource)
    Removes the given resource from this tree and closes the resource if it is a `DataStore` instance. It is caller's responsibility to ensure that the given resource is not used anymore.

    Only the "root" resources (such as the resources given to `setResource(Resource)` or `addResource(Resource)` methods) can be removed. Children of `Aggregate` resource are not scanned. If the given resource cannot be removed, then this method does nothing.

    #### Notifications

    If `onResourceClosed` has a non-null value, the `EventHandler` will be notified. The notification may happen in same time that the resource is closing in a background thread. If an exception occurs while closing the resource, the error is reported in a dialog box.
    Parameters:
      `resource` - the resource to remove. Null values are ignored.
    See Also:
      - `setResource(Resource)`
      - `addResource(Resource)`
      - `ResourceExplorer​.removeAndClose(Resource)`