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 and Description |
|---|---|
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 and Description |
|---|
DragSource()
Creates a new
DragSource. |
| Modifier and Type | Method and Description |
|---|---|
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> |
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(java.awt.dnd.peer.DragSourceContextPeer dscp,
DragGestureEvent dgl,
Cursor dragCursor,
Image dragImage,
Point imageOffset,
Transferable t,
DragSourceListener dsl)
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
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> |
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. |
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.GraphicsEnvironment.isHeadless()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.GraphicsEnvironment.isHeadless()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.GraphicsEnvironment.isHeadless()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.GraphicsEnvironment.isHeadless()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.GraphicsEnvironment.isHeadless()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.GraphicsEnvironment.isHeadless()public DragSource()
throws HeadlessException
DragSource.HeadlessException - if GraphicsEnvironment.isHeadless()
returns trueGraphicsEnvironment.isHeadless()public static DragSource getDefaultDragSource()
DragSource object associated with
the underlying platform.HeadlessException - if GraphicsEnvironment.isHeadless()
returns trueGraphicsEnvironment.isHeadless()public 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 nullimageOffset - 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 DragSourceListenerflavorMap - 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 DragSourceListenerflavorMap - 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 nulldragOffset - 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(java.awt.dnd.peer.DragSourceContextPeer dscp, 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.
dscp - The DragSourceContextPeer for this dragdgl - 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 nullimageOffset - 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 DragSourceListenerDragSourceContextNullPointerException - if dscp is nullNullPointerException - if dgl is nullNullPointerException - if dragImage is not
null and imageOffset is nullNullPointerException - if t is nullIllegalArgumentException - 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 DragSourcepublic <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.
recognizerAbstractClass - the requested abstract typeactions - the permitted source drag actionsc - the Component targetdgl - the DragGestureListener to notify
DragGestureRecognizer or null
if the Toolkit.createDragGestureRecognizer method
has no implementation available for
the requested DragGestureRecognizer
subclass and returns nullpublic 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 notify
DragGestureRecognizer or null
if the Toolkit.createDragGestureRecognizer method
has no implementation available for
the requested DragGestureRecognizer
subclass and returns nullpublic void addDragSourceListener(DragSourceListener dsl)
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.dsl - the DragSourceListener to addremoveDragSourceListener(java.awt.dnd.DragSourceListener),
getDragSourceListeners()public 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 removeaddDragSourceListener(java.awt.dnd.DragSourceListener),
getDragSourceListeners()public DragSourceListener[] getDragSourceListeners()
DragSourceListeners
registered with this DragSource.DragSource's
DragSourceListeners or an empty array if no
such listeners are currently registeredaddDragSourceListener(java.awt.dnd.DragSourceListener),
removeDragSourceListener(java.awt.dnd.DragSourceListener)public void addDragSourceMotionListener(DragSourceMotionListener dsml)
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.dsml - the DragSourceMotionListener to addremoveDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener),
getDragSourceMotionListeners()public 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 removeaddDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener),
getDragSourceMotionListeners()public DragSourceMotionListener[] getDragSourceMotionListeners()
DragSourceMotionListeners
registered with this DragSource.DragSource's
DragSourceMotionListeners or an empty array if no
such listeners are currently registeredaddDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener),
removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)public <T extends EventListener> T[] getListeners(Class<T> listenerType)
FooListeners upon this DragSource.
FooListeners are registered using the
addFooListener method.listenerType - the type of listeners requested; this parameter
should specify an interface that descends from
java.util.EventListenerFooListeners 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.EventListenergetDragSourceListeners(),
getDragSourceMotionListeners()public static int getDragThreshold()
MouseDragGestureRecognizers.
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").
MouseDragGestureRecognizer Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2016, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.