Module org.controlsfx.controls
Package org.controlsfx.control

Class SnapshotView

  • All Implemented Interfaces:
    Styleable, EventTarget, Skinnable
    public class SnapshotView
extends 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

    • Property Detail

      • node

        public final ObjectProperty<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

      • selection

        public final ObjectProperty<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:
        hasSelectionProperty()

      • hasSelection

        public final 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

      • selectionActive

        public final 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

      • selectionChanging

        public final 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

      • selectionRatioFixed

        public final 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

      • fixedSelectionRatio

        public final 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

      • selectionAreaBoundary

        public final 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

      • selectionActivityManaged

        public final 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

      • selectionMouseTransparent

        public final 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

      • selectionBorderWidth

        public final 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:
        selectionBorderPaintProperty(), Shape.strokeWidthProperty()

      • selectionAreaFill

        public final ObjectProperty<Paint> selectionAreaFillProperty
        Determines the visualization of the selected area.
        Default value:
        Color.TRANSPARENT
        Returns:
        the property holding the Paint of the selected area

      • unselectedAreaFill

        public final ObjectProperty<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

    • Field Detail

      • 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:
        Constant Field Values

      • SELECTION_CHANGING_PROPERTY_KEY

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

    • Constructor Detail

      • SnapshotView

        public SnapshotView()
        Creates a new SnapshotView.

      • SnapshotView

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

    • Method Detail

      • transformToNodeCoordinates

        public Rectangle2D transformToNodeCoordinates​(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

      • getClassCssMetaData

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

      • nodeProperty

        public final ObjectProperty<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 Node getNode()
        Returns:
        the displayed node
        See Also:
        nodeProperty()

      • setNode

        public final void setNode​(Node node)
        Parameters:
        node - the node to display
        See Also:
        nodeProperty()

      • selectionProperty

        public final ObjectProperty<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:
        hasSelectionProperty()

      • 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:
        selectionProperty()

      • hasSelectionProperty

        public final 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:
        hasSelectionProperty()

      • selectionActiveProperty

        public final 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:
        selectionActiveProperty()

      • setSelectionActive

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

      • selectionChangingProperty

        public final 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:
        selectionChangingProperty()

      • selectionRatioFixedProperty

        public final 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:
        selectionRatioFixedProperty()

      • setSelectionRatioFixed

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

      • fixedSelectionRatioProperty

        public final 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:
        fixedSelectionRatioProperty()

      • 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:
        fixedSelectionRatioProperty()

      • selectionAreaBoundaryProperty

        public final 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

      • setSelectionAreaBoundary

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

      • selectionActivityManagedProperty

        public final 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:
        selectionActivityManagedProperty()

      • setSelectionActivityManaged

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

      • selectionMouseTransparentProperty

        public final 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:
        selectionMouseTransparentProperty()

      • setSelectionMouseTransparent

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

      • setSelectionBorderPaint

        public final void setSelectionBorderPaint​(Paint selectionBorderPaint)
        Parameters:
        selectionBorderPaint - the new Paint of the selection border
        See Also:
        selectionBorderPaintProperty()

      • selectionBorderWidthProperty

        public final 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:
        selectionBorderPaintProperty(), Shape.strokeWidthProperty()

      • getSelectionBorderWidth

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

      • setSelectionBorderWidth

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

      • selectionAreaFillProperty

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

      • setSelectionAreaFill

        public final void setSelectionAreaFill​(Paint selectionAreaFill)
        Parameters:
        selectionAreaFill - the new Paint of the selected area
        See Also:
        selectionAreaFillProperty()

      • unselectedAreaFillProperty

        public final ObjectProperty<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

      • setUnselectedAreaFill

        public final void setUnselectedAreaFill​(Paint unselectedAreaFill)
        Parameters:
        unselectedAreaFill - the new Paint of the area outside of the selection
        See Also:
        unselectedAreaFillProperty()

      • 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)