Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.awt.dnd
Class DragSource

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

public class DragSource
extends Object

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

Field Summary
`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
`DragSource()` Construct a new `DragSource`.

Method Summary
`DragGestureRecognizer` | `createDefaultDragGestureRecognizer(Component c, int actions, DragGestureListener dgl)` Creates a new `DragSourceRecognizer` that implements the default abstract subclass of `DragGestureRecognizer` for this `DragSource`, and sets the specified `Component` and `DragGestureListener` on the newly created object.
`DragGestureRecognizer` | `createDragGestureRecognizer(Class 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)` Create the `DragSourceContext` to handle this drag.
`static DragSource` | `getDefaultDragSource()` This method returns the `DragSource` object associated with the underlying platform.
`FlavorMap` | `getFlavorMap()` This method returns the `FlavorMap` for this `DragSource`.
`static boolean` | `isDragImageSupported()` This method returns a `boolean` indicating whether or not drag `Image` support is available on the underlying platform.
`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.

### DefaultMoveDrop

    public static final Cursor DefaultMoveDrop

  The default `Cursor` to use with a move operation indicating that a drop is currently allowed.

### DefaultLinkDrop

    public static final Cursor DefaultLinkDrop

  The default `Cursor` to use with a link operation indicating that a drop is currently allowed.

### DefaultCopyNoDrop

    public static final Cursor DefaultCopyNoDrop

  The default `Cursor` to use with a copy operation indicating that a drop is currently not allowed.

### DefaultMoveNoDrop

    public static final Cursor DefaultMoveNoDrop

  The default `Cursor` to use with a move operation indicating that a drop is currently not allowed.

### DefaultLinkNoDrop

    public static final Cursor DefaultLinkNoDrop

  The default `Cursor` to use with a link operation indicating that a drop is currently not allowed.

Constructor Detail

### DragSource

    public DragSource()

  Construct a new `DragSource`.

Method Detail

### getDefaultDragSource

    public static DragSource getDefaultDragSource()

  This method returns the `DragSource` object associated with the underlying platform.

  Returns:
    the platform DragSource

### isDragImageSupported

    public static boolean isDragImageSupported()

  This method returns a `boolean` indicating 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` or `null` for defaults
    `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:
    ``java.awt.dnd.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` or `null` for defaults
    `transferable` - The subject data of the drag
    `dsl` - The `DragSourceListener`
    `flavorMap` - The `FlavorMap to use or `null`

    `
  Throws:
    ``java.awt.dnd.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` or `null` for defaults
    `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`

  Throws:
    ``java.awt.dnd.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` or `null` for defaults
    `transferable` - The subject data of the drag
    `dsl` - The `DragSourceListener`

  Throws:
    ``java.awt.dnd.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)

  Create the `DragSourceContext` to handle this drag. To incorporate a new `DragSourceContext` subclass, subclass `DragSource` and override this method.

  Parameters:
    `dscp` - The `DragSourceContextPeer` for this drag
    `trigger` - The `DragGestureEvent` that triggered the drag
    `dragCursor` - The initial `Cursor` to display
    `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`

  Returns:
    the `DragSourceContext`

### getFlavorMap

    public FlavorMap getFlavorMap()

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

  Returns:
    the `FlavorMap` for this `DragSource`

### createDragGestureRecognizer

    public DragGestureRecognizer createDragGestureRecognizer(Class 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 `DragSourceRecognizer` 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`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2001 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.