java.lang.Object | |
↳ | java.awt.dnd.DragSource |
The 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
.
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
DefaultCopyDrop | The default Cursor to use with a copy operation indicating
that a drop is currently allowed. |
||||||||||
DefaultCopyNoDrop | The default Cursor to use with a copy operation indicating
that a drop is currently not allowed. |
||||||||||
DefaultLinkDrop | The default Cursor to use with a link operation indicating
that a drop is currently allowed. |
||||||||||
DefaultLinkNoDrop | The default Cursor to use with a link operation indicating
that a drop is currently not allowed. |
||||||||||
DefaultMoveDrop | The default Cursor to use with a move operation indicating
that a drop is currently allowed. |
||||||||||
DefaultMoveNoDrop | The default Cursor to use with a move operation indicating
that a drop is currently not allowed. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Creates a new
DragSource . |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Adds the specified
DragSourceListener to this
DragSource to receive drag source events during drag
operations intiated with this DragSource . | |||||||||||
Adds the specified
DragSourceMotionListener to this
DragSource to receive drag motion events during drag
operations intiated with this DragSource . | |||||||||||
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. | |||||||||||
Creates a new
DragGestureRecognizer
that implements the specified
abstract subclass of
DragGestureRecognizer , and
sets the specified Component
and DragGestureListener on
the newly created object. | |||||||||||
Gets the
DragSource object associated with
the underlying platform. | |||||||||||
Gets all the
DragSourceListener s
registered with this DragSource . | |||||||||||
Gets all of the
DragSourceMotionListener s
registered with this DragSource . | |||||||||||
Returns the drag gesture motion threshold.
| |||||||||||
This method returns the
FlavorMap for this DragSource . | |||||||||||
Gets all the objects currently registered as
FooListener s upon this DragSource . | |||||||||||
Reports
whether or not drag
Image support
is available on the underlying platform. | |||||||||||
Removes the specified
DragSourceListener from this
DragSource . | |||||||||||
Removes the specified
DragSourceMotionListener from this
DragSource . | |||||||||||
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 . | |||||||||||
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 . | |||||||||||
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 . | |||||||||||
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 . |
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Creates the
DragSourceContext to handle this drag. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
The default Cursor
to use with a copy operation indicating
that a drop is currently allowed. null
if
GraphicsEnvironment.isHeadless()
returns true
.
The default Cursor
to use with a copy operation indicating
that a drop is currently not allowed. null
if
GraphicsEnvironment.isHeadless()
returns true
.
The default Cursor
to use with a link operation indicating
that a drop is currently allowed. null
if
GraphicsEnvironment.isHeadless()
returns true
.
The default Cursor
to use with a link operation indicating
that a drop is currently not allowed. null
if
GraphicsEnvironment.isHeadless()
returns true
.
The default Cursor
to use with a move operation indicating
that a drop is currently allowed. null
if
GraphicsEnvironment.isHeadless()
returns true
.
The default Cursor
to use with a move operation indicating
that a drop is currently not allowed. null
if
GraphicsEnvironment.isHeadless()
returns true
.
Creates a new DragSource
.
HeadlessException | if GraphicsEnvironment.isHeadless() returns true |
---|
Adds the specified 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 add |
---|
Adds the specified 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 add |
---|
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.
For this DragSource
the default is MouseDragGestureRecognizer
.
c | the Component target for the recognizer |
---|---|
actions | the permitted source actions |
dgl | the DragGestureListener to notify
|
DragGestureRecognizer
or null
if the Toolkit.createDragGestureRecognizer
method
has no implementation available for
the requested DragGestureRecognizer
subclass and returns null
Creates a new 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 type |
---|---|
c | the Component target |
actions | the permitted source drag actions |
dgl | the DragGestureListener to notify
|
DragGestureRecognizer
or null
if the Toolkit.createDragGestureRecognizer
method
has no implementation available for
the requested DragGestureRecognizer
subclass and returns null
Gets the DragSource
object associated with
the underlying platform.
HeadlessException | if GraphicsEnvironment.isHeadless() returns true |
---|
Gets all the DragSourceListener
s
registered with this DragSource
.
DragSource
's
DragSourceListener
s or an empty array if no
such listeners are currently registeredGets all of the DragSourceMotionListener
s
registered with this DragSource
.
DragSource
's
DragSourceMotionListener
s or an empty array if no
such listeners are currently registeredReturns the drag gesture motion threshold. The drag gesture motion threshold
defines the recommended behavior for 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")
.
This method returns the
FlavorMap
for this DragSource
.
FlavorMap
for this DragSource
Gets all the objects currently registered as
FooListener
s upon this DragSource
.
FooListener
s are registered using the
addFooListener
method.
listenerType | 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 addedif listenerType
doesn't specify a class or interface that implements
java.util.EventListener |
Reports
whether or not drag
Image
support
is available on the underlying platform.
Removes the specified 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 remove |
---|
Removes the specified 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 remove |
---|
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
.
trigger | the DragGestureEvent that initiated the drag |
---|---|
dragCursor | the initial Cursor or null for defaults |
transferable | the subject data of the drag |
dsl | the DragSourceListener
|
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 | |
InvalidDnDOperationException |
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
.
trigger | the DragGestureEvent that
initiated the drag |
---|---|
dragCursor | the initial Cursor or
null for defaults |
transferable | the subject data of the drag |
dsl | the DragSourceListener |
flavorMap | the FlavorMap to use or null
|
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 | |
InvalidDnDOperationException |
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
.
trigger | the DragGestureEvent that initiated the drag |
---|---|
dragCursor | the initial Cursor or null for defaults |
dragImage | the Image to drag or null |
dragOffset | the offset of the Image origin from the hotspot
of the Cursor at the instant of the trigger |
transferable | the subject data of the drag |
dsl | the DragSourceListener
|
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 | |
InvalidDnDOperationException |
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
.
trigger | the DragGestureEvent that initiated the drag |
---|---|
dragCursor | the initial Cursor or null for defaults |
dragImage | the image to drag or null, |
imageOffset | the offset of the Image origin from the hotspot
of the Cursor at the instant of the trigger |
transferable | the subject data of the drag |
dsl | the DragSourceListener |
flavorMap | the FlavorMap to use, or null
|
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 | |
InvalidDnDOperationException |
Creates the DragSourceContext
to handle this drag.
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.
If dragCursor
is null
, the default drag
cursors are used for this drag operation.
NullPointerException
is not thrown.
dscp | The DragSourceContextPeer for this drag |
---|---|
dgl | The DragGestureEvent that triggered the
drag |
dragCursor | The initial Cursor to display |
dragImage | The Image to drag or null |
imageOffset | The offset of the Image origin from the
hotspot of the cursor at the instant of the trigger |
t | The subject data of the drag |
dsl | 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 .
|