| java.lang.Object
 java.awt.dnd.DragSource
| DragSource | | public class DragSource implements Serializable(Code) | | 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 a Component
instance in the GUI. [implementation dependent]
- Some other arbitrary association. [implementation dependent]
Once the 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.
version:
1.53, 05/05/07
since:
1.2 |
| Field Summary | |
| final public static Cursor | DefaultCopyDrop
The default Cursor to use with a copy operation indicating
that a drop is currently allowed. | | final public static Cursor | DefaultCopyNoDrop
The default Cursor to use with a copy operation indicating
that a drop is currently not allowed. | | final public static Cursor | DefaultLinkDrop
The default Cursor to use with a link operation indicating
that a drop is currently allowed. | | final public static Cursor | DefaultLinkNoDrop
The default Cursor to use with a link operation indicating
that a drop is currently not allowed. | | final public static Cursor | DefaultMoveDrop
The default Cursor to use with a move operation indicating
that a drop is currently allowed. | | final public static Cursor | DefaultMoveNoDrop
The default Cursor to use with a move operation indicating
that a drop is currently not allowed. | | final static String | dragSourceListenerK
Internal constants for serialization. | | final static String | dragSourceMotionListenerK
|
| Constructor Summary | |
| public | DragSource()
Creates a new DragSource. |
| Method Summary | |
| public void | addDragSourceListener(DragSourceListener dsl)
Adds the specified DragSourceListener to this
DragSource to receive drag source events during drag
operations intiated with this DragSource. | | public void | addDragSourceMotionListener(DragSourceMotionListener dsml)
Adds the specified DragSourceMotionListener to this
DragSource to receive drag motion events during drag
operations intiated with this DragSource. | | 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. | | public 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. | | protected DragSourceContext | createDragSourceContext(DragSourceContextPeer dscp, 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:
dscp - The DragSourceContextPeer for this drag
Parameters:
dgl - The DragGestureEvent that triggered the drag
Parameters:
dragCursor - The initial Cursor for this drag operationor null for the default cursor handling;see DragSourceContext classfor more details on the cursor handling mechanism during drag and drop
Parameters:
dragImage - The Image to drag or null
Parameters:
imageOffset - The offset of the Image origin from the hotspot of the cursor at the instant of the trigger
Parameters:
t - The subject data of the drag
Parameters:
dsl - The DragSourceListener the DragSourceContext
throws:
NullPointerException - if dscp is null
throws:
NullPointerException - if dgl is null
throws:
NullPointerException - if dragImage is not null and imageOffset is null
throws:
NullPointerException - if t is null
throws:
IllegalArgumentException - if the Component associated with the trigger event is null.
throws:
IllegalArgumentException - if the DragSource for the trigger event is null.
throws:
IllegalArgumentException - if the drag action for thetrigger event is DnDConstants.ACTION_NONE.
throws:
IllegalArgumentException - if the source actions for theDragGestureRecognizer associated with the triggerevent are equal to DnDConstants.ACTION_NONE. | | public static DragSource | getDefaultDragSource()
Gets the DragSource object associated with
the underlying platform. | | public DragSourceListener[] | getDragSourceListeners()
Gets all the DragSourceListeners
registered with this DragSource. | | public DragSourceMotionListener[] | getDragSourceMotionListeners()
Gets all of the DragSourceMotionListeners
registered with this DragSource. | | public static int | getDragThreshold()
Returns the drag gesture motion threshold. | | public FlavorMap | getFlavorMap()
This method returns the
FlavorMap for this DragSource. | | public T[] | getListeners(Class<T> listenerType)
Gets all the objects currently registered as
FooListeners upon this DragSource. | | public static boolean | isDragImageSupported()
Reports
whether or not drag
Image support
is available on the underlying platform. | | void | processDragDropEnd(DragSourceDropEvent dsde)
This method calls dragDropEnd on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceDropEvent. | | void | processDragEnter(DragSourceDragEvent dsde)
This method calls dragEnter on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceDragEvent. | | void | processDragExit(DragSourceEvent dse)
This method calls dragExit on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceEvent. | | void | processDragMouseMoved(DragSourceDragEvent dsde)
This method calls dragMouseMoved on the
DragSourceMotionListeners registered with this
DragSource, and passes them the specified
DragSourceDragEvent. | | void | processDragOver(DragSourceDragEvent dsde)
This method calls dragOver on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceDragEvent. | | void | processDropActionChanged(DragSourceDragEvent dsde)
This method calls dropActionChanged on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceDragEvent. | | public void | removeDragSourceListener(DragSourceListener dsl)
Removes the specified DragSourceListener from this
DragSource. | | public void | removeDragSourceMotionListener(DragSourceMotionListener dsml)
Removes the specified DragSourceMotionListener from this
DragSource. | | public 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 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 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. | | public 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. |
| DefaultCopyDrop | | final public static Cursor DefaultCopyDrop(Code) | | The default Cursor to use with a copy operation indicating
that a drop is currently allowed. null if
GraphicsEnvironment.isHeadless() returns true.
See Also: java.awt.GraphicsEnvironment.isHeadless |
| DefaultCopyNoDrop | | final public static Cursor DefaultCopyNoDrop(Code) | | 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: java.awt.GraphicsEnvironment.isHeadless |
| DefaultLinkDrop | | final public static Cursor DefaultLinkDrop(Code) | | The default Cursor to use with a link operation indicating
that a drop is currently allowed. null if
GraphicsEnvironment.isHeadless() returns true.
See Also: java.awt.GraphicsEnvironment.isHeadless |
| DefaultLinkNoDrop | | final public static Cursor DefaultLinkNoDrop(Code) | | 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: java.awt.GraphicsEnvironment.isHeadless |
| DefaultMoveDrop | | final public static Cursor DefaultMoveDrop(Code) | | The default Cursor to use with a move operation indicating
that a drop is currently allowed. null if
GraphicsEnvironment.isHeadless() returns true.
See Also: java.awt.GraphicsEnvironment.isHeadless |
| DefaultMoveNoDrop | | final public static Cursor DefaultMoveNoDrop(Code) | | 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: java.awt.GraphicsEnvironment.isHeadless |
| dragSourceListenerK | | final static String dragSourceListenerK(Code) | | Internal constants for serialization.
|
| dragSourceMotionListenerK | | final static String dragSourceMotionListenerK(Code) | | |
| createDefaultDragGestureRecognizer | | public DragGestureRecognizer createDefaultDragGestureRecognizer(Component c, int actions, DragGestureListener dgl)(Code) | | 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 - the Component target for the recognizer
Parameters:
actions - the permitted source actions
Parameters:
dgl - the DragGestureListener to notify the new DragGestureRecognizer or nullif the Toolkit.createDragGestureRecognizer methodhas no implementation available for the requested DragGestureRecognizersubclass and returns null |
| createDragGestureRecognizer | | public T createDragGestureRecognizer(Class<T> recognizerAbstractClass, Component c, int actions, DragGestureListener dgl)(Code) | | Creates a new DragGestureRecognizer
that implements the specified
abstract subclass of
DragGestureRecognizer, and
sets the specified Component
and DragGestureListener on
the newly created object.
Parameters:
recognizerAbstractClass - the requested abstract type
Parameters:
actions - the permitted source drag actions
Parameters:
c - the Component target
Parameters:
dgl - the DragGestureListener to notify the new DragGestureRecognizer or nullif the Toolkit.createDragGestureRecognizer methodhas no implementation available for the requested DragGestureRecognizersubclass and returns null |
| createDragSourceContext | | protected DragSourceContext createDragSourceContext(DragSourceContextPeer dscp, DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable t, DragSourceListener dsl)(Code) | | 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:
dscp - The DragSourceContextPeer for this drag
Parameters:
dgl - The DragGestureEvent that triggered the drag
Parameters:
dragCursor - The initial Cursor for this drag operationor null for the default cursor handling;see DragSourceContext classfor more details on the cursor handling mechanism during drag and drop
Parameters:
dragImage - The Image to drag or null
Parameters:
imageOffset - The offset of the Image origin from the hotspot of the cursor at the instant of the trigger
Parameters:
t - The subject data of the drag
Parameters:
dsl - The DragSourceListener the DragSourceContext
throws:
NullPointerException - if dscp is null
throws:
NullPointerException - if dgl is null
throws:
NullPointerException - if dragImage is not null and imageOffset is null
throws:
NullPointerException - if t is null
throws:
IllegalArgumentException - if the Component associated with the trigger event is null.
throws:
IllegalArgumentException - if the DragSource for the trigger event is null.
throws:
IllegalArgumentException - if the drag action for thetrigger event is DnDConstants.ACTION_NONE.
throws:
IllegalArgumentException - if the source actions for theDragGestureRecognizer associated with the triggerevent are equal to DnDConstants.ACTION_NONE. |
| getDragThreshold | | public static int getDragThreshold()(Code) | | 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").
the drag gesture motion threshold
See Also: MouseDragGestureRecognizer
since:
1.5 |
| getFlavorMap | | public FlavorMap getFlavorMap()(Code) | | This method returns the
FlavorMap for this DragSource.
the FlavorMap for this DragSource |
| getListeners | | public T[] getListeners(Class<T> listenerType)(Code) | | Gets all the objects currently registered as
FooListeners upon this DragSource.
FooListeners are registered using the
addFooListener method.
Parameters:
listenerType - the type of listeners requested; this parametershould specify an interface that descends fromjava.util.EventListener an array of all objects registered asFooListeners on thisDragSource, or an empty array if no such listenershave been added ClassCastException if listenerTypedoesn't specify a class or interface that implementsjava.util.EventListener
See Also: DragSource.getDragSourceListeners
See Also: DragSource.getDragSourceMotionListeners
since:
1.4 |
| isDragImageSupported | | public static boolean isDragImageSupported()(Code) | | Reports
whether or not drag
Image support
is available on the underlying platform.
if the Drag Image support is available on this platform |
| processDragDropEnd | | void processDragDropEnd(DragSourceDropEvent dsde)(Code) | | This method calls dragDropEnd on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceDropEvent.
Parameters:
dsde - the DragSourceEvent |
| processDragEnter | | void processDragEnter(DragSourceDragEvent dsde)(Code) | | This method calls dragEnter on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceDragEvent.
Parameters:
dsde - the DragSourceDragEvent |
| processDragExit | | void processDragExit(DragSourceEvent dse)(Code) | | This method calls dragExit on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceEvent.
Parameters:
dse - the DragSourceEvent |
| processDragMouseMoved | | void processDragMouseMoved(DragSourceDragEvent dsde)(Code) | | This method calls dragMouseMoved on the
DragSourceMotionListeners registered with this
DragSource, and passes them the specified
DragSourceDragEvent.
Parameters:
dsde - the DragSourceEvent |
| processDragOver | | void processDragOver(DragSourceDragEvent dsde)(Code) | | This method calls dragOver on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceDragEvent.
Parameters:
dsde - the DragSourceDragEvent |
| processDropActionChanged | | void processDropActionChanged(DragSourceDragEvent dsde)(Code) | | This method calls dropActionChanged on the
DragSourceListeners registered with this
DragSource, and passes them the specified
DragSourceDragEvent.
Parameters:
dsde - the DragSourceDragEvent |
| removeDragSourceListener | | public void removeDragSourceListener(DragSourceListener dsl)(Code) | | 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 - the DragSourceListener to remove
See Also: DragSource.addDragSourceListener
See Also: DragSource.getDragSourceListeners
since:
1.4 |
| removeDragSourceMotionListener | | public void removeDragSourceMotionListener(DragSourceMotionListener dsml)(Code) | | 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 - the DragSourceMotionListener to remove
See Also: DragSource.addDragSourceMotionListener
See Also: DragSource.getDragSourceMotionListeners
since:
1.4 |
| startDrag | | public void startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap) throws InvalidDnDOperationException(Code) | | 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 - the DragGestureEvent that initiated the drag
Parameters:
dragCursor - the initial Cursor for this drag operationor null for the default cursor handling;see DragSourceContextfor more details on the cursor handling mechanism during drag and drop
Parameters:
dragImage - the image to drag or null
Parameters:
imageOffset - the offset of the Image origin from the hotspotof the Cursor at the instant of the trigger
Parameters:
transferable - the subject data of the drag
Parameters:
dsl - the DragSourceListener
Parameters:
flavorMap - the FlavorMap to use, or null
throws:
java.awt.dnd.InvalidDnDOperationException - if the Drag and Dropsystem is unable to initiate a drag operation, or if the userattempts 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(Code) | | 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 - the DragGestureEvent that initiated the drag
Parameters:
dragCursor - the initial Cursor for this drag operationor null for the default cursor handling;see DragSourceContextfor more details on the cursor handling mechanism during drag and drop
Parameters:
transferable - the subject data of the drag
Parameters:
dsl - the DragSourceListener
Parameters:
flavorMap - the FlavorMap to use or null
throws:
java.awt.dnd.InvalidDnDOperationException - if the Drag and Dropsystem is unable to initiate a drag operation, or if the userattempts 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(Code) | | 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 - the DragGestureEvent that initiated the drag
Parameters:
dragCursor - the initial Cursor for this drag operationor null for the default cursor handling;see DragSourceContextfor more details on the cursor handling mechanism during drag and drop
Parameters:
dragImage - the Image to drag or null
Parameters:
dragOffset - the offset of the Image origin from the hotspotof the Cursor at the instant of the trigger
Parameters:
transferable - the subject data of the drag
Parameters:
dsl - the DragSourceListener
throws:
java.awt.dnd.InvalidDnDOperationException - if the Drag and Dropsystem is unable to initiate a drag operation, or if the userattempts 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(Code) | | 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 - the DragGestureEvent that initiated the drag
Parameters:
dragCursor - the initial Cursor for this drag operationor null for the default cursor handling;see DragSourceContext classfor more details on the cursor handling mechanism during drag and drop
Parameters:
transferable - the subject data of the drag
Parameters:
dsl - the DragSourceListener
throws:
java.awt.dnd.InvalidDnDOperationException - if the Drag and Dropsystem is unable to initiate a drag operation, or if the userattempts to start a drag while an existing drag operation is still executing
|
|
|