Class DragSource
- All Implemented Interfaces:
Serializable
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 aComponentinstance in the GUI. [implementation dependent] - Some other arbitrary association. [implementation dependent]
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final CursorThe defaultCursorto use with a copy operation indicating that a drop is currently allowed.static final CursorThe defaultCursorto use with a copy operation indicating that a drop is currently not allowed.static final CursorThe defaultCursorto use with a link operation indicating that a drop is currently allowed.static final CursorThe defaultCursorto use with a link operation indicating that a drop is currently not allowed.static final CursorThe defaultCursorto use with a move operation indicating that a drop is currently allowed.static final CursorThe defaultCursorto use with a move operation indicating that a drop is currently not allowed. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoidAdds the specifiedDragSourceListenerto thisDragSourceto receive drag source events during drag operations initiated with thisDragSource.voidAdds the specifiedDragSourceMotionListenerto thisDragSourceto receive drag motion events during drag operations initiated with thisDragSource.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.<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 DragSourceGets theDragSourceobject associated with the underlying platform.Gets all theDragSourceListeners registered with thisDragSource.Gets all of theDragSourceMotionListeners registered with thisDragSource.static intReturns the drag gesture motion threshold.This method returns theFlavorMapfor thisDragSource.<T extends EventListener>
T[]getListeners(Class<T> listenerType) Gets all the objects currently registered asFooListeners upon thisDragSource.static booleanReports whether or not dragImagesupport is available on the underlying platform.voidRemoves the specifiedDragSourceListenerfrom thisDragSource.voidRemoves 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 Details
-
DefaultCopyDrop
The defaultCursorto use with a copy operation indicating that a drop is currently allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
-
DefaultMoveDrop
The defaultCursorto use with a move operation indicating that a drop is currently allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
-
DefaultLinkDrop
The defaultCursorto use with a link operation indicating that a drop is currently allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
-
DefaultCopyNoDrop
The defaultCursorto use with a copy operation indicating that a drop is currently not allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
-
DefaultMoveNoDrop
The defaultCursorto use with a move operation indicating that a drop is currently not allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
-
DefaultLinkNoDrop
The defaultCursorto use with a link operation indicating that a drop is currently not allowed.nullifGraphicsEnvironment.isHeadless()returnstrue.- See Also:
-
-
Constructor Details
-
DragSource
Creates a newDragSource.- Throws:
HeadlessException- if GraphicsEnvironment.isHeadless() returns true- See Also:
-
-
Method Details
-
getDefaultDragSource
Gets theDragSourceobject associated with the underlying platform.- Returns:
- the platform DragSource
- Throws:
HeadlessException- if GraphicsEnvironment.isHeadless() returns true- See Also:
-
isDragImageSupported
public static boolean isDragImageSupported()Reports whether or not dragImagesupport is available on the underlying platform.- Returns:
trueif the Drag Image support is available on this platform, otherwisefalse
-
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
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 typec- theComponenttargetactions- the permitted source drag actionsdgl- 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
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
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:
-
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:
-
addDragSourceMotionListener
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
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:
-
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:
-
getListeners
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:
-
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:
-