Class DragSource

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.

Fields

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()

Constructors

DragSource

public DragSource()
           throws HeadlessException

Creates a new DragSource.

Throws:

HeadlessException - if GraphicsEnvironment.isHeadless() returns true

See Also:

GraphicsEnvironment.isHeadless()

Methods

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()

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

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

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

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

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)

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()

Returns:

the FlavorMap for this DragSource

createDragGestureRecognizer

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

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)

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 DragSourceListeners registered with this DragSource.

Returns:

all of this DragSource's DragSourceListeners 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 DragSourceMotionListeners registered with this DragSource.

Returns:

all of this DragSource's DragSourceMotionListeners 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 FooListeners upon this DragSource. FooListeners 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 FooListeners 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

Since:

1.5

See Also:

MouseDragGestureRecognizer