javafx.scene.input

Class DragEvent

java.lang.Object

java.util.EventObject

javafx.event.Event

javafx.scene.input.InputEvent

javafx.scene.input.DragEvent

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public class DragEvent
extends InputEvent

Drag events replace mouse events during drag-and-drop gesture. The difference between press-drag-release and drag-and-drop gestures is described at 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 TransferModes 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() {
    @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() {
    @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() {
    @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.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and 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

Method Summary

Methods

Modifier and Type	Method and Description
void	acceptTransferModes(TransferMode... transferModes) Accepts this DragEvent, choosing the transfer mode for the drop operation.
Event	copyFor(java.lang.Object newSource, EventTarget newTarget) Creates and returns a copy of this event with the specified event source and target.
TransferMode	getAcceptedTransferMode() Gets transfer mode accepted by potential target.
Dragboard	getDragboard() A dragboard that is available to transfer data.
java.lang.Object	getGestureSource() The source object of the drag and drop gesture.
java.lang.Object	getGestureTarget() The target object of the drag and drop gesture.
double	getSceneX() Returns horizontal position of the event relative to the origin of the Scene that contains the DragEvent's source.
double	getSceneY() Returns vertical position of the event relative to the origin of the Scene 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.
boolean	isAccepted() Indicates if this event has been accepted.
boolean	isDropCompleted() Whether setDropCompleted(true) has been called on this event.
void	setDropCompleted(boolean isTransferDone) Indicates that transfer handling of this DragEvent was completed successfully during a DRAG_DROPPED event handler.

Methods inherited from class javafx.event.Event

clone, consume, fireEvent, getEventType, getTarget, isConsumed

Methods inherited from class java.util.EventObject

getSource, toString

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ANY

public static final EventType<DragEvent> ANY

Common supertype for all drag event types.

DRAG_ENTERED_TARGET

public static final EventType<DragEvent> 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.

See Also:

MouseEvent for more information about mouse entered/exited handling which is similar

DRAG_ENTERED

public static final EventType<DragEvent> 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 use DRAG_ENTERED_TARGET.

See Also:

MouseEvent for more information about mouse entered/exited handling which is similar

DRAG_EXITED_TARGET

public static final EventType<DragEvent> 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.

See Also:

MouseEvent for more information about mouse entered/exited handling which is similar

DRAG_EXITED

public static final EventType<DragEvent> 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 use DRAG_EXITED_TARGET.

See Also:

MouseEvent for more information about mouse entered/exited handling which is similar

DRAG_OVER

public static final EventType<DragEvent> DRAG_OVER

This event occurs when drag gesture progresses within this node.

DRAG_DROPPED

public static final EventType<DragEvent> DRAG_DROPPED

This event occurs when the mouse button is released during drag and drop gesture on a drop target. Transfer of data from the DragEvent's dragboard should happen in handler of this event.

DRAG_DONE

public static final EventType<DragEvent> DRAG_DONE

This event occurs on drag-and-drop gesture source after its data has been dropped on a drop target. The transferMode of the event shows what just happened at the drop target. If transferMode has the value MOVE, 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. A transferMode that has the value NONE indicates that no data was transferred during the drag and drop gesture.

Method Detail

copyFor

public Event copyFor(java.lang.Object newSource,
            EventTarget newTarget)

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 to null, it is replaced by the NULL_SOURCE_TARGET value.

Overrides:

copyFor in class Event

Parameters:

newSource - the new source of the copied event

newTarget - the new target of the copied event

Returns:

the event copy with the new source and target

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.

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 the Scene that contains the DragEvent's source. If the node is not in a Scene, then the value is relative to the boundsInParent of the root-most parent of the DragEvent's node.

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 the Scene that contains the DragEvent's source. If the node is not in a Scene, then the value is relative to the boundsInParent of the root-most parent of the DragEvent's node.

Returns:

vertical position of the event relative to the origin of the Scene that contains the DragEvent's source

getGestureSource

public final java.lang.Object getGestureSource()

The source object of the drag and drop gesture. Gesture source is the object that started drag and drop operation. The value null is valid in the case that the gesture comes from another application.

getGestureTarget

public final java.lang.Object getGestureTarget()

The target object of the drag and drop gesture. Gesture target is the object that accepts drag events. The value null 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.

getTransferMode

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

isAccepted

public final boolean isAccepted()

Indicates if this event has been accepted.

Default value:

false

See Also:

acceptTransferModes(javafx.scene.input.TransferMode...)

getAcceptedTransferMode

public final TransferMode getAcceptedTransferMode()

Gets transfer mode accepted by potential target.

Returns:

transfer mode accepted by potential target.

getDragboard

public final Dragboard getDragboard()

A dragboard that is available to transfer data. Data can be placed onto this dragboard in handler of the DRAG_DETECTED mouse event. Data can be copied from this dragboard in handler of the DRAG_DROPPED event.

acceptTransferModes

public void acceptTransferModes(TransferMode... transferModes)

Accepts this DragEvent, choosing the transfer mode for the drop operation. Used to indicate that the potential drop target that receives this event is a drop target from DRAG_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.

setDropCompleted

public void setDropCompleted(boolean isTransferDone)

Indicates that transfer handling of this DragEvent was completed successfully during a DRAG_DROPPED event handler. No dragboard access can happen after this call.

Parameters:

isTransferDone - true indicates that the transfer was successful.

Throws:

java.lang.IllegalStateException - if this is not a DRAG_DROPPED event

isDropCompleted

public boolean isDropCompleted()

Whether setDropCompleted(true) has been called on this event.

Returns:

true if setDropCompleted(true) has been called