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 DragSource comes into existence, associated with some presentation element (Component) in the GUI, to initiate a Drag and Drop of some potentially Transferable data.

• 1 or more DropTarget(s) come into/go out of existence, associated with presentation elements in the GUI (Components), potentially capable of consuming Transferable data types.

• A DragGestureRecognizer is obtained from the DragSource and is associated with a Component in order to track and identify any Drag initiating gesture by the user over the Component.

• A user makes a Drag gesture over the Component, which the registered DragGestureRecognizer detects, and notifies its DragGestureListener of.

  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 class MouseDragGestureRecognizer for recognizing mouse device gestures. Other abstract subclasses may be provided by the platform to support other input devices or particular Component class semantics.

• The DragGestureListener causes the DragSource to initiate the Drag and Drop operation on behalf of the user, perhaps animating the GUI Cursor and/or rendering an Image of the item(s) that are the subject of the operation.

• As the user gestures navigate over Component(s) in the GUI with associated DropTarget(s), the DragSource receives notifications in order to provide "Drag Over" feedback effects, and the DropTarget(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 DragSource and DropTarget: Copy, Move or Reference(link).

• By the intersection of the set of data types provided by the DragSource and the set of data types comprehensible by the DropTarget.

• When the user terminates the drag operation, normally resulting in a successful Drop, both the DragSource and DropTarget receive notifications that include, and result in the type negotiation and transfer of, the information associated with the DragSource via a Transferable object.

In such situations it is desirable that the GUI control detect this and institute a scroll operation in order to make obscured region(s) visible to the user.

The appropriate DragGestureRecognizer subclass instance is obtained from the DragSource asssociated with a particular Component, or from the Toolkit object via its java.awt.Toolkit.createDragGestureRecognizer createDragGestureRecognizer() method.

Once the DragGestureRecognizer is associated with a particular Component it will register the appropriate listener interfaces on that Component in order to track the input events delivered to the Component.

Once the DragGestureRecognizer identifies a sequence of events on the Component as a drag initiating gesture, it will notify its unicast DragGestureListener by invoking its java.awt.dnd.DragGestureListener.dragGestureRecognized gestureRecognized() method.

When a concrete DragGestureRecognizer instance detects a drag initiating gesture on the Component it is associated with, it fires a DragGestureEvent to the DragGestureListener registered on its unicast event source for DragGestureListener events.

• 1 default instance per JVM for the lifetime of that JVM.

DragSourceEvents are generated whenever the drag enters, moves over, or exits a drop site, when the drop action changes, and when the drag ends.

Each DropTarget is associated with a FlavorMap. The default FlavorMap hereafter designates the FlavorMap returned by SystemFlavorMap.getDefaultFlavorMap().

The DropTargetDragEvent reports the source drop actions and the user drop action that reflect the current state of the drag operation.

Source drop actions is a bitwise mask of DnDConstants that represents the set of drop actions supported by the drag source for this drag operation.

User drop action depends on the drop actions supported by the drag source and the drop action selected by the user.

Mouse drag gesture recognizers should honor the drag gesture motion threshold, available through DragSource.getDragThreshold . A drag gesture should be recognized only when the distance in either the horizontal or vertical direction between the location of the latest mouse dragged event and the location of the corresponding mouse button pressed event is greater than the drag gesture motion threshold.

Drag gesture recognizers created with DragSource.createDefaultDragGestureRecognizer follow this convention.
author:
   Laurence P.