Serializable
public class DragSource extends Object implements Serializable
DragSource
is the entity responsible for the initiation of the Drag and Drop operation, and may be used in a number of scenarios: Component
, or application specific object associated with a Component
instance in the GUI. [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
.
Modifier and Type | Field | Description |
---|---|---|
static final Cursor |
DefaultCopyDrop |
The default Cursor to use with a copy operation indicating that a drop is currently allowed. |
static final Cursor |
DefaultCopyNoDrop |
The default Cursor to use with a copy operation indicating that a drop is currently not allowed. |
static final Cursor |
DefaultLinkDrop |
The default Cursor to use with a link operation indicating that a drop is currently allowed. |
static final Cursor |
DefaultLinkNoDrop |
The default Cursor to use with a link operation indicating that a drop is currently not allowed. |
static final Cursor |
DefaultMoveDrop |
The default Cursor to use with a move operation indicating that a drop is currently allowed. |
static final Cursor |
DefaultMoveNoDrop |
The default Cursor to use with a move operation indicating that a drop is currently not allowed. |
Constructor | Description |
---|---|
DragSource() |
Creates a new DragSource . |
Modifier and Type | Method | Description |
---|---|---|
void |
addDragSourceListener |
Adds the specified DragSourceListener to this DragSource to receive drag source events during drag operations initiated with this DragSource . |
void |
addDragSourceMotionListener |
Adds the specified DragSourceMotionListener to this DragSource to receive drag motion events during drag operations initiated with this DragSource . |
DragGestureRecognizer |
createDefaultDragGestureRecognizer |
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> |
createDragGestureRecognizer |
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 |
Creates the DragSourceContext to handle the current drag operation. |
static DragSource |
getDefaultDragSource() |
Gets the DragSource object associated with the underlying platform. |
DragSourceListener[] |
getDragSourceListeners() |
Gets all the DragSourceListener s registered with this DragSource . |
DragSourceMotionListener[] |
getDragSourceMotionListeners() |
Gets all of the DragSourceMotionListener s 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> |
getListeners |
Gets all the objects currently registered as FooListener s upon this DragSource . |
static boolean |
isDragImageSupported() |
Reports whether or not drag Image support is available on the underlying platform. |
void |
removeDragSourceListener |
Removes the specified DragSourceListener from this DragSource . |
void |
removeDragSourceMotionListener |
Removes the specified DragSourceMotionListener from this DragSource . |
void |
startDrag |
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 |
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 . |
void |
startDrag |
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 |
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 . |
public static final Cursor DefaultCopyDrop
Cursor
to use with a copy operation indicating that a drop is currently allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.public static final Cursor DefaultMoveDrop
Cursor
to use with a move operation indicating that a drop is currently allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.public static final Cursor DefaultLinkDrop
Cursor
to use with a link operation indicating that a drop is currently allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.public static final Cursor DefaultCopyNoDrop
Cursor
to use with a copy operation indicating that a drop is currently not allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.public static final Cursor DefaultMoveNoDrop
Cursor
to use with a move operation indicating that a drop is currently not allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.public static final Cursor DefaultLinkNoDrop
Cursor
to use with a link operation indicating that a drop is currently not allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.public DragSource() throws HeadlessException
DragSource
.HeadlessException
- if GraphicsEnvironment.isHeadless() returns truepublic static DragSource getDefaultDragSource()
DragSource
object associated with the underlying platform.HeadlessException
- if GraphicsEnvironment.isHeadless() returns truepublic static boolean isDragImageSupported()
Image
support is available on the underlying platform.public void startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap) throws InvalidDnDOperationException
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
.trigger
- the DragGestureEvent
that initiated the dragdragCursor
- 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 dropdragImage
- the image to drag or null
imageOffset
- the offset of the Image
origin from the hotspot of the Cursor
at the instant of the triggertransferable
- the subject data of the dragdsl
- the DragSourceListener
flavorMap
- the FlavorMap
to use, or null
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 executingpublic void startDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap) throws InvalidDnDOperationException
DragGestureEvent
that initiated the drag, the initial Cursor
to use, the Transferable
subject data of the drag, the DragSourceListener
, and the FlavorMap
.trigger
- the DragGestureEvent
that initiated the dragdragCursor
- 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 droptransferable
- the subject data of the dragdsl
- the DragSourceListener
flavorMap
- the FlavorMap
to use or null
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 executingpublic void startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point dragOffset, Transferable transferable, DragSourceListener dsl) throws InvalidDnDOperationException
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
.trigger
- the DragGestureEvent
that initiated the dragdragCursor
- 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 dropdragImage
- the Image
to drag or null
dragOffset
- the offset of the Image
origin from the hotspot of the Cursor
at the instant of the triggertransferable
- the subject data of the dragdsl
- the DragSourceListener
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 executingpublic void startDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl) throws InvalidDnDOperationException
DragGestureEvent
that initiated the drag, the initial Cursor
to use, the Transferable
subject data of the drag, and the DragSourceListener
.trigger
- the DragGestureEvent
that initiated the dragdragCursor
- 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 droptransferable
- the subject data of the dragdsl
- the DragSourceListener
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 executingprotected DragSourceContext createDragSourceContext(DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable t, DragSourceListener dsl)
DragSourceContext
to handle the current drag operation. To incorporate a new DragSourceContext
subclass, subclass DragSource
and override this method.
If dragImage
is null
, no image is used to represent the drag over feedback for this drag operation, but NullPointerException
is not thrown.
If dsl
is null
, no drag source listener is registered with the created DragSourceContext
, but NullPointerException
is not thrown.
dgl
- The DragGestureEvent
that triggered the dragdragCursor
- 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 dropdragImage
- The Image
to drag or null
imageOffset
- The offset of the Image
origin from the hotspot of the cursor at the instant of the triggert
- The subject data of the dragdsl
- The DragSourceListener
DragSourceContext
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
.public FlavorMap getFlavorMap()
FlavorMap
for this DragSource
.FlavorMap
for this DragSource
public <T extends DragGestureRecognizer> T createDragGestureRecognizer(Class<T> recognizerAbstractClass, Component c, int actions, DragGestureListener dgl)
DragGestureRecognizer
that implements the specified abstract subclass of DragGestureRecognizer
, and sets the specified Component
and DragGestureListener
on the newly created object.T
- the type of DragGestureRecognizer
to createrecognizerAbstractClass
- the requested abstract typec
- the Component
targetactions
- the permitted source drag actionsdgl
- the DragGestureListener
to notifyDragGestureRecognizer
or null
if the Toolkit.createDragGestureRecognizer
method has no implementation available for the requested DragGestureRecognizer
subclass and returns null
public DragGestureRecognizer createDefaultDragGestureRecognizer(Component c, int actions, DragGestureListener dgl)
DragGestureRecognizer
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
.c
- the Component
target for the recognizeractions
- the permitted source actionsdgl
- the DragGestureListener
to notifyDragGestureRecognizer
or null
if the Toolkit.createDragGestureRecognizer
method has no implementation available for the requested DragGestureRecognizer
subclass and returns null
public void addDragSourceListener(DragSourceListener dsl)
DragSourceListener
to this DragSource
to receive drag source events during drag operations initiated with this DragSource
. If a null
listener is specified, no action is taken and no exception is thrown.dsl
- the DragSourceListener
to addpublic void removeDragSourceListener(DragSourceListener dsl)
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.dsl
- the DragSourceListener
to removepublic DragSourceListener[] getDragSourceListeners()
DragSourceListener
s registered with this DragSource
.DragSource
's DragSourceListener
s or an empty array if no such listeners are currently registeredpublic void addDragSourceMotionListener(DragSourceMotionListener dsml)
DragSourceMotionListener
to this DragSource
to receive drag motion events during drag operations initiated with this DragSource
. If a null
listener is specified, no action is taken and no exception is thrown.dsml
- the DragSourceMotionListener
to addpublic void removeDragSourceMotionListener(DragSourceMotionListener dsml)
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.dsml
- the DragSourceMotionListener
to removepublic DragSourceMotionListener[] getDragSourceMotionListeners()
DragSourceMotionListener
s registered with this DragSource
.DragSource
's DragSourceMotionListener
s or an empty array if no such listeners are currently registeredpublic <T extends EventListener> T[] getListeners(Class<T> listenerType)
FooListener
s upon this DragSource
. FooListener
s are registered using the addFooListener
method.T
- the type of listener objectslistenerType
- the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
FooListener
s on this DragSource
, or an empty array if no such listeners have been addedClassCastException
- if listenerType
doesn't specify a class or interface that implements java.util.EventListener
public static int getDragThreshold()
MouseDragGestureRecognizer
s. If the system property awt.dnd.drag.threshold
is 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 using java.awt.Toolkit.getDesktopProperty("DnD.gestureMotionThreshold")
.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/java/awt/dnd/DragSource.html