- All Implemented Interfaces:
javafx.css.Styleable
,javafx.event.EventTarget
,javafx.scene.control.Skinnable
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

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 thenode
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 theselectionActivityManaged
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 thefixedSelectionRatio
properties
Visualization
-
selectionAreaFill
property for the selected area's paint -
selectionBorderPaint
property for the selection border's paint -
selectionBorderWidth
property for the selection border's width -
unselectedAreaFill
property for the area outside of the selection -
unselectedAreaBoundary
property which defined what the unselected area covers
-
Property Summary
PropertiesTypePropertyDescriptionfinal javafx.beans.property.DoubleProperty
The value to which the selection ratio is fixed.final javafx.beans.property.ReadOnlyBooleanProperty
Indicates whether there currently is a selection.final javafx.beans.property.ObjectProperty
<javafx.scene.Node> TheNode
which will be displayed in the center of this control.final javafx.beans.property.BooleanProperty
Indicates whether the selection is currently active.final javafx.beans.property.BooleanProperty
Indicates whether the value of theselectionActive
property is managed by this control.final javafx.beans.property.ObjectProperty
<SnapshotView.Boundary> Indicates whichSnapshotView.Boundary
is set for the area the user can select.final javafx.beans.property.ObjectProperty
<javafx.scene.paint.Paint> Determines the visualization of the selected area.final javafx.beans.property.ObjectProperty
<javafx.scene.paint.Paint> Determines the visualization of the selection's border.final javafx.beans.property.DoubleProperty
Determines the width of the selection's border.final javafx.beans.property.ReadOnlyBooleanProperty
Indicates whether theselection
is currently changing due to user interaction with the control.final javafx.beans.property.BooleanProperty
Indicates whether the overlay which displays the selection is mouse transparent.final javafx.beans.property.ObjectProperty
<javafx.geometry.Rectangle2D> The current selection as aRectangle2D
.final javafx.beans.property.BooleanProperty
Indicates whether the ratio of theselection
is fixed.final javafx.beans.property.ObjectProperty
<SnapshotView.Boundary> Indicates whichSnapshotView.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> 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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
TheselectionArea
, in which the user can create a selection, and theunselectedArea
, in which the unselected area is visualized, are limited to a certain area of the control. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final double
The maximal divergence between a selection's ratio and thefixedselectionRatio
for the selection to still have the correct ratio (seehasCorrectRatio
).static final String
The key of theproperty
which is used to updateselectionChanging
.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
ConstructorsConstructorDescriptionCreates a new SnapshotView.SnapshotView
(javafx.scene.Node node) Creates a new SnapshotView using the specified node. -
Method Summary
Modifier and TypeMethodDescriptionprotected javafx.scene.control.Skin
<?> javafx.scene.image.WritableImage
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
The value to which the selection ratio is fixed.static List
<javafx.css.CssMetaData<? extends javafx.css.Styleable, ?>> List
<javafx.css.CssMetaData<? extends javafx.css.Styleable, ?>> final double
final javafx.scene.Node
getNode()
final javafx.geometry.Rectangle2D
final SnapshotView.Boundary
final javafx.scene.paint.Paint
final javafx.scene.paint.Paint
final double
final SnapshotView.Boundary
final javafx.scene.paint.Paint
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
final javafx.beans.property.ReadOnlyBooleanProperty
Indicates whether there currently is a selection.final boolean
final boolean
final boolean
final boolean
final boolean
final javafx.beans.property.ObjectProperty
<javafx.scene.Node> TheNode
which will be displayed in the center of this control.final javafx.beans.property.BooleanProperty
Indicates whether the selection is currently active.final javafx.beans.property.BooleanProperty
Indicates whether the value of theselectionActive
property is managed by this control.final javafx.beans.property.ObjectProperty
<SnapshotView.Boundary> Indicates whichSnapshotView.Boundary
is set for the area the user can select.final javafx.beans.property.ObjectProperty
<javafx.scene.paint.Paint> Determines the visualization of the selected area.final javafx.beans.property.ObjectProperty
<javafx.scene.paint.Paint> Determines the visualization of the selection's border.final javafx.beans.property.DoubleProperty
Determines the width of the selection's border.final javafx.beans.property.ReadOnlyBooleanProperty
Indicates whether theselection
is currently changing due to user interaction with the control.final javafx.beans.property.BooleanProperty
Indicates whether the overlay which displays the selection is mouse transparent.final javafx.beans.property.ObjectProperty
<javafx.geometry.Rectangle2D> The current selection as aRectangle2D
.final javafx.beans.property.BooleanProperty
Indicates whether the ratio of theselection
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 newRectangle2D
from the specified arguments and sets it as the newselection
.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
Transforms theselection
to node coordinates by callingtransformToNodeCoordinates
.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> Indicates whichSnapshotView.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> 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 java.lang.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> nodePropertyTheNode
which will be displayed in the center of this control.The node's
boundsInParent
show its relative position inside this control. Since theselection
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> selectionPropertyThe current selection as aRectangle2D
. 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, anIllegalArgumentException
is thrown.The same is true if the
selectionAreaBoundary
is set toNODE
but with the stricter condition that the selection must lie within thenode
'sboundsInParent
.If the selection ratio is
fixed
, any new selection must have thefixedSelectionRatio
. Otherwise, anIllegalArgumentException
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
orRectangle2D.EMPTY
in which case no selection is displayed andhasSelection
isfalse
.- See Also:
-
hasSelection
public final javafx.beans.property.ReadOnlyBooleanProperty hasSelectionPropertyIndicates whether there currently is a selection. This will befalse
if theselection
property holdsnull
orRectangle2D.EMPTY
.- See Also:
-
selectionActive
public final javafx.beans.property.BooleanProperty selectionActivePropertyIndicates 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 selectionChangingPropertyIndicates whether theselection
is currently changing due to user interaction with the control. It will be set totrue
when changing the selection begins and set tofalse
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 selectionRatioFixedPropertyIndicates whether the ratio of theselection
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 istrue
, the user is limited to making selections with the ratio defined by thefixedSelectionRatio
property. If the ratio is fixed and a selection with a different ratio is set, anIllegalArgumentException
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 fixedSelectionRatioPropertyThe value to which the selection ratio is fixed. The ratio is defined aswidth / height
and its value must be strictly positive.If
selectionRatioFixed
istrue
, 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 callingsetSelection
), this ratio is checked and if violated anIllegalArgumentException
is thrown.If a selection exists and
selectionRatioFixed
is set totrue
, 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> selectionAreaBoundaryPropertyIndicates whichSnapshotView.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 fromCONTROL
toNODE
a possibly existing selection is resized accordingly.If the boundary is set to
NODE
, this is also respected when a newselection
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 anIllegalArgumentException
.Note that this does not change the reference coordinate system! The selection's coordinates are still interpreted relative to the
node
'sboundsInParent
.- Default value:
CONTROL
- See Also:
-
selectionActivityManaged
public final javafx.beans.property.BooleanProperty selectionActivityManagedPropertyIndicates whether the value of theselectionActive
property is managed by this control.If this property is set to
true
(which is the default) this control will update theselectionActive
property immediately after a new selection is set: if the new selection isnull
orRectangle2D.EMPTY
, it will be set tofalse
; otherwise totrue
.If this property is
false
this control will never changeselectionActive
'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 selectionMouseTransparentPropertyIndicates 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 displayednode
.- Default value:
false
- See Also:
-
unselectedAreaBoundary
public final javafx.beans.property.ObjectProperty<SnapshotView.Boundary> unselectedAreaBoundaryPropertyIndicates whichSnapshotView.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 displayednode
. In most cases this only makes sense if theselectionAreaBoundary
is also set toNODE
.- Default value:
SnapshotView.Boundary.CONTROL
- See Also:
-
selectionBorderPaint
public final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint> selectionBorderPaintPropertyDetermines the visualization of the selection's border.- Default value:
Color.WHITESMOKE
- See Also:
-
selectionBorderWidth
public final javafx.beans.property.DoubleProperty selectionBorderWidthPropertyDetermines 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> selectionAreaFillPropertyDetermines the visualization of the selected area.- Default value:
Color.TRANSPARENT
- See Also:
-
unselectedAreaFill
public final javafx.beans.property.ObjectProperty<javafx.scene.paint.Paint> unselectedAreaFillPropertyDetermines the visualization of the area outside of the selection.- Default value:
black
withopacity
0.5- See Also:
-
-
Field Details
-
MAX_SELECTION_RATIO_DIVERGENCE
public static final double MAX_SELECTION_RATIO_DIVERGENCEThe maximal divergence between a selection's ratio and thefixedselectionRatio
for the selection to still have the correct ratio (seehasCorrectRatio
).The divergence is expressed relative to the
fixedselectionRatio
.- See Also:
-
SELECTION_CHANGING_PROPERTY_KEY
The key of theproperty
which is used to updateselectionChanging
.
-
-
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 theselection
to node coordinates by callingtransformToNodeCoordinates
.- Returns:
- a
Rectangle2D
which expresses the selection in the node's coordinates - Throws:
IllegalStateException
- ifnode
isnull
orhasSelection
isfalse
- 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
- theRectangle2D
which will be transformed (must not benull
); its coordinates will be interpreted relative to the control (like theselection
)- Returns:
- a
Rectangle2D
with the same width and height as the specifiedarea
but with coordinates which are relative to the currentnode
- Throws:
IllegalStateException
- ifnode
isnull
-
createSnapshot
Creates a snapshot of the selected area of the node.- Returns:
- the
WritableImage
that holds the rendered selection - Throws:
IllegalStateException
- ifnode
isnull
orhasSelection
isfalse
- See Also:
-
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
- theSnapshotParameters
used for the snapshot (must not benull
); the viewport will be interpreted relative to this control (like theselection
)- Returns:
- the
WritableImage
that holds the rendered viewport - Throws:
IllegalStateException
- ifnode
isnull
- See Also:
-
getUserAgentStylesheet
- Overrides:
getUserAgentStylesheet
in classjavafx.scene.layout.Region
-
getClassCssMetaData
- Returns:
- the
CssMetaData
associated with this class, which includes theCssMetaData
of its super classes
-
getControlCssMetaData
- Overrides:
getControlCssMetaData
in classjavafx.scene.control.Control
-
createDefaultSkin
protected javafx.scene.control.Skin<?> createDefaultSkin()- Overrides:
createDefaultSkin
in classjavafx.scene.control.Control
-
nodeProperty
public final javafx.beans.property.ObjectProperty<javafx.scene.Node> nodeProperty()TheNode
which will be displayed in the center of this control.The node's
boundsInParent
show its relative position inside this control. Since theselection
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 aRectangle2D
. 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, anIllegalArgumentException
is thrown.The same is true if the
selectionAreaBoundary
is set toNODE
but with the stricter condition that the selection must lie within thenode
'sboundsInParent
.If the selection ratio is
fixed
, any new selection must have thefixedSelectionRatio
. Otherwise, anIllegalArgumentException
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
orRectangle2D.EMPTY
in which case no selection is displayed andhasSelection
isfalse
.- 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 theselectionAreaBoundary
or the selection ratio isfixed
and the new selection does not have thefixedSelectionRatio
.- See Also:
-
setSelection
public final void setSelection(double upperLeftX, double upperLeftY, double width, double height) Creates a newRectangle2D
from the specified arguments and sets it as the newselection
. It will have (upperLeftX
,upperLeftY
) as its upper left point and spanwidth
to the right andheight
down.- Parameters:
upperLeftX
- the x coordinate of the selection's upper left pointupperLeftY
- the y coordinate of the selection's upper left pointwidth
- the selection's widthheight
- the selection's height- Throws:
IllegalArgumentException
- if the selection is out of the bounds defined by theselectionAreaBoundary
or the selection ratio isfixed
and the new selection does not have thefixedSelectionRatio
.- See Also:
-
hasSelectionProperty
public final javafx.beans.property.ReadOnlyBooleanProperty hasSelectionProperty()Indicates whether there currently is a selection. This will befalse
if theselection
property holdsnull
orRectangle2D.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 theselection
is currently changing due to user interaction with the control. It will be set totrue
when changing the selection begins and set tofalse
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 theselection
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 istrue
, the user is limited to making selections with the ratio defined by thefixedSelectionRatio
property. If the ratio is fixed and a selection with a different ratio is set, anIllegalArgumentException
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 aswidth / height
and its value must be strictly positive.If
selectionRatioFixed
istrue
, 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 callingsetSelection
), this ratio is checked and if violated anIllegalArgumentException
is thrown.If a selection exists and
selectionRatioFixed
is set totrue
, 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
- iffixedSelectionRatio
is not strictly positive- See Also:
-
selectionAreaBoundaryProperty
public final javafx.beans.property.ObjectProperty<SnapshotView.Boundary> selectionAreaBoundaryProperty()Indicates whichSnapshotView.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 fromCONTROL
toNODE
a possibly existing selection is resized accordingly.If the boundary is set to
NODE
, this is also respected when a newselection
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 anIllegalArgumentException
.Note that this does not change the reference coordinate system! The selection's coordinates are still interpreted relative to the
node
'sboundsInParent
.- Default value:
CONTROL
- Returns:
- the property indicating the
SnapshotView.Boundary
for the area the user can select
-
getSelectionAreaBoundary
- Returns:
- the
SnapshotView.Boundary
for the area the user can select
-
setSelectionAreaBoundary
- Parameters:
selectionAreaBoundary
- the newSnapshotView.Boundary
for the area the user can select
-
selectionActivityManagedProperty
public final javafx.beans.property.BooleanProperty selectionActivityManagedProperty()Indicates whether the value of theselectionActive
property is managed by this control.If this property is set to
true
(which is the default) this control will update theselectionActive
property immediately after a new selection is set: if the new selection isnull
orRectangle2D.EMPTY
, it will be set tofalse
; otherwise totrue
.If this property is
false
this control will never changeselectionActive
'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 displayednode
.- 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 whichSnapshotView.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 displayednode
. In most cases this only makes sense if theselectionAreaBoundary
is also set toNODE
.- Default value:
SnapshotView.Boundary.CONTROL
- Returns:
- the property defining the
SnapshotView.Boundary
of the unselected area
-
getUnselectedAreaBoundary
- Returns:
- the
SnapshotView.Boundary
for the unselected area - See Also:
-
setUnselectedAreaBoundary
- Parameters:
unselectedAreaBoundary
- the newSnapshotView.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 newPaint
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 newPaint
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
withopacity
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 newPaint
of the area outside of the selection- See Also:
-
getUserAgentStylesheet
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 lookupfileName
- the name of the user agent stylesheet- Returns:
- the external form of the user agent stylesheet (the path)
-