DragEvent (JavaFX 13)

Module javafx.graphics
Package 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:
    `Serializable`, `Cloneable`

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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `acceptTransferModes​(TransferMode... transferModes)` | Accepts this `DragEvent`, 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 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.
    `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()` | 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, 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.

  - ### Constructor Detail

    - #### 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, the `accepted` state and `acceptedTransferMode` are set according to the passed `transferMode`.
      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 Detail

    - #### 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 event
        `target` - the new target of the copied event
        `gestureSource` - 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

          public DragEvent copyFor​(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

    - #### copyFor

          public DragEvent copyFor​(Object source,
                                   EventTarget target,
                                   EventType<DragEvent> type)

      Creates a copy of the given drag event with the given fields substituted.
      Parameters:
        `source` - source of the copied event
        `target` - target of the copied event
        `type` - type of event
      Returns:
        the event copy with the fields
      Since:
        JavaFX 8.0

    - #### getEventType

          public EventType<DragEvent> getEventType()

      Description copied from class: `Event`
      Gets the event type of this event. Objects of the same `Event` class can have different event types. These event types further specify what kind of event occurred.
      Overrides:
        `getEventType` in class `InputEvent`
      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 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. 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 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. 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

          public final PickResult getPickResult()

      Returns information about the pick.
      Returns:
        new PickResult object that contains information about the pick
      Since:
        JavaFX 8.0

    - #### getGestureSource

          public final 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.
      Returns:
        the source object of the drag and drop gesture

    - #### getGestureTarget

          public final 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.
      Returns:
        the target object of the drag and drop gesture

    - #### 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.
      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

          public final TransferMode getAcceptedTransferMode()

      Gets transfer mode accepted by potential target.
      Returns:
        transfer mode accepted by potential target

    - #### getAcceptingObject

          public final Object getAcceptingObject()

      The object that accepted the drag.
      Returns:
        the object that accepted the drag
      Since:
        JavaFX 8.0

    - #### 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.
      Returns:
        a dragboard that is available to transfer data

    - #### 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.

      Parameters:
        `transferModes` - the transfer mode for the drop operation.

    - #### 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:
        `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