- All Implemented Interfaces:
Serializable
,Cloneable
public final class DragEvent extends InputEvent
MouseEvent
.
Drag and drop gesture can be started by calling startDragAndDrop()
(on a node or scene) inside of a DRAG_DETECTED
event handler.
The data to be transfered to drop target are placed to a dragBoard
at this moment.
Drag entered/exited events behave similarly to mouse entered/exited
events, please see MouseEvent
overview.
Drag sources: initiating a drag and drop gesture
When a drag gesture is detected, an application can decide whether to start a drag and drop gesture or continue with a press-drag-release gesture.
The default drag detection mechanism uses mouse movements with a pressed
button in combination with hysteresis. This behavior can be
augmented by the application. Each MOUSE_PRESSED
and
MOUSE_DRAGGED
event has a dragDetect
flag that determines
whether a drag gesture has been detected. The default value of this flag
depends on the default detection mechanism and can be modified by calling
setDragDetect()
inside of an event handler. When processing of
one of these events ends with the dragDetect
flag set to true,
a DRAG_DETECTED
MouseEvent
is sent to the potential gesture
source (the object on which a mouse button has been pressed). This event
notifies about the gesture detection.
Inside a DRAG_DETECTED
event handler, if the
startDragAndDrop()
method is called on a node or scene and a dragged
data is made available to the returned Dragboard
, the object on which
startDragAndDrop()
has been called is considred a gesture source
and the drag and drop gesture is started. The Dragboard
has system
clipboard functionality but is specifically used for drag and drop data
transfer.
The startDragAndDrop()
method takes a set of TransferMode
s
supported by the gesture source. For instance passing only
TransferMode.COPY
indicates that the gesture source allows only
copying of the data, not moving or referencing.
Following example shows a simple drag and drop source:
Rectangle rect = new Rectangle(100, 100); rect.setOnDragDetected(new EventHandler<MouseEvent>() { @Override public void handle(MouseEvent event) { Dragboard db = startDragAndDrop(TransferMode.ANY); ClipboardContent content = new ClipboardContent(); content.putString("Hello!"); db.setContent(content); event.consume(); } });
Potential drop targets
After the drag and drop gesture has been started, any object
(Node
, Scene
) over which the mouse is dragged is
a potential drop target.
When the mouse is dragged into the boundaries of potential drop target,
the potential target gets a DRAG_ENTERED
event. When the mouse is
dragged outside of the potential target's bounds, it gets a
DRAG_EXITED
event. There are also the bubbling
DRAG_ENTERED_TARGET
and DRAG_EXITED_TARGET
variants. They
behave similarly to mouse entered/exited events, please see
MouseEvent
overview.
A potential drop target can decide to change its appearance to
let the user know that the dragged data can be dropped on it. This can be
done in a DRAG_OVER
event handler, based on the position of the
mouse. Another option is to change the potential target's appearance in
a DRAG_ENTERED
and DRAG_EXITED
handlers.
In DRAG_OVER
event handler a potential drop target has the ability
to make it known that it is an actual target. This is done by calling
acceptTransferModes(TransferMode...)
on the event,
passing transfer modes it is willing to accept.
If it is not called during the event delivery or if none of the
passed transfer modes is supported by gesture source, then the potential
drop target is not considered to be an actual drop target.
When deciding weather to accept the event by calling acceptTransferModes(TransferMode...)
,
the type of data available on the Dragboard
should be considered.
Access to the Dragboard
is provided by the getDragboard()
method.
When accepting an event, the potential gesture target decides which
TransferMode
is accepted for the operation. To make the decision,
DragBoard.getTransferModes()
(set of transfer modes supported by
the gesture source) and DragEvent.getTransferMode()
(default
transfer mode issued by platform, driven by key modifiers) can be used.
It is poosible to pass more transfer modes into the
acceptTransferModes(TransferMode...)
method. In this case
it makes the decision in behalf of the
application (it chooses the default mode if it's supported by gesture source
and accepted by gesture target, otherwise it chooses the most common mode
of the supported and accepted ones).
The DRAG_DROPPED
event's getTransferMode()
later reports the
transfer mode accepted by the DRAG_OVER
event handler.
A drag and drop gesture ends when the mouse button is released.
If this happens over a gesture target that accepted previous DRAG_OVER
events with a transfer mode supported by gesture source,
a DRAG_DROPPED
event is sent to the gesture target.
In its handler, the gesture target can access the data on the dragboard.
After data has been transferred (or decided not to transfer), the gesture
needs to be completed by calling setDropCompleted(Boolean)
on the event.
The Boolean
argument indicates if the data has been transferred
successfully or not. If it is not called, the gesture is considered
unsuccessful.
Following example shows a simple drag and drop target for text data:
Rectangle rect = new Rectangle(100, 100); rect.setOnDragOver(new EventHandler<DragEvent>() { @Override public void handle(DragEvent event) { Dragboard db = event.getDragboard(); if (db.hasString()) { event.acceptTransferModes(TransferMode.COPY_OR_MOVE); } event.consume(); } }); rect.setOnDragDropped(new EventHandler<DragEvent>() { @Override public void handle(DragEvent event) { Dragboard db = event.getDragboard(); boolean success = false; if (db.hasString()) { System.out.println("Dropped: " + db.getString()); success = true; } event.setDropCompleted(success); event.consume(); } });
Drag sources: finalizing drag and drop gesture
After the gesture has been finished, whether by successful or unsuccessful
data transfer or being canceled, the DRAG_DONE
event is sent to
the gesture source. The getTransferMode()
method of the event
indicates to the gesture source how the transfer of data was completed.
If the transfer mode has the value MOVE
, then this allows the source
to clear out its data. Clearing the source's data gives the appropriate
appearance to a user that the data has been moved by the drag and drop
gesture. If it has the value null
, then the drag and drop gesture
ended without any data being transferred. This could happen as a result of
a mouse release event over a node that is not a drop target, or the user
pressing the ESC key to cancel the drag and drop gesture, or by
the gesture target reporting an unsuccessful data transfer.
- Since:
- JavaFX 2.0
- See Also:
- Serialized Form
-
Field Summary
Fields Modifier and Type Field Description static EventType<DragEvent>
ANY
Common supertype for all drag event types.static EventType<DragEvent>
DRAG_DONE
This event occurs on drag-and-drop gesture source after its data has been dropped on a drop target.static EventType<DragEvent>
DRAG_DROPPED
This event occurs when the mouse button is released during drag and drop gesture on a drop target.static EventType<DragEvent>
DRAG_ENTERED
This event occurs when drag gesture enters a node.static EventType<DragEvent>
DRAG_ENTERED_TARGET
This event occurs when drag gesture enters a node.static EventType<DragEvent>
DRAG_EXITED
This event occurs when drag gesture exits a node.static EventType<DragEvent>
DRAG_EXITED_TARGET
This event occurs when drag gesture exits a node.static EventType<DragEvent>
DRAG_OVER
This event occurs when drag gesture progresses within this node.Fields inherited from class javafx.event.Event
consumed, eventType, NULL_SOURCE_TARGET, target
Fields inherited from class java.util.EventObject
source
-
Constructor Summary
Constructors Constructor Description DragEvent(Object source, EventTarget target, EventType<DragEvent> eventType, Dragboard dragboard, double x, double y, double screenX, double screenY, TransferMode transferMode, Object gestureSource, Object gestureTarget, PickResult pickResult)
Constructs new DragEvent event.DragEvent(EventType<DragEvent> eventType, Dragboard dragboard, double x, double y, double screenX, double screenY, TransferMode transferMode, Object gestureSource, Object gestureTarget, PickResult pickResult)
Constructs new DragEvent event with empty source and target. -
Method Summary
Modifier and Type Method Description void
acceptTransferModes(TransferMode... transferModes)
Accepts thisDragEvent
, choosing the transfer mode for the drop operation.DragEvent
copyFor(Object newSource, EventTarget newTarget)
Creates and returns a copy of this event with the specified event source and target.DragEvent
copyFor(Object source, EventTarget target, Object gestureSource, Object gestureTarget, EventType<DragEvent> eventType)
Creates a copy of the given drag event with the given fields substituted.DragEvent
copyFor(Object source, EventTarget target, EventType<DragEvent> type)
Creates a copy of the given drag event with the given fields substituted.TransferMode
getAcceptedTransferMode()
Gets transfer mode accepted by potential target.Object
getAcceptingObject()
The object that accepted the drag.Dragboard
getDragboard()
A dragboard that is available to transfer data.EventType<DragEvent>
getEventType()
Gets the event type of this event.Object
getGestureSource()
The source object of the drag and drop gesture.Object
getGestureTarget()
The target object of the drag and drop gesture.PickResult
getPickResult()
Returns information about the pick.double
getSceneX()
Returns horizontal position of the event relative to the origin of theScene
that contains the DragEvent's source.double
getSceneY()
Returns vertical position of the event relative to the origin of theScene
that contains the DragEvent's source.double
getScreenX()
Returns absolute horizontal position of the event.double
getScreenY()
Returns absolute vertical position of the event.TransferMode
getTransferMode()
Data transfer mode.double
getX()
Horizontal position of the event relative to the origin of the DragEvent's source.double
getY()
Vertical position of the event relative to the origin of the DragEvent's source.double
getZ()
Depth position of the event relative to the origin of the MouseEvent's source.boolean
isAccepted()
Indicates if this event has been accepted.boolean
isDropCompleted()
WhethersetDropCompleted(true)
has been called on this event.void
setDropCompleted(boolean isTransferDone)
Indicates that transfer handling of thisDragEvent
was completed successfully during aDRAG_DROPPED
event handler.Methods inherited from class java.util.EventObject
getSource, toString
-
Field Details
-
ANY
Common supertype for all drag event types. -
DRAG_ENTERED_TARGET
This event occurs when drag gesture enters a node. It's the bubbling variant, which is delivered also to all parents of the entered node (unless it was consumed). When notifications about entering some of node's children are not desired,DRAG_ENTERED
event handler should be used. -
DRAG_ENTERED
This event occurs when drag gesture enters a node. This event type is delivered only to the entered node, if parents want to filter it or get the bubbling event, they need to useDRAG_ENTERED_TARGET
. -
DRAG_EXITED_TARGET
This event occurs when drag gesture exits a node. It's the bubbling variant, which is delivered also to all parents of the eixited node (unless it was consumed). When notifications about exiting some of node's children are not desired,DRAG_EXITED
event handler should be used. -
DRAG_EXITED
This event occurs when drag gesture exits a node. This event type is delivered only to the exited node, if parents want to filter it or get the bubbling event, they need to useDRAG_EXITED_TARGET
. -
DRAG_OVER
This event occurs when drag gesture progresses within this node. -
DRAG_DROPPED
-
DRAG_DONE
This event occurs on drag-and-drop gesture source after its data has been dropped on a drop target. ThetransferMode
of the event shows what just happened at the drop target. IftransferMode
has the valueMOVE
, then the source can clear out its data. Clearing the source's data gives the appropriate appearance to a user that the data has been moved by the drag and drop gesture. AtransferMode
that has the valueNONE
indicates that no data was transferred during the drag and drop gesture.
-
-
Constructor Details
-
DragEvent
public DragEvent(Object source, EventTarget target, EventType<DragEvent> eventType, Dragboard dragboard, double x, double y, double screenX, double screenY, TransferMode transferMode, Object gestureSource, Object gestureTarget, PickResult pickResult)Constructs new DragEvent event. For DRAG_DROPPED and DRAG_DONE event types, theaccepted
state andacceptedTransferMode
are set according to the passedtransferMode
.- Parameters:
source
- the source of the event. Can be null.target
- the target of the event. Can be null.eventType
- The type of the event.dragboard
- the dragboard of the event.x
- The x with respect to the scene.y
- The y with respect to the scene.screenX
- The x coordinate relative to screen.screenY
- The y coordinate relative to screen.transferMode
- the transfer mode of the event.gestureSource
- the source of the DnD gesture of the event.gestureTarget
- the target of the DnD gesture of the event.pickResult
- pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates and the target- Since:
- JavaFX 8.0
-
DragEvent
public DragEvent(EventType<DragEvent> eventType, Dragboard dragboard, double x, double y, double screenX, double screenY, TransferMode transferMode, Object gestureSource, Object gestureTarget, PickResult pickResult)Constructs new DragEvent event with empty source and target.- Parameters:
eventType
- The type of the event.dragboard
- the dragboard of the event.x
- The x with respect to the scene.y
- The y with respect to the scene.screenX
- The x coordinate relative to screen.screenY
- The y coordinate relative to screen.transferMode
- the transfer mode of the event.gestureSource
- the source of the DnD gesture of the event.gestureTarget
- the target of the DnD gesture of the event.pickResult
- pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates- Since:
- JavaFX 8.0
-
-
Method Details
-
copyFor
public DragEvent copyFor(Object source, EventTarget target, Object gestureSource, Object gestureTarget, EventType<DragEvent> eventType)Creates a copy of the given drag event with the given fields substituted.- Parameters:
source
- the new source of the copied eventtarget
- the new target of the copied eventgestureSource
- the new gesture source.gestureTarget
- the new gesture target.eventType
- the new eventType- Returns:
- the event copy with the fields
- Since:
- JavaFX 8.0
-
copyFor
Description copied from class:Event
Creates and returns a copy of this event with the specified event source and target. If the source or target is set tonull
, it is replaced by theNULL_SOURCE_TARGET
value. -
copyFor
Creates a copy of the given drag event with the given fields substituted.- Parameters:
source
- source of the copied eventtarget
- target of the copied eventtype
- type of event- Returns:
- the event copy with the fields
- Since:
- JavaFX 8.0
-
getEventType
Description copied from class:Event
Gets the event type of this event. Objects of the sameEvent
class can have different event types. These event types further specify what kind of event occurred.- Overrides:
getEventType
in classInputEvent
- Returns:
- the event type
-
getX
public final double getX()Horizontal position of the event relative to the origin of the DragEvent's source.- Returns:
- horizontal position of the event relative to the origin of the DragEvent's source
-
getY
public final double getY()Vertical position of the event relative to the origin of the DragEvent's source.- Returns:
- vertical position of the event relative to the origin of the DragEvent's source
-
getZ
public final double getZ()Depth position of the event relative to the origin of the MouseEvent's source.- Returns:
- depth position of the event relative to the origin of the MouseEvent's source
- Since:
- JavaFX 8.0
-
getScreenX
public final double getScreenX()Returns absolute horizontal position of the event.- Returns:
- absolute horizontal position of the event
-
getScreenY
public final double getScreenY()Returns absolute vertical position of the event.- Returns:
- absolute vertical position of the event
-
getSceneX
public final double getSceneX()Returns horizontal position of the event relative to the origin of theScene
that contains the DragEvent's source. If the node is not in aScene
, then the value is relative to the boundsInParent of the root-most parent of the DragEvent's node. Note that in 3D scene, this represents the flat coordinates after applying the projection transformations.- Returns:
- horizontal position of the event relative to the
origin of the
Scene
that contains the DragEvent's source
-
getSceneY
public final double getSceneY()Returns vertical position of the event relative to the origin of theScene
that contains the DragEvent's source. If the node is not in aScene
, then the value is relative to the boundsInParent of the root-most parent of the DragEvent's node. Note that in 3D scene, this represents the flat coordinates after applying the projection transformations.- Returns:
- vertical position of the event relative to the
origin of the
Scene
that contains the DragEvent's source
-
getPickResult
Returns information about the pick.- Returns:
- new PickResult object that contains information about the pick
- Since:
- JavaFX 8.0
-
getGestureSource
The source object of the drag and drop gesture. Gesture source is the object that started drag and drop operation. The valuenull
is valid in the case that the gesture comes from another application.- Returns:
- the source object of the drag and drop gesture
-
getGestureTarget
The target object of the drag and drop gesture. Gesture target is the object that accepts drag events. The valuenull
is valid in the case that the drag and drop gesture has been canceled or completed without a transfer taking place or there is currently no event target accepting the drag events.- Returns:
- the target object of the drag and drop gesture
-
getTransferMode
Data transfer mode. Before the data transfer is is performed, this is the default transfer mode set by system according to input events such as the user holding some modifiers. In time of data transfer (in DRAG_DROPPED event) it determines the transfer mode accepted by previous DRAG_OVER handler. After the data transfer (in DRAG_DONE event) it determines the actual mode of the transfer done.- Returns:
- the data transfer mode
-
isAccepted
public final boolean isAccepted()Indicates if this event has been accepted.- Default value:
- false
- Returns:
- is this event has been accepted
- See Also:
acceptTransferModes(javafx.scene.input.TransferMode...)
-
getAcceptedTransferMode
Gets transfer mode accepted by potential target.- Returns:
- transfer mode accepted by potential target
-
getAcceptingObject
The object that accepted the drag.- Returns:
- the object that accepted the drag
- Since:
- JavaFX 8.0
-
getDragboard
A dragboard that is available to transfer data. Data can be placed onto this dragboard in handler of theDRAG_DETECTED
mouse event. Data can be copied from this dragboard in handler of theDRAG_DROPPED
event.- Returns:
- a dragboard that is available to transfer data
-
acceptTransferModes
Accepts thisDragEvent
, choosing the transfer mode for the drop operation. Used to indicate that the potential drop target that receives this event is a drop target fromDRAG_OVER
event handler.It accepts one of the transfer modes that are both passed into this method and supported by the gesture source. It accepts the default transfer mode if possible, otherwise the most common one of the acceptable modes.
- Parameters:
transferModes
- the transfer mode for the drop operation.
-
setDropCompleted
public void setDropCompleted(boolean isTransferDone)Indicates that transfer handling of thisDragEvent
was completed successfully during aDRAG_DROPPED
event handler. Nodragboard
access can happen after this call.- Parameters:
isTransferDone
-true
indicates that the transfer was successful.- Throws:
IllegalStateException
- if this is not a DRAG_DROPPED event
-
isDropCompleted
public boolean isDropCompleted()WhethersetDropCompleted(true)
has been called on this event.- Returns:
- true if
setDropCompleted(true)
has been called
-