java.awt.dnd

## Class DragSource

- java.lang.Object
- - java.awt.dnd.DragSource

- All Implemented Interfaces:
    Serializable

      public class DragSource
      extends Object
      implements Serializable

  The `DragSource` is the entity responsible for the initiation of the Drag and Drop operation, and may be used in a number of scenarios:
  - 1 default instance per JVM for the lifetime of that JVM.
  - 1 instance per class of potential Drag Initiator object (e.g TextField). [implementation dependent]
  - 1 per instance of a particular `Component`, or application specific object associated with a `Component` instance in the GUI. [implementation dependent]
  - Some other arbitrary association. [implementation dependent]
  Once the `DragSource` is obtained, a `DragGestureRecognizer` should also be obtained to associate the `DragSource` with a particular `Component`.

  The initial interpretation of the user's gesture, and the subsequent starting of the drag operation are the responsibility of the implementing `Component`, which is usually implemented by a `DragGestureRecognizer`.

  When a drag gesture occurs, the `DragSource`'s startDrag() method shall be invoked in order to cause processing of the user's navigational gestures and delivery of Drag and Drop protocol notifications. A `DragSource` shall only permit a single Drag and Drop operation to be current at any one time, and shall reject any further startDrag() requests by throwing an `IllegalDnDOperationException` until such time as the extant operation is complete.

  The startDrag() method invokes the createDragSourceContext() method to instantiate an appropriate `DragSourceContext` and associate the `DragSourceContextPeer` with that.

  If the Drag and Drop System is unable to initiate a drag operation for some reason, the startDrag() method throws a `java.awt.dnd.InvalidDnDOperationException` to signal such a condition. Typically this exception is thrown when the underlying platform system is either not in a state to initiate a drag, or the parameters specified are invalid.

  Note that during the drag, the set of operations exposed by the source at the start of the drag operation may not change until the operation is complete. The operation(s) are constant for the duration of the operation with respect to the `DragSource`.

  Since:
    1.2
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Cursor` | `DefaultCopyDrop` The default `Cursor` to use with a copy operation indicating that a drop is currently allowed.
    `static Cursor` | `DefaultCopyNoDrop` The default `Cursor` to use with a copy operation indicating that a drop is currently not allowed.
    `static Cursor` | `DefaultLinkDrop` The default `Cursor` to use with a link operation indicating that a drop is currently allowed.
    `static Cursor` | `DefaultLinkNoDrop` The default `Cursor` to use with a link operation indicating that a drop is currently not allowed.
    `static Cursor` | `DefaultMoveDrop` The default `Cursor` to use with a move operation indicating that a drop is currently allowed.
    `static Cursor` | `DefaultMoveNoDrop` The default `Cursor` to use with a move operation indicating that a drop is currently not allowed.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DragSource()` Creates a new `DragSource`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDragSourceListener(DragSourceListener dsl)` Adds the specified `DragSourceListener` to this `DragSource` to receive drag source events during drag operations intiated with this `DragSource`.
    `void` | `addDragSourceMotionListener(DragSourceMotionListener dsml)` Adds the specified `DragSourceMotionListener` to this `DragSource` to receive drag motion events during drag operations intiated with this `DragSource`.
    `DragGestureRecognizer` | `createDefaultDragGestureRecognizer(Component c, int actions, DragGestureListener dgl)` Creates a new `DragGestureRecognizer` that implements the default abstract subclass of `DragGestureRecognizer` for this `DragSource`, and sets the specified `Component` and `DragGestureListener` on the newly created object.
    `<T extends DragGestureRecognizer> T` | `createDragGestureRecognizer(Class<T> recognizerAbstractClass, Component c, int actions, DragGestureListener dgl)` Creates a new `DragGestureRecognizer` that implements the specified abstract subclass of `DragGestureRecognizer`, and sets the specified `Component` and `DragGestureListener` on the newly created object.
    `protected DragSourceContext` | `createDragSourceContext(java.awt.dnd.peer.DragSourceContextPeer dscp, DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable t, DragSourceListener dsl)` Creates the `DragSourceContext` to handle the current drag operation.
    `static DragSource` | `getDefaultDragSource()` Gets the `DragSource` object associated with the underlying platform.
    `DragSourceListener[]` | `getDragSourceListeners()` Gets all the `DragSourceListener`s registered with this `DragSource`.
    `DragSourceMotionListener[]` | `getDragSourceMotionListeners()` Gets all of the `DragSourceMotionListener`s registered with this `DragSource`.
    `static int` | `getDragThreshold()` Returns the drag gesture motion threshold.
    `FlavorMap` | `getFlavorMap()` This method returns the `FlavorMap` for this `DragSource`.
    `<T extends EventListener> T[]` | `getListeners(Class<T> listenerType)` Gets all the objects currently registered as `FooListener`s upon this `DragSource`.
    `static boolean` | `isDragImageSupported()` Reports whether or not drag `Image` support is available on the underlying platform.
    `void` | `removeDragSourceListener(DragSourceListener dsl)` Removes the specified `DragSourceListener` from this `DragSource`.
    `void` | `removeDragSourceMotionListener(DragSourceMotionListener dsml)` Removes the specified `DragSourceMotionListener` from this `DragSource`.
    `void` | `startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point dragOffset, Transferable transferable, DragSourceListener dsl)` Start a drag, given the `DragGestureEvent` that initiated the drag, the initial `Cursor` to use, the `Image` to drag, the offset of the `Image` origin from the hotspot of the `Cursor` at the instant of the trigger, the subject data of the drag, and the `DragSourceListener`.
    `void` | `startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap)` Start a drag, given the `DragGestureEvent` that initiated the drag, the initial `Cursor` to use, the `Image` to drag, the offset of the `Image` origin from the hotspot of the `Cursor` at the instant of the trigger, the `Transferable` subject data of the drag, the `DragSourceListener`, and the `FlavorMap`.
    `void` | `startDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl)` Start a drag, given the `DragGestureEvent` that initiated the drag, the initial `Cursor` to use, the `Transferable` subject data of the drag, and the `DragSourceListener`.
    `void` | `startDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap)` Start a drag, given the `DragGestureEvent` that initiated the drag, the initial `Cursor` to use, the `Transferable` subject data of the drag, the `DragSourceListener`, and the `FlavorMap`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DefaultCopyDrop

          public static final Cursor DefaultCopyDrop

      The default `Cursor` to use with a copy operation indicating that a drop is currently allowed. `null` if `GraphicsEnvironment.isHeadless()` returns `true`.
      See Also:
        `GraphicsEnvironment.isHeadless()`

    - #### DefaultMoveDrop

          public static final Cursor DefaultMoveDrop

      The default `Cursor` to use with a move operation indicating that a drop is currently allowed. `null` if `GraphicsEnvironment.isHeadless()` returns `true`.
      See Also:
        `GraphicsEnvironment.isHeadless()`

    - #### DefaultLinkDrop

          public static final Cursor DefaultLinkDrop

      The default `Cursor` to use with a link operation indicating that a drop is currently allowed. `null` if `GraphicsEnvironment.isHeadless()` returns `true`.
      See Also:
        `GraphicsEnvironment.isHeadless()`

    - #### DefaultCopyNoDrop

          public static final Cursor DefaultCopyNoDrop

      The default `Cursor` to use with a copy operation indicating that a drop is currently not allowed. `null` if `GraphicsEnvironment.isHeadless()` returns `true`.
      See Also:
        `GraphicsEnvironment.isHeadless()`

    - #### DefaultMoveNoDrop

          public static final Cursor DefaultMoveNoDrop

      The default `Cursor` to use with a move operation indicating that a drop is currently not allowed. `null` if `GraphicsEnvironment.isHeadless()` returns `true`.
      See Also:
        `GraphicsEnvironment.isHeadless()`

    - #### DefaultLinkNoDrop

          public static final Cursor DefaultLinkNoDrop

      The default `Cursor` to use with a link operation indicating that a drop is currently not allowed. `null` if `GraphicsEnvironment.isHeadless()` returns `true`.
      See Also:
        `GraphicsEnvironment.isHeadless()`

  - ### Constructor Detail

    - #### DragSource

          public DragSource()
                     throws HeadlessException

      Creates a new `DragSource`.
      Throws:
        `HeadlessException` - if GraphicsEnvironment.isHeadless() returns true
      See Also:
        `GraphicsEnvironment.isHeadless()`

  - ### Method Detail

    - #### getDefaultDragSource

          public static DragSource getDefaultDragSource()

      Gets the `DragSource` object associated with the underlying platform.
      Returns:
        the platform DragSource
      Throws:
        `HeadlessException` - if GraphicsEnvironment.isHeadless() returns true
      See Also:
        `GraphicsEnvironment.isHeadless()`

    - #### isDragImageSupported

          public static boolean isDragImageSupported()

      Reports whether or not drag `Image` support is available on the underlying platform.

      Returns:
        if the Drag Image support is available on this platform

    - #### startDrag

          public void startDrag(DragGestureEvent trigger,
                                Cursor dragCursor,
                                Image dragImage,
                                Point imageOffset,
                                Transferable transferable,
                                DragSourceListener dsl,
                                FlavorMap flavorMap)
                         throws InvalidDnDOperationException

      Start a drag, given the `DragGestureEvent` that initiated the drag, the initial `Cursor` to use, the `Image` to drag, the offset of the `Image` origin from the hotspot of the `Cursor` at the instant of the trigger, the `Transferable` subject data of the drag, the `DragSourceListener`, and the `FlavorMap`.

      Parameters:
        `trigger` - the `DragGestureEvent` that initiated the drag
        `dragCursor` - the initial `Cursor` for this drag operation or `null` for the default cursor handling; see DragSourceContext for more details on the cursor handling mechanism during drag and drop
        `dragImage` - the image to drag or `null`
        `imageOffset` - the offset of the `Image` origin from the hotspot of the `Cursor` at the instant of the trigger
        `transferable` - the subject data of the drag
        `dsl` - the `DragSourceListener`
        `flavorMap` - the `FlavorMap` to use, or `null`

      Throws:
        `InvalidDnDOperationException` - if the Drag and Drop system is unable to initiate a drag operation, or if the user attempts to start a drag while an existing drag operation is still executing

    - #### startDrag

          public void startDrag(DragGestureEvent trigger,
                                Cursor dragCursor,
                                Transferable transferable,
                                DragSourceListener dsl,
                                FlavorMap flavorMap)
                         throws InvalidDnDOperationException

      Start a drag, given the `DragGestureEvent` that initiated the drag, the initial `Cursor` to use, the `Transferable` subject data of the drag, the `DragSourceListener`, and the `FlavorMap`.

      Parameters:
        `trigger` - the `DragGestureEvent` that initiated the drag
        `dragCursor` - the initial `Cursor` for this drag operation or `null` for the default cursor handling; see DragSourceContext for more details on the cursor handling mechanism during drag and drop
        `transferable` - the subject data of the drag
        `dsl` - the `DragSourceListener`
        `flavorMap` - the `FlavorMap` to use or `null`

      Throws:
        `InvalidDnDOperationException` - if the Drag and Drop system is unable to initiate a drag operation, or if the user attempts to start a drag while an existing drag operation is still executing

    - #### startDrag

          public void startDrag(DragGestureEvent trigger,
                                Cursor dragCursor,
                                Image dragImage,
                                Point dragOffset,
                                Transferable transferable,
                                DragSourceListener dsl)
                         throws InvalidDnDOperationException

      Start a drag, given the `DragGestureEvent` that initiated the drag, the initial `Cursor` to use, the `Image` to drag, the offset of the `Image` origin from the hotspot of the `Cursor` at the instant of the trigger, the subject data of the drag, and the `DragSourceListener`.

      Parameters:
        `trigger` - the `DragGestureEvent` that initiated the drag
        `dragCursor` - the initial `Cursor` for this drag operation or `null` for the default cursor handling; see DragSourceContext for more details on the cursor handling mechanism during drag and drop
        `dragImage` - the `Image` to drag or `null`
        `dragOffset` - the offset of the `Image` origin from the hotspot of the `Cursor` at the instant of the trigger
        `transferable` - the subject data of the drag
        `dsl` - the `DragSourceListener`

      Throws:
        `InvalidDnDOperationException` - if the Drag and Drop system is unable to initiate a drag operation, or if the user attempts to start a drag while an existing drag operation is still executing

    - #### startDrag

          public void startDrag(DragGestureEvent trigger,
                                Cursor dragCursor,
                                Transferable transferable,
                                DragSourceListener dsl)
                         throws InvalidDnDOperationException

      Start a drag, given the `DragGestureEvent` that initiated the drag, the initial `Cursor` to use, the `Transferable` subject data of the drag, and the `DragSourceListener`.

      Parameters:
        `trigger` - the `DragGestureEvent` that initiated the drag
        `dragCursor` - the initial `Cursor` for this drag operation or `null` for the default cursor handling; see DragSourceContext class for more details on the cursor handling mechanism during drag and drop
        `transferable` - the subject data of the drag
        `dsl` - the `DragSourceListener`

      Throws:
        `InvalidDnDOperationException` - if the Drag and Drop system is unable to initiate a drag operation, or if the user attempts to start a drag while an existing drag operation is still executing

    - #### createDragSourceContext

          protected DragSourceContext createDragSourceContext(java.awt.dnd.peer.DragSourceContextPeer dscp,
                                                              DragGestureEvent dgl,
                                                              Cursor dragCursor,
                                                              Image dragImage,
                                                              Point imageOffset,
                                                              Transferable t,
                                                              DragSourceListener dsl)

      Creates the `DragSourceContext` to handle the current drag operation.

      To incorporate a new `DragSourceContext` subclass, subclass `DragSource` and override this method.

      If `dragImage` is `null`, no image is used to represent the drag over feedback for this drag operation, but `NullPointerException` is not thrown.

      If `dsl` is `null`, no drag source listener is registered with the created `DragSourceContext`, but `NullPointerException` is not thrown.

      Parameters:
        `dscp` - The `DragSourceContextPeer` for this drag
        `dgl` - The `DragGestureEvent` that triggered the drag
        `dragCursor` - The initial `Cursor` for this drag operation or `null` for the default cursor handling; see DragSourceContext class for more details on the cursor handling mechanism during drag and drop
        `dragImage` - The `Image` to drag or `null`
        `imageOffset` - The offset of the `Image` origin from the hotspot of the cursor at the instant of the trigger
        `t` - The subject data of the drag
        `dsl` - The `DragSourceListener`
      Returns:
        the `DragSourceContext`
      Throws:
        `NullPointerException` - if `dscp` is `null`
        `NullPointerException` - if `dgl` is `null`
        `NullPointerException` - if `dragImage` is not `null` and `imageOffset` is `null`
        `NullPointerException` - if `t` is `null`
        `IllegalArgumentException` - if the `Component` associated with the trigger event is `null`.
        `IllegalArgumentException` - if the `DragSource` for the trigger event is `null`.
        `IllegalArgumentException` - if the drag action for the trigger event is `DnDConstants.ACTION_NONE`.
        `IllegalArgumentException` - if the source actions for the `DragGestureRecognizer` associated with the trigger event are equal to `DnDConstants.ACTION_NONE`.

    - #### getFlavorMap

          public FlavorMap getFlavorMap()

      This method returns the `FlavorMap` for this `DragSource`.

      Returns:
        the `FlavorMap` for this `DragSource`

    - #### createDragGestureRecognizer

          public <T extends DragGestureRecognizer> T createDragGestureRecognizer(Class<T> recognizerAbstractClass,
                                                                                 Component c,
                                                                                 int actions,
                                                                                 DragGestureListener dgl)

      Creates a new `DragGestureRecognizer` that implements the specified abstract subclass of `DragGestureRecognizer`, and sets the specified `Component` and `DragGestureListener` on the newly created object.

      Parameters:
        `recognizerAbstractClass` - the requested abstract type
        `actions` - the permitted source drag actions
        `c` - the `Component` target
        `dgl` - the `DragGestureListener` to notify

      Returns:
        the new `DragGestureRecognizer` or `null` if the `Toolkit.createDragGestureRecognizer` method has no implementation available for the requested `DragGestureRecognizer` subclass and returns `null`

    - #### createDefaultDragGestureRecognizer

          public DragGestureRecognizer createDefaultDragGestureRecognizer(Component c,
                                                                          int actions,
                                                                          DragGestureListener dgl)

      Creates a new `DragGestureRecognizer` that implements the default abstract subclass of `DragGestureRecognizer` for this `DragSource`, and sets the specified `Component` and `DragGestureListener` on the newly created object. For this `DragSource` the default is `MouseDragGestureRecognizer`.

      Parameters:
        `c` - the `Component` target for the recognizer
        `actions` - the permitted source actions
        `dgl` - the `DragGestureListener` to notify

      Returns:
        the new `DragGestureRecognizer` or `null` if the `Toolkit.createDragGestureRecognizer` method has no implementation available for the requested `DragGestureRecognizer` subclass and returns `null`

    - #### addDragSourceListener

          public void addDragSourceListener(DragSourceListener dsl)

      Adds the specified `DragSourceListener` to this `DragSource` to receive drag source events during drag operations intiated with this `DragSource`. If a `null` listener is specified, no action is taken and no exception is thrown.
      Parameters:
        `dsl` - the `DragSourceListener` to add
      Since:
        1.4
      See Also:
        `removeDragSourceListener(java.awt.dnd.DragSourceListener)`, `getDragSourceListeners()`

    - #### removeDragSourceListener

          public void removeDragSourceListener(DragSourceListener dsl)

      Removes the specified `DragSourceListener` from this `DragSource`. If a `null` listener is specified, no action is taken and no exception is thrown. If the listener specified by the argument was not previously added to this `DragSource`, no action is taken and no exception is thrown.
      Parameters:
        `dsl` - the `DragSourceListener` to remove
      Since:
        1.4
      See Also:
        `addDragSourceListener(java.awt.dnd.DragSourceListener)`, `getDragSourceListeners()`

    - #### getDragSourceListeners

          public DragSourceListener[] getDragSourceListeners()

      Gets all the `DragSourceListener`s registered with this `DragSource`.
      Returns:
        all of this `DragSource`'s `DragSourceListener`s or an empty array if no such listeners are currently registered
      Since:
        1.4
      See Also:
        `addDragSourceListener(java.awt.dnd.DragSourceListener)`, `removeDragSourceListener(java.awt.dnd.DragSourceListener)`

    - #### addDragSourceMotionListener

          public void addDragSourceMotionListener(DragSourceMotionListener dsml)

      Adds the specified `DragSourceMotionListener` to this `DragSource` to receive drag motion events during drag operations intiated with this `DragSource`. If a `null` listener is specified, no action is taken and no exception is thrown.
      Parameters:
        `dsml` - the `DragSourceMotionListener` to add
      Since:
        1.4
      See Also:
        `removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)`, `getDragSourceMotionListeners()`

    - #### removeDragSourceMotionListener

          public void removeDragSourceMotionListener(DragSourceMotionListener dsml)

      Removes the specified `DragSourceMotionListener` from this `DragSource`. If a `null` listener is specified, no action is taken and no exception is thrown. If the listener specified by the argument was not previously added to this `DragSource`, no action is taken and no exception is thrown.
      Parameters:
        `dsml` - the `DragSourceMotionListener` to remove
      Since:
        1.4
      See Also:
        `addDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)`, `getDragSourceMotionListeners()`

    - #### getDragSourceMotionListeners

          public DragSourceMotionListener[] getDragSourceMotionListeners()

      Gets all of the `DragSourceMotionListener`s registered with this `DragSource`.
      Returns:
        all of this `DragSource`'s `DragSourceMotionListener`s or an empty array if no such listeners are currently registered
      Since:
        1.4
      See Also:
        `addDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)`, `removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)`

    - #### getListeners

          public <T extends EventListener> T[] getListeners(Class<T> listenerType)

      Gets all the objects currently registered as `FooListener`s upon this `DragSource`. `FooListener`s are registered using the `addFooListener` method.
      Parameters:
        `listenerType` - the type of listeners requested; this parameter should specify an interface that descends from `java.util.EventListener`
      Returns:
        an array of all objects registered as `FooListener`s on this `DragSource`, or an empty array if no such listeners have been added
      Throws:
        `ClassCastException` - if `listenerType` doesn't specify a class or interface that implements `java.util.EventListener`
      Since:
        1.4
      See Also:
        `getDragSourceListeners()`, `getDragSourceMotionListeners()`

    - #### getDragThreshold

          public static int getDragThreshold()

      Returns the drag gesture motion threshold. The drag gesture motion threshold defines the recommended behavior for `MouseDragGestureRecognizer`s.

      If the system property `awt.dnd.drag.threshold` is set to a positive integer, this method returns the value of the system property; otherwise if a pertinent desktop property is available and supported by the implementation of the Java platform, this method returns the value of that property; otherwise this method returns some default value. The pertinent desktop property can be queried using `java.awt.Toolkit.getDesktopProperty("DnD.gestureMotionThreshold")`.

      Returns:
        the drag gesture motion threshold
      Since:
        1.5
      See Also:
        `MouseDragGestureRecognizer`

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.