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

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 ()
Creates a new DragSource.

Method Summary

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 (DragSourceContextPeer dscp, DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable t, DragSourceListener dsl) Creates the DragSourceContext to handle this drag.
static DragSource	getDefaultDragSource () Gets the DragSource object associated with the underlying platform.
DragSourceListener []	getDragSourceListeners () Gets all the DragSourceListeners registered with this DragSource.
DragSourceMotionListener []	getDragSourceMotionListeners () Gets all of the DragSourceMotionListeners 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 FooListeners 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 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

InvalidDnDOperationException

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

InvalidDnDOperationException

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

dragOffset - the offset of the Image origin from the hotspot of the