Class SnapshotView

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
javafx.scene.control.Control
org.controlsfx.control.SnapshotView
All Implemented Interfaces:
javafx.css.Styleable, javafx.event.EventTarget, javafx.scene.control.Skinnable
public class SnapshotView extends javafx.scene.control.Control
A SnapshotView is a control which allows the user to select an area of a node in the typical manner used by picture editors and crate snapshots of the selection.

While holding the left mouse key down, a rectangular selection can be drawn. This selection can be moved, resized in eight cardinal directions and removed. Additionally, the selection's ratio can be fixed in which case the user's resizing will be limited such that the ratio is always upheld.

The area where the selection is possible is either this entire control or limited to the displayed node.

Screenshots

Screenshot of SnapshotView

Code Samples

The following snippet creates a new instance with the ControlsFX logo loaded from the web, sets a selected area and fixes its ratio: 
ImageView controlsFxView = new ImageView(
        "http://cache.fxexperience.com/wp-content/uploads/2013/05/ControlsFX.png");
SnapshotView snapshotView = new SnapshotView(controlsFxView);
snapshotView.setSelection(33, 50, 100, 100);
snapshotView.setFixedSelectionRatio(1); // (this is actually the default value)
snapshotView.setSelectionRatioFixed(true);

Functionality Overview

This is just a vague overview. The linked properties provide a more detailed explanation.

Node

The node which this control displays is held by the node property.

Selection

There are several properties which interact to manage and indicate the selection.
State
  • the selection is held by the selection property
  • the hasSelection property indicates whether a selection exists
  • the selectionActive property indicates whether the current selection is active (it is only displayed if it is); by default this property is updated by this control which is determined by the selectionActivityManaged property
Interaction
  • if the selection is changing due to the user interacting with the control, this is indicated by the selectionChanging property
  • whether the user can select any area of the control or only one above the node is determined by the selectionAreaBoundary property
  • with the selectionMouseTransparent property the control can be made mouse transparent so the user can interact with the displayed node
  • the selection's ratio of width to height can be fixed with the selectionRatioFixed and the fixedSelectionRatio properties
Visualization

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    SnapshotView.Boundary
    The selectionArea, in which the user can create a selection, and the unselectedArea, in which the unselected area is visualized, are limited to a certain area of the control.

  • Property Summary

    Properties
    Type
    Property
    Description
    final javafx.beans.property.DoubleProperty
    fixedSelectionRatio
    The value to which the selection ratio is fixed.
    final javafx.beans.property.ReadOnlyBooleanProperty
    hasSelection
    Indicates whether there currently is a selection.
    final javafx.beans.property.ObjectProperty<javafx.scene.Node>
    node
    The Node which will be displayed in the center of this control.
    final javafx.beans.property.BooleanProperty
    selectionActive
    Indicates whether the selection is currently active.
    final javafx.beans.property.BooleanProperty
    selectionActivityManaged
    Indicates whether the value of the selectionActive property is managed by this control.
    final javafx.beans.property.ObjectProperty<SnapshotView.Boundary>
    selectionAreaBoundary
    Indicates which SnapshotView.Boundary is set for the area the user can select.
    final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint>
    selectionAreaFill
    Determines the visualization of the selected area.
    final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint>
    selectionBorderPaint
    Determines the visualization of the selection's border.
    final javafx.beans.property.DoubleProperty
    selectionBorderWidth
    Determines the width of the selection's border.
    final javafx.beans.property.ReadOnlyBooleanProperty
    selectionChanging
    Indicates whether the selection is currently changing due to user interaction with the control.
    final javafx.beans.property.BooleanProperty
    selectionMouseTransparent
    Indicates whether the overlay which displays the selection is mouse transparent.
    final javafx.beans.property.ObjectProperty<javafx.geometry.Rectangle2D>
    selection
    The current selection as a Rectangle2D.
    final javafx.beans.property.BooleanProperty
    selectionRatioFixed
    Indicates whether the ratio of the selection is fixed.
    final javafx.beans.property.ObjectProperty<SnapshotView.Boundary>
    unselectedAreaBoundary
    Indicates which SnapshotView.Boundary is set for the visualization of the unselected area (i.e. the area outside of the selection rectangle).
    final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint>
    unselectedAreaFill
    Determines the visualization of the area outside of the selection.

    Properties inherited from class javafx.scene.control.Control

    contextMenu, skin, tooltip

    Properties inherited from class javafx.scene.layout.Region

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

    Properties inherited from class javafx.scene.Parent

    needsLayout

    Properties inherited from class javafx.scene.Node

    accessibleHelp, accessibleRoleDescription, accessibleRole, accessibleText, blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effectiveNodeOrientation, effect, eventDispatcher, focused, focusTraversable, 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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    MAX_SELECTION_RATIO_DIVERGENCE
    The maximal divergence between a selection's ratio and the fixedselectionRatio for the selection to still have the correct ratio (see hasCorrectRatio).
    static final String
    SELECTION_CHANGING_PROPERTY_KEY
    The key of the property which is used to update selectionChanging.

    Fields inherited from class javafx.scene.layout.Region

    USE_COMPUTED_SIZE, USE_PREF_SIZE

    Fields inherited from class javafx.scene.Node

    BASELINE_OFFSET_SAME_AS_HEIGHT

  • Constructor Summary

    Constructors
    Constructor
    Description
    SnapshotView()
    Creates a new SnapshotView.
    SnapshotView(javafx.scene.Node node)
    Creates a new SnapshotView using the specified node.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected javafx.scene.control.Skin<?>
    createDefaultSkin()
     
    javafx.scene.image.WritableImage
    createSnapshot()
    Creates a snapshot of the selected area of the node.
    javafx.scene.image.WritableImage
    createSnapshot(javafx.scene.SnapshotParameters parameters)
    Creates a snapshot of the node with the specified parameters.
    final javafx.beans.property.DoubleProperty
    fixedSelectionRatioProperty()
    The value to which the selection ratio is fixed.
    static List<javafx.css.CssMetaData<? extends javafx.css.Styleable, ?>>
    getClassCssMetaData()
     
    List<javafx.css.CssMetaData<? extends javafx.css.Styleable, ?>>
    getControlCssMetaData()
     
    final double
    getFixedSelectionRatio()
     
    final javafx.scene.Node
    getNode()
     
    final javafx.geometry.Rectangle2D
    getSelection()
     
    final SnapshotView.Boundary
    getSelectionAreaBoundary()
     
    final javafx.scene.paint.Paint
    getSelectionAreaFill()
     
    final javafx.scene.paint.Paint
    getSelectionBorderPaint()
     
    final double
    getSelectionBorderWidth()
     
    final SnapshotView.Boundary
    getUnselectedAreaBoundary()
     
    final javafx.scene.paint.Paint
    getUnselectedAreaFill()
     
    String
    getUserAgentStylesheet()
    protected final String
    getUserAgentStylesheet(Class<?> clazz, String fileName)
    A helper method that ensures that the resource based lookup of the user agent stylesheet only happens once.
    final boolean
    hasSelection()
     
    final javafx.beans.property.ReadOnlyBooleanProperty
    hasSelectionProperty()
    Indicates whether there currently is a selection.
    final boolean
    isSelectionActive()
     
    final boolean
    isSelectionActivityManaged()
     
    final boolean
    isSelectionChanging()
     
    final boolean
    isSelectionMouseTransparent()
     
    final boolean
    isSelectionRatioFixed()
     
    final javafx.beans.property.ObjectProperty<javafx.scene.Node>
    nodeProperty()
    The Node which will be displayed in the center of this control.
    final javafx.beans.property.BooleanProperty
    selectionActiveProperty()
    Indicates whether the selection is currently active.
    final javafx.beans.property.BooleanProperty
    selectionActivityManagedProperty()
    Indicates whether the value of the selectionActive property is managed by this control.
    final javafx.beans.property.ObjectProperty<SnapshotView.Boundary>
    selectionAreaBoundaryProperty()
    Indicates which SnapshotView.Boundary is set for the area the user can select.
    final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint>
    selectionAreaFillProperty()
    Determines the visualization of the selected area.
    final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint>
    selectionBorderPaintProperty()
    Determines the visualization of the selection's border.
    final javafx.beans.property.DoubleProperty
    selectionBorderWidthProperty()
    Determines the width of the selection's border.
    final javafx.beans.property.ReadOnlyBooleanProperty
    selectionChangingProperty()
    Indicates whether the selection is currently changing due to user interaction with the control.
    final javafx.beans.property.BooleanProperty
    selectionMouseTransparentProperty()
    Indicates whether the overlay which displays the selection is mouse transparent.
    final javafx.beans.property.ObjectProperty<javafx.geometry.Rectangle2D>
    selectionProperty()
    The current selection as a Rectangle2D.
    final javafx.beans.property.BooleanProperty
    selectionRatioFixedProperty()
    Indicates whether the ratio of the selection is fixed.
    final void
    setFixedSelectionRatio(double fixedSelectionRatio)
     
    final void
    setNode(javafx.scene.Node node)
     
    final void
    setSelection(double upperLeftX, double upperLeftY, double width, double height)
    Creates a new Rectangle2D from the specified arguments and sets it as the new selection.
    final void
    setSelection(javafx.geometry.Rectangle2D selection)
     
    final void
    setSelectionActive(boolean selectionActive)
     
    final void
    setSelectionActivityManaged(boolean selectionActivityManaged)
     
    final void
    setSelectionAreaBoundary(SnapshotView.Boundary selectionAreaBoundary)
     
    final void
    setSelectionAreaFill(javafx.scene.paint.Paint selectionAreaFill)
     
    final void
    setSelectionBorderPaint(javafx.scene.paint.Paint selectionBorderPaint)
     
    final void
    setSelectionBorderWidth(double selectionBorderWidth)
     
    final void
    setSelectionMouseTransparent(boolean selectionMouseTransparent)
     
    final void
    setSelectionRatioFixed(boolean selectionRatioFixed)
     
    final void
    setUnselectedAreaBoundary(SnapshotView.Boundary unselectedAreaBoundary)
     
    final void
    setUnselectedAreaFill(javafx.scene.paint.Paint unselectedAreaFill)
     
    javafx.geometry.Rectangle2D
    transformSelectionToNodeCoordinates()
    Transforms the selection to node coordinates by calling transformToNodeCoordinates.
    javafx.geometry.Rectangle2D
    transformToNodeCoordinates(javafx.geometry.Rectangle2D area)
    Transforms the specified area's coordinates to coordinates relative to the node.
    final javafx.beans.property.ObjectProperty<SnapshotView.Boundary>
    unselectedAreaBoundaryProperty()
    Indicates which SnapshotView.Boundary is set for the visualization of the unselected area (i.e. the area outside of the selection rectangle).
    final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint>
    unselectedAreaFillProperty()
    Determines the visualization of the area outside of the selection.

    Methods inherited from class javafx.scene.control.Control

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

    Methods inherited from class javafx.scene.layout.Region

    backgroundProperty, borderProperty, cacheShapeProperty, centerShapeProperty, getBackground, getBorder, getHeight, getInsets, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpaqueInsets, getPadding, getPrefHeight, getPrefWidth, getShape, 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 javafx.scene.Parent

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

    Methods inherited from class javafx.scene.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, 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, 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 javafx.css.Styleable

    getStyleableNode

  • Property Details

    • node

      public final javafx.beans.property.ObjectProperty<javafx.scene.Node> nodeProperty
      The Node which will be displayed in the center of this control.

      The node's boundsInParent show its relative position inside this control. Since the selection property also uses this control as its reference coordinate system, the bounds can be used to compute which area of the node is selected.

      If this control or the node behaves strangely when resized, try embedding the original node in a Pane and setting the pane here.

      See Also:

    • selection

      public final javafx.beans.property.ObjectProperty<javafx.geometry.Rectangle2D> selectionProperty
      The current selection as a Rectangle2D. As such an instance is immutable a new one must be set to chane the selection.

      The rectangle's coordinates are interpreted relative to this control. The top left corner is the origin (0, 0) and the lower right corner is (width, height). It is guaranteed that the selection always lies within these bounds. If the control is resized, so is the selection. If a selection which violates these bounds is set, an IllegalArgumentException is thrown.

      The same is true if the selectionAreaBoundary is set to NODE but with the stricter condition that the selection must lie within the node's boundsInParent.

      If the selection ratio is fixed, any new selection must have the fixedSelectionRatio. Otherwise, an IllegalArgumentException is thrown.

      An IllegalArgumentException is also thrown if not all of the selection's values (e.g. width and height) are finite.

      The selection might be null or Rectangle2D.EMPTY in which case no selection is displayed and hasSelection is false.

      See Also:

    • hasSelection

      public final javafx.beans.property.ReadOnlyBooleanProperty hasSelectionProperty
      Indicates whether there currently is a selection. This will be false if the selection property holds null or Rectangle2D.EMPTY .
      See Also:

    • selectionActive

      public final javafx.beans.property.BooleanProperty selectionActiveProperty
      Indicates whether the selection is currently active. Only an active selection will be displayed by the control.

      See selectionActivityManaged for documentation on how this property might be changed by this control.

      See Also:

    • selectionChanging

      public final javafx.beans.property.ReadOnlyBooleanProperty selectionChangingProperty
      Indicates whether the selection is currently changing due to user interaction with the control. It will be set to true when changing the selection begins and set to false when it ends.

      If a selection is set by the code using this control (e.g. by calling setSelection) this property does not change its value.

      See Also:

    • selectionRatioFixed

      public final javafx.beans.property.BooleanProperty selectionRatioFixedProperty
      Indicates whether the ratio of the selection is fixed.

      By default this property is false and the user interacting with this control can make arbitrary selections with any ratio of width to height. If it is true, the user is limited to making selections with the ratio defined by the fixedSelectionRatio property. If the ratio is fixed and a selection with a different ratio is set, an IllegalArgumentException is thrown.

      If a selection exists and this property is set to true, the selection is immediately resized to the currently set ratio.

      Default value:
      false
      See Also:

    • fixedSelectionRatio

      public final javafx.beans.property.DoubleProperty fixedSelectionRatioProperty
      The value to which the selection ratio is fixed. The ratio is defined as width / height and its value must be strictly positive.

      If selectionRatioFixed is true, this ratio will be upheld by all changes made by user interaction with this control. If the ratio is fixed and a selection is set by code (e.g. by calling setSelection), this ratio is checked and if violated an IllegalArgumentException is thrown.

      If a selection exists and selectionRatioFixed is set to true, the selection is immediately resized to this ratio. Similarly, if a selection exists and its ratio is fixed, setting a new value resizes the selection to the new ratio.

      Default value:
      1.0
      See Also:

    • selectionAreaBoundary

      public final javafx.beans.property.ObjectProperty<SnapshotView.Boundary> selectionAreaBoundaryProperty
      Indicates which SnapshotView.Boundary is set for the area the user can select.

      By default the user can select any area of the control. If this should be limited to the area over the displayed node instead, this property can be set to NODE. If the value is changed from CONTROL to NODE a possibly existing selection is resized accordingly.

      If the boundary is set to NODE, this is also respected when a new selection is set. This means the condition for the new selection's coordinates is made stricter and setting a selection out of the node's bounds (instead of only out of the control's bounds) throws an IllegalArgumentException.

      Note that this does not change the reference coordinate system! The selection's coordinates are still interpreted relative to the node's boundsInParent.

      Default value:
      CONTROL
      See Also:

    • selectionActivityManaged

      public final javafx.beans.property.BooleanProperty selectionActivityManagedProperty
      Indicates whether the value of the selectionActive property is managed by this control.

      If this property is set to true (which is the default) this control will update the selectionActive property immediately after a new selection is set: if the new selection is null or Rectangle2D.EMPTY, it will be set to false; otherwise to true.

      If this property is false this control will never change selectionActive's value. In this case it must be managed by the using code but it is possible to unidirectionally bind it to another property without this control interfering.

      Default value:
      true
      See Also:

    • selectionMouseTransparent

      public final javafx.beans.property.BooleanProperty selectionMouseTransparentProperty
      Indicates whether the overlay which displays the selection is mouse transparent.

      By default all mouse events are captured by this control and used to interact with the selection. If this property is set to true, this behavior changes and the user is able to interact with the displayed node.

      Default value:
      false
      See Also:

    • unselectedAreaBoundary

      public final javafx.beans.property.ObjectProperty<SnapshotView.Boundary> unselectedAreaBoundaryProperty
      Indicates which SnapshotView.Boundary is set for the visualization of the unselected area (i.e. the area outside of the selection rectangle).

      If it is set to CONTROL (which is the default), the unselected area covers the whole control.

      If it is set to NODE, the area only covers the displayed node. In most cases this only makes sense if the selectionAreaBoundary is also set to NODE.

      Default value:
      SnapshotView.Boundary.CONTROL
      See Also:

    • selectionBorderPaint

      public final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint> selectionBorderPaintProperty
      Determines the visualization of the selection's border.
      Default value:
      Color.WHITESMOKE
      See Also:

    • selectionBorderWidth

      public final javafx.beans.property.DoubleProperty selectionBorderWidthProperty
      Determines the width of the selection's border. The border is always painted to the outside of the selected area, i.e. the selected area is never covered by the border.
      Default value:
      2.5
      See Also:

    • selectionAreaFill

      public final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint> selectionAreaFillProperty
      Determines the visualization of the selected area.
      Default value:
      Color.TRANSPARENT
      See Also:

    • unselectedAreaFill

      public final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint> unselectedAreaFillProperty
      Determines the visualization of the area outside of the selection.
      Default value:
      black with opacity 0.5
      See Also:

  • Field Details

    • MAX_SELECTION_RATIO_DIVERGENCE

      public static final double MAX_SELECTION_RATIO_DIVERGENCE
      The maximal divergence between a selection's ratio and the fixedselectionRatio for the selection to still have the correct ratio (see hasCorrectRatio).

      The divergence is expressed relative to the fixedselectionRatio.

      See Also:

    • SELECTION_CHANGING_PROPERTY_KEY

      public static final String SELECTION_CHANGING_PROPERTY_KEY
      The key of the property which is used to update selectionChanging.

  • Constructor Details

    • SnapshotView

      public SnapshotView()
      Creates a new SnapshotView.

    • SnapshotView

      public SnapshotView(javafx.scene.Node node)
      Creates a new SnapshotView using the specified node.
      Parameters:
      node - the node to show after construction

  • Method Details

    • transformSelectionToNodeCoordinates

      public javafx.geometry.Rectangle2D transformSelectionToNodeCoordinates()
      Transforms the selection to node coordinates by calling transformToNodeCoordinates.
      Returns:
      a Rectangle2D which expresses the selection in the node's coordinates
      Throws:
      IllegalStateException - if node is null or hasSelection is false
      See Also:

    • transformToNodeCoordinates

      public javafx.geometry.Rectangle2D transformToNodeCoordinates(javafx.geometry.Rectangle2D area) throws IllegalStateException
      Transforms the specified area's coordinates to coordinates relative to the node. (The node's coordinate system has its origin in the upper left corner of the node.)
      Parameters:
      area - the Rectangle2D which will be transformed (must not be null); its coordinates will be interpreted relative to the control (like the selection)
      Returns:
      a Rectangle2D with the same width and height as the specified area but with coordinates which are relative to the current node
      Throws:
      IllegalStateException - if node is null

    • createSnapshot

      public javafx.scene.image.WritableImage createSnapshot() throws IllegalStateException
      Creates a snapshot of the selected area of the node.
      Returns:
      the WritableImage that holds the rendered selection
      Throws:
      IllegalStateException - if node is null or hasSelection is false
      See Also:
      • Node.snapshot(SnapshotParameters, WritableImage)

    • createSnapshot

      public javafx.scene.image.WritableImage createSnapshot(javafx.scene.SnapshotParameters parameters) throws IllegalStateException
      Creates a snapshot of the node with the specified parameters.
      Parameters:
      parameters - the SnapshotParameters used for the snapshot (must not be null); the viewport will be interpreted relative to this control (like the selection)
      Returns:
      the WritableImage that holds the rendered viewport
      Throws:
      IllegalStateException - if node is null
      See Also:
      • Node.snapshot(SnapshotParameters, WritableImage)

    • getUserAgentStylesheet

      public String getUserAgentStylesheet()
      Overrides:
      getUserAgentStylesheet in class javafx.scene.layout.Region

    • getClassCssMetaData

      public static List<javafx.css.CssMetaData<? extends javafx.css.Styleable, ?>> getClassCssMetaData()
      Returns:
      the CssMetaData associated with this class, which includes the CssMetaData of its super classes

    • getControlCssMetaData

      public List<javafx.css.CssMetaData<? extends javafx.css.Styleable, ?>> getControlCssMetaData()
      Overrides:
      getControlCssMetaData in class javafx.scene.control.Control

    • createDefaultSkin

      protected javafx.scene.control.Skin<?> createDefaultSkin()
      Overrides:
      createDefaultSkin in class javafx.scene.control.Control

    • nodeProperty

      public final javafx.beans.property.ObjectProperty<javafx.scene.Node> nodeProperty()
      The Node which will be displayed in the center of this control.

      The node's boundsInParent show its relative position inside this control. Since the selection property also uses this control as its reference coordinate system, the bounds can be used to compute which area of the node is selected.

      If this control or the node behaves strangely when resized, try embedding the original node in a Pane and setting the pane here.

      Returns:
      the property holding the displayed node

    • getNode

      public final javafx.scene.Node getNode()
      Returns:
      the displayed node
      See Also:

    • setNode

      public final void setNode(javafx.scene.Node node)
      Parameters:
      node - the node to display
      See Also:

    • selectionProperty

      public final javafx.beans.property.ObjectProperty<javafx.geometry.Rectangle2D> selectionProperty()
      The current selection as a Rectangle2D. As such an instance is immutable a new one must be set to chane the selection.

      The rectangle's coordinates are interpreted relative to this control. The top left corner is the origin (0, 0) and the lower right corner is (width, height). It is guaranteed that the selection always lies within these bounds. If the control is resized, so is the selection. If a selection which violates these bounds is set, an IllegalArgumentException is thrown.

      The same is true if the selectionAreaBoundary is set to NODE but with the stricter condition that the selection must lie within the node's boundsInParent.

      If the selection ratio is fixed, any new selection must have the fixedSelectionRatio. Otherwise, an IllegalArgumentException is thrown.

      An IllegalArgumentException is also thrown if not all of the selection's values (e.g. width and height) are finite.

      The selection might be null or Rectangle2D.EMPTY in which case no selection is displayed and hasSelection is false.

      Returns:
      the property holding the current selection
      See Also:

    • getSelection

      public final javafx.geometry.Rectangle2D getSelection()
      Returns:
      the current selection
      See Also:

    • setSelection

      public final void setSelection(javafx.geometry.Rectangle2D selection)
      Parameters:
      selection - the new selection
      Throws:
      IllegalArgumentException - if the selection is out of the bounds defined by the selectionAreaBoundary or the selection ratio is fixed and the new selection does not have the fixedSelectionRatio.
      See Also:

    • setSelection

      public final void setSelection(double upperLeftX, double upperLeftY, double width, double height)
      Creates a new Rectangle2D from the specified arguments and sets it as the new selection. It will have (upperLeftX, upperLeftY) as its upper left point and span width to the right and height down.
      Parameters:
      upperLeftX - the x coordinate of the selection's upper left point
      upperLeftY - the y coordinate of the selection's upper left point
      width - the selection's width
      height - the selection's height
      Throws:
      IllegalArgumentException - if the selection is out of the bounds defined by the selectionAreaBoundary or the selection ratio is fixed and the new selection does not have the fixedSelectionRatio.
      See Also:

    • hasSelectionProperty

      public final javafx.beans.property.ReadOnlyBooleanProperty hasSelectionProperty()
      Indicates whether there currently is a selection. This will be false if the selection property holds null or Rectangle2D.EMPTY .
      Returns:
      a property indicating whether there currently is a selection

    • hasSelection

      public final boolean hasSelection()
      Returns:
      whether there currently is a selection
      See Also:

    • selectionActiveProperty

      public final javafx.beans.property.BooleanProperty selectionActiveProperty()
      Indicates whether the selection is currently active. Only an active selection will be displayed by the control.

      See selectionActivityManaged for documentation on how this property might be changed by this control.

      Returns:
      the property indicating whether the selection is active

    • isSelectionActive

      public final boolean isSelectionActive()
      Returns:
      whether the selection is active
      See Also:

    • setSelectionActive

      public final void setSelectionActive(boolean selectionActive)
      Parameters:
      selectionActive - the new selection active status
      See Also:

    • selectionChangingProperty

      public final javafx.beans.property.ReadOnlyBooleanProperty selectionChangingProperty()
      Indicates whether the selection is currently changing due to user interaction with the control. It will be set to true when changing the selection begins and set to false when it ends.

      If a selection is set by the code using this control (e.g. by calling setSelection) this property does not change its value.

      Returns:
      a property indicating whether the selection is changing by user interaction

    • isSelectionChanging

      public final boolean isSelectionChanging()
      Returns:
      whether the selection is changing by user interaction
      See Also:

    • selectionRatioFixedProperty

      public final javafx.beans.property.BooleanProperty selectionRatioFixedProperty()
      Indicates whether the ratio of the selection is fixed.

      By default this property is false and the user interacting with this control can make arbitrary selections with any ratio of width to height. If it is true, the user is limited to making selections with the ratio defined by the fixedSelectionRatio property. If the ratio is fixed and a selection with a different ratio is set, an IllegalArgumentException is thrown.

      If a selection exists and this property is set to true, the selection is immediately resized to the currently set ratio.

      Default value:
      false
      Returns:
      the property indicating whether the selection ratio is fixed

    • isSelectionRatioFixed

      public final boolean isSelectionRatioFixed()
      Returns:
      whether the selection ratio is fixed
      See Also:

    • setSelectionRatioFixed

      public final void setSelectionRatioFixed(boolean selectionRatioFixed)
      Parameters:
      selectionRatioFixed - whether the selection ratio will be fixed
      See Also:

    • fixedSelectionRatioProperty

      public final javafx.beans.property.DoubleProperty fixedSelectionRatioProperty()
      The value to which the selection ratio is fixed. The ratio is defined as width / height and its value must be strictly positive.

      If selectionRatioFixed is true, this ratio will be upheld by all changes made by user interaction with this control. If the ratio is fixed and a selection is set by code (e.g. by calling setSelection), this ratio is checked and if violated an IllegalArgumentException is thrown.

      If a selection exists and selectionRatioFixed is set to true, the selection is immediately resized to this ratio. Similarly, if a selection exists and its ratio is fixed, setting a new value resizes the selection to the new ratio.

      Default value:
      1.0
      Returns:
      a property containing the fixed selection ratio

    • getFixedSelectionRatio

      public final double getFixedSelectionRatio()
      Returns:
      the fixedSelectionRatio, which will always be a strictly positive value
      See Also:

    • setFixedSelectionRatio

      public final void setFixedSelectionRatio(double fixedSelectionRatio)
      Parameters:
      fixedSelectionRatio - the fixed selection ratio to set
      Throws:
      IllegalArgumentException - if fixedSelectionRatio is not strictly positive
      See Also:

    • selectionAreaBoundaryProperty

      public final javafx.beans.property.ObjectProperty<SnapshotView.Boundary> selectionAreaBoundaryProperty()
      Indicates which SnapshotView.Boundary is set for the area the user can select.

      By default the user can select any area of the control. If this should be limited to the area over the displayed node instead, this property can be set to NODE. If the value is changed from CONTROL to NODE a possibly existing selection is resized accordingly.

      If the boundary is set to NODE, this is also respected when a new selection is set. This means the condition for the new selection's coordinates is made stricter and setting a selection out of the node's bounds (instead of only out of the control's bounds) throws an IllegalArgumentException.

      Note that this does not change the reference coordinate system! The selection's coordinates are still interpreted relative to the node's boundsInParent.

      Default value:
      CONTROL
      Returns:
      the property indicating the SnapshotView.Boundary for the area the user can select

    • getSelectionAreaBoundary

      public final SnapshotView.Boundary getSelectionAreaBoundary()
      Returns:
      the SnapshotView.Boundary for the area the user can select

    • setSelectionAreaBoundary

      public final void setSelectionAreaBoundary(SnapshotView.Boundary selectionAreaBoundary)
      Parameters:
      selectionAreaBoundary - the new SnapshotView.Boundary for the area the user can select

    • selectionActivityManagedProperty

      public final javafx.beans.property.BooleanProperty selectionActivityManagedProperty()
      Indicates whether the value of the selectionActive property is managed by this control.

      If this property is set to true (which is the default) this control will update the selectionActive property immediately after a new selection is set: if the new selection is null or Rectangle2D.EMPTY, it will be set to false; otherwise to true.

      If this property is false this control will never change selectionActive's value. In this case it must be managed by the using code but it is possible to unidirectionally bind it to another property without this control interfering.

      Default value:
      true
      Returns:
      the property indicating whether the value of the selectionActive property is managed by this control

    • isSelectionActivityManaged

      public final boolean isSelectionActivityManaged()
      Returns:
      whether the selection activity is managed by this control
      See Also:

    • setSelectionActivityManaged

      public final void setSelectionActivityManaged(boolean selectionActivityManaged)
      Parameters:
      selectionActivityManaged - whether the selection activity will be managed by this control
      See Also:

    • selectionMouseTransparentProperty

      public final javafx.beans.property.BooleanProperty selectionMouseTransparentProperty()
      Indicates whether the overlay which displays the selection is mouse transparent.

      By default all mouse events are captured by this control and used to interact with the selection. If this property is set to true, this behavior changes and the user is able to interact with the displayed node.

      Default value:
      false
      Returns:
      the property indicating whether the selection is mouse transparent

    • isSelectionMouseTransparent

      public final boolean isSelectionMouseTransparent()
      Returns:
      whether the selection is mouse transparent
      See Also:

    • setSelectionMouseTransparent

      public final void setSelectionMouseTransparent(boolean selectionMouseTransparent)
      Parameters:
      selectionMouseTransparent - whether the selection will be mouse transparent
      See Also:

    • unselectedAreaBoundaryProperty

      public final javafx.beans.property.ObjectProperty<SnapshotView.Boundary> unselectedAreaBoundaryProperty()
      Indicates which SnapshotView.Boundary is set for the visualization of the unselected area (i.e. the area outside of the selection rectangle).

      If it is set to CONTROL (which is the default), the unselected area covers the whole control.

      If it is set to NODE, the area only covers the displayed node. In most cases this only makes sense if the selectionAreaBoundary is also set to NODE.

      Default value:
      SnapshotView.Boundary.CONTROL
      Returns:
      the property defining the SnapshotView.Boundary of the unselected area

    • getUnselectedAreaBoundary

      public final SnapshotView.Boundary getUnselectedAreaBoundary()
      Returns:
      the SnapshotView.Boundary for the unselected area
      See Also:

    • setUnselectedAreaBoundary

      public final void setUnselectedAreaBoundary(SnapshotView.Boundary unselectedAreaBoundary)
      Parameters:
      unselectedAreaBoundary - the new SnapshotView.Boundary for the unselected area
      See Also:

    • selectionBorderPaintProperty

      public final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint> selectionBorderPaintProperty()
      Determines the visualization of the selection's border.
      Default value:
      Color.WHITESMOKE
      Returns:
      the property holding the Paint of the selection border
      See Also:

    • getSelectionBorderPaint

      public final javafx.scene.paint.Paint getSelectionBorderPaint()
      Returns:
      the Paint of the selection border
      See Also:

    • setSelectionBorderPaint

      public final void setSelectionBorderPaint(javafx.scene.paint.Paint selectionBorderPaint)
      Parameters:
      selectionBorderPaint - the new Paint of the selection border
      See Also:

    • selectionBorderWidthProperty

      public final javafx.beans.property.DoubleProperty selectionBorderWidthProperty()
      Determines the width of the selection's border. The border is always painted to the outside of the selected area, i.e. the selected area is never covered by the border.
      Default value:
      2.5
      Returns:
      the property defining the selection border's width
      See Also:

    • getSelectionBorderWidth

      public final double getSelectionBorderWidth()
      Returns:
      the selection border width
      See Also:

    • setSelectionBorderWidth

      public final void setSelectionBorderWidth(double selectionBorderWidth)
      Parameters:
      selectionBorderWidth - the selection border width to set
      See Also:

    • selectionAreaFillProperty

      public final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint> selectionAreaFillProperty()
      Determines the visualization of the selected area.
      Default value:
      Color.TRANSPARENT
      Returns:
      the property holding the Paint of the selected area

    • getSelectionAreaFill

      public final javafx.scene.paint.Paint getSelectionAreaFill()
      Returns:
      the Paint of the selected area
      See Also:

    • setSelectionAreaFill

      public final void setSelectionAreaFill(javafx.scene.paint.Paint selectionAreaFill)
      Parameters:
      selectionAreaFill - the new Paint of the selected area
      See Also:

    • unselectedAreaFillProperty

      public final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint> unselectedAreaFillProperty()
      Determines the visualization of the area outside of the selection.
      Default value:
      black with opacity 0.5
      Returns:
      the property holding the Paint of the area outside of the selection

    • getUnselectedAreaFill

      public final javafx.scene.paint.Paint getUnselectedAreaFill()
      Returns:
      the Paint of the area outside of the selection
      See Also:

    • setUnselectedAreaFill

      public final void setUnselectedAreaFill(javafx.scene.paint.Paint unselectedAreaFill)
      Parameters:
      unselectedAreaFill - the new Paint of the area outside of the selection
      See Also:

    • getUserAgentStylesheet

      protected final String getUserAgentStylesheet(Class<?> clazz, String fileName)
      A helper method that ensures that the resource based lookup of the user agent stylesheet only happens once. Caches the external form of the resource.
      Parameters:
      clazz - the class used for the resource lookup
      fileName - the name of the user agent stylesheet
      Returns:
      the external form of the user agent stylesheet (the path)