The Drag and Drop API

Contents
Swinging Duke

For more information about the drag-and-drop mechanism described in this API, see the PostScript document titled "Proposal for a Drag and Drop Subsystem for the Java Foundation Classes."

In JDK 1.I 1, the Abstract Windowing Toolkit (AWT) introduced the use of a Uniform Data Transfer Mechanism to implement clipboard and drag-and-drop facilities. This API defines the drag-and-drop mechanism for the beta version of Swing.

This API is based on an earlier work that was undertaken in 1996 to specify a uniform data-transfer mechanism using clipboard and drag-and-drop facilities for AWT. But this API incorporates significant differences from that previous work as a result of the JavaBeans event model, lightweight components, and an increasing understanding of cross-platform integration issues.

Goals

The primary requirements that this API addresses are:

Provision of a platform-independent drag-and-drop facility for Java GUI clients implemented through AWT and JFC classes.
Integration with platform-dependent drag-and-drop facilities, permitting Java clients to be able to perform drag-and-drop operations with native applications using:
- OLE (Win32) drag-and-drop
- CDE/Motif dynamic protocol
- MacOS
- JavaOS
To leverage the existing java.awt.datatransfer package (a June 2, 1997 proposal for a drag-and-drop subsystem for JFC) to enable the transfer of data, described by an extensible data type system based on the MIME standard.
Support for the use of accessibility features whenever possible.

Features of the Drag and Drop API

This section presents the main features of this preliminary drag-and-drop API.

Overview

Drag and drop is a direct manipulation gesture found in many graphical user interface systems. It provides a mechanism for transferring information between entities associated with a presentation element in the GUI. Normally driven by the physical gesturing of a human user, drag and drop provides sensory feedback to the user during navigation over the presentation elements in the GUI, originating from the source of the drag and usually terminating in a drop over a target between which any subsequent data transfer occurs.

A typical drag-and-drop operation can be summed up in the following operations (which are not necessarily strictly sequential):

A drag source (an object of the DragSource class) comes into existence, associated with some presentation element in the GUI, and some potentially transferable data.
One or more drop targets come into or go out of existence, associated with presentation elements in the GUI that are potentially capable of consuming transferable data.
A human user gestures to initiate a drag-and-drop operation on a presentation element in the GUI associated with a drag source. (Note: Although the body of this document 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 drag-and-drop operation, given the appropriate implementation of a drag source.)
As user gestures navigate over presentation elements in GUI-associated drop target(s), the drag source receives notifications in order to provide "drag under" feedback effects. The gesture itself moves a logical cursor across the GUI hierarchy, intersecting the geometry of GUI components, possible resulting in the logical "drag" cursor entering, crossing, and subsequently leaving associated drop targets.
The drag source object manifests "drag under" feedback to the user, in the typical case by animating the GUI cursor associated with the logical cursor. Drop target objects manifest "drag under" feedback to the user, typically by rendering animations into their associated GUI components under the GUI cursor.
The determination of the feedback effects, and the ultimate success or failure of the data transfer, should one occur, is parametrized as follows:
- By the transfer operation: Copy or Move.
- By the intersection of the set of data types provided by the drag source and the set of data types that are comprehensible by the drop target.
- When the user terminates the drag operation, normally resulting in a successful drop, both the drag source and the drop target receive notifications that include, and result in the transfer of, the information associated with the drag source.

The Drag Source

The drag source is the entity responsible for the coordination of the drag-and-drop operation for the initiating client. The definition of the DragSource class is presented in a PostScript file titled "Proposal for a Drag and Drop Subsystem for the Java Foundation Classes."