Module java.desktop
Package java.awt.dnd

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 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.

Since:
1.2
See Also: