Class DragSource
- java.lang.Object
-
- java.awt.dnd.DragSource
- All Implemented Interfaces:
Serializable
public class DragSource extends Object implements Serializable
The 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 aComponent
instance 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:
- Serialized Form
Field Summary
Modifier and Type | Field | Description |
---|---|---|
static Cursor | DefaultCopyDrop | The default |
static Cursor | DefaultCopyNoDrop | The default |
static Cursor | DefaultLinkDrop | The default |
static Cursor | DefaultLinkNoDrop | The default |
static Cursor | DefaultMoveDrop | The default |
static Cursor | DefaultMoveNoDrop | The default |
Constructor Summary
Constructor | Description |
---|---|
DragSource() | Creates a new |
Method Summary
Modifier and Type | Method | Description |
---|---|---|
void | addDragSourceListener(DragSourceListener dsl) | Adds the specified |
void | addDragSourceMotionListener(DragSourceMotionListener dsml) | Adds the specified |
DragGestureRecognizer | createDefaultDragGestureRecognizer(Component c,
int actions,
DragGestureListener dgl) | Creates a new |
<T extends DragGestureRecognizer> | createDragGestureRecognizer(Class<T> recognizerAbstractClass,
Component c,
int actions,
DragGestureListener dgl) | Creates a new |
protected DragSourceContext | createDragSourceContext(DragGestureEvent dgl,
Cursor dragCursor,
Image dragImage,
Point imageOffset,
Transferable t,
DragSourceListener dsl) | Creates the |
static DragSource | getDefaultDragSource() | Gets the |
DragSourceListener[] | getDragSourceListeners() | Gets all the |
DragSourceMotionListener[] | getDragSourceMotionListeners() | Gets all of the |
static int | getDragThreshold() | Returns the drag gesture motion threshold. |
FlavorMap | getFlavorMap() | This method returns the |
<T extends EventListener> | getListeners(Class<T> listenerType) | Gets all the objects currently registered as |
static boolean | isDragImageSupported() | Reports whether or not drag |
void | removeDragSourceListener(DragSourceListener dsl) | Removes the specified |
void | removeDragSourceMotionListener(DragSourceMotionListener dsml) | Removes the specified |
void | startDrag(DragGestureEvent trigger,
Cursor dragCursor,
Transferable transferable,
DragSourceListener dsl) | Start a drag, given the |
void | startDrag(DragGestureEvent trigger,
Cursor dragCursor,
Transferable transferable,
DragSourceListener dsl,
FlavorMap flavorMap) | Start a drag, given the |
void | startDrag(DragGestureEvent trigger,
Cursor dragCursor,
Image dragImage,
Point dragOffset,
Transferable transferable,
DragSourceListener dsl) | Start a drag, given the |
void | startDrag(DragGestureEvent trigger,
Cursor dragCursor,
Image dragImage,
Point imageOffset,
Transferable transferable,
DragSourceListener dsl,
FlavorMap flavorMap) | Start a drag, given the |
Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Field Detail
DefaultCopyDrop
public static final Cursor DefaultCopyDrop
The default Cursor
to use with a copy operation indicating that a drop is currently allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.
- See Also:
GraphicsEnvironment.isHeadless()
DefaultMoveDrop
public static final Cursor DefaultMoveDrop
The default Cursor
to use with a move operation indicating that a drop is currently allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.
- See Also:
GraphicsEnvironment.isHeadless()
DefaultLinkDrop
public static final Cursor DefaultLinkDrop
The default Cursor
to use with a link operation indicating that a drop is currently allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.
- See Also:
GraphicsEnvironment.isHeadless()
DefaultCopyNoDrop
public static final Cursor DefaultCopyNoDrop
The default Cursor
to use with a copy operation indicating that a drop is currently not allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.
- See Also:
GraphicsEnvironment.isHeadless()
DefaultMoveNoDrop
public static final Cursor DefaultMoveNoDrop
The default Cursor
to use with a move operation indicating that a drop is currently not allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.
- See Also:
GraphicsEnvironment.isHeadless()
DefaultLinkNoDrop
public static final Cursor DefaultLinkNoDrop
The default Cursor
to use with a link operation indicating that a drop is currently not allowed. null
if GraphicsEnvironment.isHeadless()
returns true
.
- See Also:
GraphicsEnvironment.isHeadless()
Constructor Detail
DragSource
public DragSource() throws HeadlessException
Creates a new DragSource
.
- Throws:
-
HeadlessException
- if GraphicsEnvironment.isHeadless() returns true - See Also:
GraphicsEnvironment.isHeadless()
Method Detail
getDefaultDragSource
public static DragSource getDefaultDragSource()
Gets the DragSource
object associated with the underlying platform.
- Returns:
- the platform DragSource
- Throws:
-
HeadlessException
- if GraphicsEnvironment.isHeadless() returns true - See Also:
GraphicsEnvironment.isHeadless()
isDragImageSupported
public static boolean isDragImageSupported()
Reports whether or not drag Image
support is available on the underlying platform.
- Returns:
- if the Drag Image support is available on this platform
startDrag
public void startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap) throws 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
.
- Parameters:
-
trigger
- theDragGestureEvent
that initiated the drag -
dragCursor
- the initialCursor
for this drag operation ornull
for the default cursor handling; see DragSourceContext for more details on the cursor handling mechanism during drag and drop -
dragImage
- the image to drag ornull
-
imageOffset
- the offset of theImage
origin from the hotspot of theCursor
at the instant of the trigger -
transferable
- the subject data of the drag -
dsl
- theDragSourceListener
-
flavorMap
- theFlavorMap
to 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 the DragGestureEvent
that initiated the drag, the initial Cursor
to use, the Transferable
subject data of the drag, the DragSourceListener
, and the FlavorMap
.
- Parameters:
-
trigger
- theDragGestureEvent
that initiated the drag -
dragCursor
- the initialCursor
for this drag operation ornull
for the default cursor handling; see DragSourceContext for more details on the cursor handling mechanism during drag and drop -
transferable
- the subject data of the drag -
dsl
- theDragSourceListener
-
flavorMap
- theFlavorMap
to 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 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
.
- Parameters:
-
trigger
- theDragGestureEvent
that initiated the drag -
dragCursor
- the initialCursor
for this drag operation ornull
for the default cursor handling; see DragSourceContext for more details on the cursor handling mechanism during drag and drop -
dragImage
- theImage
to drag ornull
-
dragOffset
- the offset of theImage
origin from the hotspot of theCursor
at the instant of the trigger -
transferable
- the subject data of the drag -
dsl
- 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 the DragGestureEvent
that initiated the drag, the initial Cursor
to use, the Transferable
subject data of the drag, and the DragSourceListener
.
- Parameters:
-
trigger
- theDragGestureEvent
that initiated the drag -
dragCursor
- the initialCursor
for this drag operation ornull
for the default cursor handling; see DragSourceContext class for more details on the cursor handling mechanism during drag and drop -
transferable
- the subject data of the drag -
dsl
- 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 the 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.
- Parameters:
-
dgl
- TheDragGestureEvent
that triggered the drag -
dragCursor
- The initialCursor
for this drag operation ornull
for the default cursor handling; see DragSourceContext class for more details on the cursor handling mechanism during drag and drop -
dragImage
- TheImage
to drag ornull
-
imageOffset
- The offset of theImage
origin from the hotspot of the cursor at the instant of the trigger -
t
- The subject data of the drag -
dsl
- TheDragSourceListener
- Returns:
- the
DragSourceContext
- Throws:
-
NullPointerException
- ifdscp
isnull
-
NullPointerException
- ifdgl
isnull
-
NullPointerException
- ifdragImage
is notnull
andimageOffset
isnull
-
NullPointerException
- ift
isnull
-
IllegalArgumentException
- if theComponent
associated with the trigger event isnull
. -
IllegalArgumentException
- if theDragSource
for the trigger event isnull
. -
IllegalArgumentException
- if the drag action for the trigger event isDnDConstants.ACTION_NONE
. -
IllegalArgumentException
- if the source actions for theDragGestureRecognizer
associated with the trigger event are equal toDnDConstants.ACTION_NONE
.
getFlavorMap
public FlavorMap getFlavorMap()
This method returns the FlavorMap
for this DragSource
.
- Returns:
- the
FlavorMap
for thisDragSource
createDragGestureRecognizer
public <T extends DragGestureRecognizer> T 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.
- Type Parameters:
-
T
- the type ofDragGestureRecognizer
to create - Parameters:
-
recognizerAbstractClass
- the requested abstract type -
actions
- the permitted source drag actions -
c
- theComponent
target -
dgl
- theDragGestureListener
to notify - Returns:
- the new
DragGestureRecognizer
ornull
if theToolkit.createDragGestureRecognizer
method has no implementation available for the requestedDragGestureRecognizer
subclass and returnsnull
createDefaultDragGestureRecognizer
public 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. For this DragSource
the default is MouseDragGestureRecognizer
.
- Parameters:
-
c
- theComponent
target for the recognizer -
actions
- the permitted source actions -
dgl
- theDragGestureListener
to notify - Returns:
- the new
DragGestureRecognizer
ornull
if theToolkit.createDragGestureRecognizer
method has no implementation available for the requestedDragGestureRecognizer
subclass and returnsnull
addDragSourceListener
public void addDragSourceListener(DragSourceListener dsl)
Adds the specified 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.
- Parameters:
-
dsl
- theDragSourceListener
to add - Since:
- 1.4
- See Also:
-
removeDragSourceListener(java.awt.dnd.DragSourceListener)
,getDragSourceListeners()
removeDragSourceListener
public void removeDragSourceListener(DragSourceListener dsl)
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.
- Parameters:
-
dsl
- theDragSourceListener
to remove - Since:
- 1.4
- See Also:
-
addDragSourceListener(java.awt.dnd.DragSourceListener)
,getDragSourceListeners()
getDragSourceListeners
public DragSourceListener[] getDragSourceListeners()
Gets all the DragSourceListener
s registered with this DragSource
.
- Returns:
- all of this
DragSource
'sDragSourceListener
s or an empty array if no such listeners are currently registered - Since:
- 1.4
- See Also:
-
addDragSourceListener(java.awt.dnd.DragSourceListener)
,removeDragSourceListener(java.awt.dnd.DragSourceListener)
addDragSourceMotionListener
public void addDragSourceMotionListener(DragSourceMotionListener dsml)
Adds the specified 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.
- Parameters:
-
dsml
- theDragSourceMotionListener
to add - Since:
- 1.4
- See Also:
-
removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)
,getDragSourceMotionListeners()
removeDragSourceMotionListener
public void removeDragSourceMotionListener(DragSourceMotionListener dsml)
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.
- Parameters:
-
dsml
- theDragSourceMotionListener
to remove - Since:
- 1.4
- See Also:
-
addDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)
,getDragSourceMotionListeners()
getDragSourceMotionListeners
public DragSourceMotionListener[] getDragSourceMotionListeners()
Gets all of the DragSourceMotionListener
s registered with this DragSource
.
- Returns:
- all of this
DragSource
'sDragSourceMotionListener
s or an empty array if no such listeners are currently registered - Since:
- 1.4
- See Also:
-
addDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)
,removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)
getListeners
public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Gets all the objects currently registered as FooListener
s upon this DragSource
. FooListener
s are registered using the addFooListener
method.
- 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
FooListener
s on thisDragSource
, or an empty array if no such listeners have been added - Throws:
-
ClassCastException
- iflistenerType
doesn't specify a class or interface that implementsjava.util.EventListener
- Since:
- 1.4
- See Also:
-
getDragSourceListeners()
,getDragSourceMotionListeners()
getDragThreshold
public static int getDragThreshold()
Returns 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")
.
- Returns:
- the drag gesture motion threshold
- Since:
- 1.5
- See Also:
MouseDragGestureRecognizer