Package java.awt.dnd
This package defines the classes and interfaces necessary to perform Drag and Drop operations in Java. It defines classes for the drag-source and the drop-target, as well as events for transferring the data being dragged. This package also provides a means for giving visual feedback to the user throughout the duration of the Drag and Drop operation.
A typical Drag and Drop operation can be decomposed into the following states (not entirely sequentially):
- A
DragSourcecomes into existence, associated with some presentation element (Component) in the GUI, to initiate a Drag and Drop of some potentiallyTransferabledata. - 1 or more
DropTarget(s) come into/go out of existence, associated with presentation elements in the GUI (Components), potentially capable of consumingTransferabledata types. - A
DragGestureRecognizeris obtained from theDragSourceand is associated with aComponentin order to track and identify any Drag initiating gesture by the user over theComponent. - A user makes a Drag gesture over the
Component, which the registeredDragGestureRecognizerdetects, and notifies itsDragGestureListenerof.Note: Although this API consistently refers to the stimulus for a drag and drop operation being a physical gesture by a human user, this does not preclude a programmatically driven DnD operation given the appropriate implementation of a
DragSource. This package contains the abstract classMouseDragGestureRecognizerfor recognizing mouse device gestures. Other abstract subclasses may be provided by the platform to support other input devices or particularComponentclass semantics. - The
DragGestureListenercauses theDragSourceto initiate the Drag and Drop operation on behalf of the user, perhaps animating the GUI Cursor and/or rendering anImageof the item(s) that are the subject of the operation. - As the user gestures navigate over
Component(s) in the GUI with associatedDropTarget(s), theDragSourcereceives notifications in order to provide "Drag Over" feedback effects, and theDropTarget(s) receive notifications in order to provide "Drag Under" feedback effects based upon the operation(s) supported and the data type(s) involved.
The gesture itself moves a logical cursor across the GUI hierarchy,
intersecting the geometry of GUI Component(s), possibly resulting in the
logical "Drag" cursor entering, crossing, and subsequently leaving
Component(s) and associated DropTarget(s).
The DragSource object manifests "Drag Over" feedback to the user, in
the typical case by animating the GUI Cursor associated with the
logical cursor.
DropTarget objects manifest "Drag Under" feedback to the user, in the
typical case, by rendering animations into their associated GUI
Component(s) under the GUI Cursor.
The determination of the feedback effects, and the ultimate success or failure of the data transfer, should one occur, is parameterized as follows:
- By the transfer "operation" selected by the user, and supported by
both the
DragSourceandDropTarget: Copy, Move or Reference(link). - By the intersection of the set of data types provided by the
DragSourceand the set of data types comprehensible by theDropTarget. - When the user terminates the drag operation, normally resulting in a
successful Drop, both the
DragSourceandDropTargetreceive notifications that include, and result in the type negotiation and transfer of, the information associated with theDragSourcevia aTransferableobject.
- Since:
- 1.2
-
Interface Summary Interface Description Autoscroll During DnD operations it is possible that a user may wish to drop the subject of the operation on a region of a scrollable GUI control that is not currently visible to the user.DragGestureListener The listener interface for receiving drag gesture events.DragSourceListener TheDragSourceListenerdefines the event interface for originators of Drag and Drop operations to track the state of the user's gesture, and to provide appropriate "drag over" feedback to the user throughout the Drag and Drop operation.DragSourceMotionListener A listener interface for receiving mouse motion events during a drag operation.DropTargetListener TheDropTargetListenerinterface is the callback interface used by theDropTargetclass to provide notification of DnD operations that involve the subjectDropTarget. -
Class Summary Class Description DnDConstants This class contains constant values representing the type of action(s) to be performed by a Drag and Drop operation.DragGestureEvent ADragGestureEventis passed toDragGestureListener's dragGestureRecognized() method when a particularDragGestureRecognizerdetects that a platform dependent drag initiating gesture has occurred on theComponentthat it is tracking.DragGestureRecognizer TheDragGestureRecognizeris an abstract base class for the specification of a platform-dependent listener that can be associated with a particularComponentin order to identify platform-dependent drag initiating gestures.DragSource TheDragSourceis 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.DragSourceAdapter An abstract adapter class for receiving drag source events.DragSourceContext TheDragSourceContextclass is responsible for managing the initiator side of the Drag and Drop protocol.DragSourceDragEvent TheDragSourceDragEventis delivered from theDragSourceContextPeer, via theDragSourceContext, to theDragSourceListenerregistered with thatDragSourceContextand with its associatedDragSource.DragSourceDropEvent TheDragSourceDropEventis delivered from theDragSourceContextPeer, via theDragSourceContext, to thedragDropEndmethod ofDragSourceListeners registered with thatDragSourceContextand with its associatedDragSource.DragSourceEvent This class is the base class forDragSourceDragEventandDragSourceDropEvent.DropTarget TheDropTargetis associated with aComponentwhen thatComponentwishes to accept drops during Drag and Drop operations.DropTarget.DropTargetAutoScroller this protected nested class implements autoscrollingDropTargetAdapter An abstract adapter class for receiving drop target events.DropTargetContext ADropTargetContextis created whenever the logical cursor associated with a Drag and Drop operation coincides with the visible geometry of aComponentassociated with aDropTarget.DropTargetDragEvent TheDropTargetDragEventis delivered to aDropTargetListenervia its dragEnter() and dragOver() methods.DropTargetDropEvent TheDropTargetDropEventis delivered via theDropTargetListenerdrop() method.DropTargetEvent TheDropTargetEventis the base class for both theDropTargetDragEventand theDropTargetDropEvent.MouseDragGestureRecognizer This abstract subclass ofDragGestureRecognizerdefines aDragGestureRecognizerfor mouse-based gestures. -
Exception Summary Exception Description InvalidDnDOperationException This exception is thrown by various methods in the java.awt.dnd package.