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

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:
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 Details

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

    • 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

    • unselectedAreaBoundary

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

    • selectionBorderPaint

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

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

    • 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 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(Node node)
      Creates a new SnapshotView using the specified node.
      Parameters:
      node - the node to show after construction

  • Method Details

    • transformSelectionToNodeCoordinates

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

    • createSnapshot

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

    • createSnapshot

      public WritableImage createSnapshot(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:

    • getUserAgentStylesheet

      public String getUserAgentStylesheet()
      Overrides:
      getUserAgentStylesheet in class Region

    • getClassCssMetaData

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

    • getControlCssMetaData

      public List<CssMetaData<? extends Styleable,?>> getControlCssMetaData()
      Overrides:
      getControlCssMetaData in class Control

    • createDefaultSkin

      protected Skin<?> createDefaultSkin()
      Overrides:
      createDefaultSkin in class Control

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

    • setNode

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

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

    • getSelection

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

    • setSelection

      public final void setSelection(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 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 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 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 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 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 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 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 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 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 ObjectProperty<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 Paint getSelectionBorderPaint()
      Returns:
      the Paint of the selection border
      See Also:

    • setSelectionBorderPaint

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

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

    • 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 ObjectProperty<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 Paint getSelectionAreaFill()
      Returns:
      the Paint of the selected area
      See Also:

    • setSelectionAreaFill

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

    • 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

    • getUnselectedAreaFill

      public final Paint getUnselectedAreaFill()
      Returns:
      the Paint of the area outside of the selection
      See Also:

    • setUnselectedAreaFill

      public final void setUnselectedAreaFill(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)