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 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 | Description |
---|---|
DragSource() |
Creates a new
DragSource . |
Modifier and Type | Method | Description |
---|---|---|
void |
addDragSourceListener(DragSourceListener dsl) |
Adds the specified
DragSourceListener to this
DragSource to receive drag source events during drag
operations initiated with this DragSource . |
void |
addDragSourceMotionListener(DragSourceMotionListener dsml) |
Adds the specified
DragSourceMotionListener to this
DragSource to receive drag motion events during drag
operations initiated 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(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
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(Class<T> listenerType) |
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(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,
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 . |
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 . |
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 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 typeactions
- the permitted source drag actionsc
- the Component
targetdgl
- 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 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()
DragSourceListener
s
registered with this DragSource
.DragSource
's
DragSourceListener
s 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 initiated 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()
DragSourceMotionListener
s
registered with this DragSource
.DragSource
's
DragSourceMotionListener
s 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)
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
getDragSourceListeners()
,
getDragSourceMotionListeners()
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")
.
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, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-internal+0-adhoc.mlchung.jdk9-jdeps