- java.lang.Object
-
- java.awt.dnd.DragSource
-
- All Implemented Interfaces:
Serializable
public class DragSource extends Object implements Serializable
TheDragSourceis 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 aComponentinstance in the GUI. [implementation dependent] - Some other arbitrary association. [implementation dependent]
DragSourceis obtained, aDragGestureRecognizershould also be obtained to associate theDragSourcewith a particularComponent.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 aDragGestureRecognizer.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. ADragSourceshall only permit a single Drag and Drop operation to be current at any one time, and shall reject any further startDrag() requests by throwing anIllegalDnDOperationExceptionuntil such time as the extant operation is complete.The startDrag() method invokes the createDragSourceContext() method to instantiate an appropriate
DragSourceContextand associate theDragSourceContextPeerwith 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.InvalidDnDOperationExceptionto 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 Description static CursorDefaultCopyDropThe defaultCursorto use with a copy operation indicating that a drop is currently allowed.static CursorDefaultCopyNoDropThe defaultCursorto use with a copy operation indicating that a drop is currently not allowed.static CursorDefaultLinkDropThe defaultCursorto use with a link operation indicating that a drop is currently allowed.static CursorDefaultLinkNoDropThe defaultCursorto use with a link operation indicating that a drop is currently not allowed.static CursorDefaultMoveDropThe defaultCursorto use with a move operation indicating that a drop is currently allowed.static CursorDefaultMoveNoDropThe defaultCursorto use with a move operation indicating that a drop is currently not allowed.
-
Constructor Summary
Constructors Constructor Description DragSource()Creates a newDragSource.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description voidaddDragSourceListener(DragSourceListener dsl)Adds the specifiedDragSourceListenerto thisDragSourceto receive drag source events during drag operations initiated with thisDragSource.voidaddDragSourceMotionListener(DragSourceMotionListener dsml)Adds the specifiedDragSourceMotionListenerto thisDragSourceto receive drag motion events during drag operations initiated with thisDragSource.DragGestureRecognizercreateDefaultDragGestureRecognizer(Component c, int actions, DragGestureListener dgl)Creates a newDragGestureRecognizerthat implements the default abstract subclass ofDragGestureRecognizerfor thisDragSource, and sets the specifiedComponentandDragGestureListeneron the newly created object.<T extends DragGestureRecognizer>
TcreateDragGestureRecognizer(Class<T> recognizerAbstractClass, Component c, int actions, DragGestureListener dgl)Creates a newDragGestureRecognizerthat implements the specified abstract subclass ofDragGestureRecognizer, and sets the specifiedComponentandDragGestureListeneron the newly created object.protected DragSourceContextcreateDragSourceContext(DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable t, DragSourceListener dsl)Creates theDragSourceContextto handle the current drag operation.static DragSourcegetDefaultDragSource()Gets theDragSourceobject associated with the underlying platform.DragSourceListener[]getDragSourceListeners()Gets all theDragSourceListeners registered with thisDragSource.DragSourceMotionListener[]getDragSourceMotionListeners()Gets all of theDragSourceMotionListeners registered with thisDragSource.static intgetDragThreshold()Returns the drag gesture motion threshold.FlavorMapgetFlavorMap()This method returns theFlavorMapfor thisDragSource.<T extends EventListener>
T[]getListeners(Class<T> listenerType)Gets all the objects currently registered asFooListeners upon thisDragSource.static booleanisDragImageSupported()Reports whether or not dragImagesupport is available on the underlying platform.voidremoveDragSourceListener(DragSourceListener dsl)Removes the specifiedDragSourceListenerfrom thisDragSource.voidremoveDragSourceMotionListener(DragSourceMotionListener dsml)Removes the specifiedDragSourceMotionListenerfrom thisDragSource.voidstartDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl)Start a drag, given theDragGestureEventthat initiated the drag, the initialCursorto use, theTransferablesubject data of the drag, and theDragSourceListener.voidstartDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap)Start a drag, given theDragGestureEventthat initiated the drag, the initialCursorto use, theTransferablesubject data of the drag, theDragSourceListener, and theFlavorMap.voidstartDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point dragOffset, Transferable transferable, DragSourceListener dsl)Start a drag, given theDragGestureEventthat initiated the drag, the initialCursorto use, theImageto drag, the offset of theImageorigin from the hotspot of theCursorat the instant of the trigger, the subject data of the drag, and theDragSourceListener.voidstartDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap)Start a drag, given theDragGestureEventthat initiated the drag, the initialCursorto use, theImageto drag, the offset of theImageorigin from the hotspot of theCursorat the instant of the trigger, theTransferablesubject data of the drag, theDragSourceListener, and theFlavorMap.
-
-
-
Field Detail
-
DefaultCopyDrop
public static final Cursor DefaultCopyDrop
The defaultCursorto use with a copy operation indicating that a drop is currently allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
GraphicsEnvironment.isHeadless()
-
DefaultMoveDrop
public static final Cursor DefaultMoveDrop
The defaultCursorto use with a move operation indicating that a drop is currently allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
GraphicsEnvironment.isHeadless()
-
DefaultLinkDrop
public static final Cursor DefaultLinkDrop
The defaultCursorto use with a link operation indicating that a drop is currently allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
GraphicsEnvironment.isHeadless()
-
DefaultCopyNoDrop
public static final Cursor DefaultCopyNoDrop
The defaultCursorto use with a copy operation indicating that a drop is currently not allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
GraphicsEnvironment.isHeadless()
-
DefaultMoveNoDrop
public static final Cursor DefaultMoveNoDrop
The defaultCursorto use with a move operation indicating that a drop is currently not allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
GraphicsEnvironment.isHeadless()
-
DefaultLinkNoDrop
public static final Cursor DefaultLinkNoDrop
The defaultCursorto use with a link operation indicating that a drop is currently not allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
GraphicsEnvironment.isHeadless()
-
-
Constructor Detail
-
DragSource
public DragSource() throws HeadlessExceptionCreates a newDragSource.- Throws:
HeadlessException- if GraphicsEnvironment.isHeadless() returns true- See Also:
GraphicsEnvironment.isHeadless()
-
-
Method Detail
-
getDefaultDragSource
public static DragSource getDefaultDragSource()
Gets theDragSourceobject 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 dragImagesupport 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 theDragGestureEventthat initiated the drag, the initialCursorto use, theImageto drag, the offset of theImageorigin from the hotspot of theCursorat the instant of the trigger, theTransferablesubject data of the drag, theDragSourceListener, and theFlavorMap.- Parameters:
trigger- theDragGestureEventthat initiated the dragdragCursor- the initialCursorfor this drag operation ornullfor the default cursor handling; see DragSourceContext for more details on the cursor handling mechanism during drag and dropdragImage- the image to drag ornullimageOffset- the offset of theImageorigin from the hotspot of theCursorat the instant of the triggertransferable- the subject data of the dragdsl- theDragSourceListenerflavorMap- theFlavorMapto use, ornull- 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 theDragGestureEventthat initiated the drag, the initialCursorto use, theTransferablesubject data of the drag, theDragSourceListener, and theFlavorMap.- Parameters:
trigger- theDragGestureEventthat initiated the dragdragCursor- the initialCursorfor this drag operation ornullfor the default cursor handling; see DragSourceContext for more details on the cursor handling mechanism during drag and droptransferable- the subject data of the dragdsl- theDragSourceListenerflavorMap- theFlavorMapto use ornull- 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 theDragGestureEventthat initiated the drag, the initialCursorto use, theImageto drag, the offset of theImageorigin from the hotspot of theCursorat the instant of the trigger, the subject data of the drag, and theDragSourceListener.- Parameters:
trigger- theDragGestureEventthat initiated the dragdragCursor- the initialCursorfor this drag operation ornullfor the default cursor handling; see DragSourceContext for more details on the cursor handling mechanism during drag and dropdragImage- theImageto drag ornulldragOffset- the offset of theImageorigin from the hotspot of theCursorat the instant of the triggertransferable- the subject data of the dragdsl- theDragSourceListener- 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 theDragGestureEventthat initiated the drag, the initialCursorto use, theTransferablesubject data of the drag, and theDragSourceListener.- Parameters:
trigger- theDragGestureEventthat initiated the dragdragCursor- the initialCursorfor this drag operation ornullfor the default cursor handling; see DragSourceContext class for more details on the cursor handling mechanism during drag and droptransferable- the subject data of the dragdsl- theDragSourceListener- 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(DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable t, DragSourceListener dsl)
Creates theDragSourceContextto handle the current drag operation.To incorporate a new
DragSourceContextsubclass, subclassDragSourceand override this method.If
dragImageisnull, no image is used to represent the drag over feedback for this drag operation, butNullPointerExceptionis not thrown.If
dslisnull, no drag source listener is registered with the createdDragSourceContext, butNullPointerExceptionis not thrown.- Parameters:
dgl- TheDragGestureEventthat triggered the dragdragCursor- The initialCursorfor this drag operation ornullfor the default cursor handling; see DragSourceContext class for more details on the cursor handling mechanism during drag and dropdragImage- TheImageto drag ornullimageOffset- The offset of theImageorigin from the hotspot of the cursor at the instant of the triggert- The subject data of the dragdsl- TheDragSourceListener- Returns:
- the
DragSourceContext - Throws:
NullPointerException- ifdscpisnullNullPointerException- ifdglisnullNullPointerException- ifdragImageis notnullandimageOffsetisnullNullPointerException- iftisnullIllegalArgumentException- if theComponentassociated with the trigger event isnull.IllegalArgumentException- if theDragSourcefor the trigger event isnull.IllegalArgumentException- if the drag action for the trigger event isDnDConstants.ACTION_NONE.IllegalArgumentException- if the source actions for theDragGestureRecognizerassociated with the trigger event are equal toDnDConstants.ACTION_NONE.
-
getFlavorMap
public FlavorMap getFlavorMap()
This method returns theFlavorMapfor thisDragSource.- Returns:
- the
FlavorMapfor thisDragSource
-
createDragGestureRecognizer
public <T extends DragGestureRecognizer> T createDragGestureRecognizer(Class<T> recognizerAbstractClass, Component c, int actions, DragGestureListener dgl)
Creates a newDragGestureRecognizerthat implements the specified abstract subclass ofDragGestureRecognizer, and sets the specifiedComponentandDragGestureListeneron the newly created object.- Type Parameters:
T- the type ofDragGestureRecognizerto create- Parameters:
recognizerAbstractClass- the requested abstract typeactions- the permitted source drag actionsc- theComponenttargetdgl- theDragGestureListenerto notify- Returns:
- the new
DragGestureRecognizerornullif theToolkit.createDragGestureRecognizermethod has no implementation available for the requestedDragGestureRecognizersubclass and returnsnull
-
createDefaultDragGestureRecognizer
public DragGestureRecognizer createDefaultDragGestureRecognizer(Component c, int actions, DragGestureListener dgl)
Creates a newDragGestureRecognizerthat implements the default abstract subclass ofDragGestureRecognizerfor thisDragSource, and sets the specifiedComponentandDragGestureListeneron the newly created object. For thisDragSourcethe default isMouseDragGestureRecognizer.- Parameters:
c- theComponenttarget for the recognizeractions- the permitted source actionsdgl- theDragGestureListenerto notify- Returns:
- the new
DragGestureRecognizerornullif theToolkit.createDragGestureRecognizermethod has no implementation available for the requestedDragGestureRecognizersubclass and returnsnull
-
addDragSourceListener
public void addDragSourceListener(DragSourceListener dsl)
Adds the specifiedDragSourceListenerto thisDragSourceto receive drag source events during drag operations initiated with thisDragSource. If anulllistener is specified, no action is taken and no exception is thrown.- Parameters:
dsl- theDragSourceListenerto add- Since:
- 1.4
- See Also:
removeDragSourceListener(java.awt.dnd.DragSourceListener),getDragSourceListeners()
-
removeDragSourceListener
public void removeDragSourceListener(DragSourceListener dsl)
Removes the specifiedDragSourceListenerfrom thisDragSource. If anulllistener is specified, no action is taken and no exception is thrown. If the listener specified by the argument was not previously added to thisDragSource, no action is taken and no exception is thrown.- Parameters:
dsl- theDragSourceListenerto remove- Since:
- 1.4
- See Also:
addDragSourceListener(java.awt.dnd.DragSourceListener),getDragSourceListeners()
-
getDragSourceListeners
public DragSourceListener[] getDragSourceListeners()
Gets all theDragSourceListeners registered with thisDragSource.- Returns:
- all of this
DragSource'sDragSourceListeners 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 specifiedDragSourceMotionListenerto thisDragSourceto receive drag motion events during drag operations initiated with thisDragSource. If anulllistener is specified, no action is taken and no exception is thrown.- Parameters:
dsml- theDragSourceMotionListenerto add- Since:
- 1.4
- See Also:
removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener),getDragSourceMotionListeners()
-
removeDragSourceMotionListener
public void removeDragSourceMotionListener(DragSourceMotionListener dsml)
Removes the specifiedDragSourceMotionListenerfrom thisDragSource. If anulllistener is specified, no action is taken and no exception is thrown. If the listener specified by the argument was not previously added to thisDragSource, no action is taken and no exception is thrown.- Parameters:
dsml- theDragSourceMotionListenerto remove- Since:
- 1.4
- See Also:
addDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener),getDragSourceMotionListeners()
-
getDragSourceMotionListeners
public DragSourceMotionListener[] getDragSourceMotionListeners()
Gets all of theDragSourceMotionListeners registered with thisDragSource.- Returns:
- all of this
DragSource'sDragSourceMotionListeners 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 asFooListeners upon thisDragSource.FooListeners are registered using theaddFooListenermethod.- Type Parameters:
T- the type of listener objects- Parameters:
listenerType- the type of listeners requested; this parameter should specify an interface that descends fromjava.util.EventListener- Returns:
- an array of all objects registered as
FooListeners on thisDragSource, or an empty array if no such listeners have been added - Throws:
ClassCastException- iflistenerTypedoesn't specify a class or interface that implementsjava.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 forMouseDragGestureRecognizers.If the system property
awt.dnd.drag.thresholdis 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 usingjava.awt.Toolkit.getDesktopProperty("DnD.gestureMotionThreshold").- Returns:
- the drag gesture motion threshold
- Since:
- 1.5
- See Also:
MouseDragGestureRecognizer
-
-