<!--
 Copyright 1998-1999 Sun Microsystems, Inc.  All Rights Reserved.
 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 This code is free software; you can redistribute it and/or modify it
 under the terms of the GNU General Public License version 2 only, as
 published by the Free Software Foundation.  Sun designates this
 particular file as subject to the "Classpath" exception as provided
 by Sun in the LICENSE file that accompanied this code.

 This code is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 version 2 for more details (a copy is included in the LICENSE file that
 accompanied this code).

 You should have received a copy of the GNU General Public License version
 2 along with this work; if not, write to the Free Software Foundation,
 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 CA 95054 USA or visit www.sun.com if you need additional information or
 have any questions.
-->

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<body bgcolor="white">

Drag and Drop is a direct manipulation gesture found in many Graphical
User Interface systems that provides a mechanism to transfer
information between two entities logically associated with presentation
elements in the GUI. Normally driven by a physical gesture of a
human user using an appropriate input device, Drag and Drop provides both
a mechanism to enable continuous feedback regarding the
possible outcome of any subsequent data transfer to the user during
navigation over the presentation elements in the GUI, and the facilities
to provide for any subsequent data negotiation and transfer. 
<P>
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. 
<P>
A typical Drag and Drop operation can be decomposed into the following
states (not entirely sequentially): 
<UL>
<LI>A <code>DragSource</code> comes into existence, 
associated with some presentation
element (<code>Component</code>) in the GUI, to initiate a Drag and Drop of
some potentially <code>Transferable</code> data. 
<P>
<LI>1 or more <code>DropTarget</code>(s) come into/go out of 
existence, associated
with presentation elements in the GUI (Components), potentially
capable of consuming <code>Transferable</code> data types. 
<P>
<LI> A <code>DragGestureRecognizer</code> is 
obtained from the <code>DragSource</code> and is
associated with a <code>Component</code> in order 
to track and identify any Drag
initiating gesture by the user over the <code>Component</code>. 
<P>
<LI> A user makes a Drag gesture over the <code>Component</code>, 
which the registered
<code>DragGestureRecognizer</code> detects, and notifies its
<code>DragGestureListener</code> of. 
<P>
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 <code>DragSource</code>. This package
contains the abstract class <code>MouseDragGestureRecognizer</code> for
recognizing mouse device gestures. Other abstract subclasses may be
provided by the platform to support other input devices or
particular <code>Component</code> class semantics. 
    <P>
<LI> The <code>DragGestureListener</code> causes the 
<code>DragSource</code> to initiate the Drag
and Drop operation on behalf of the user, perhaps animating the
GUI Cursor and/or rendering an <code>Image</code> of the item(s) that are the
subject of the operation.
<P>
<LI> As the user gestures navigate over <code>Component</code>(s) 
in the GUI with
associated <code>DropTarget</code>(s), the <code>DragSource</code> 
receives notifications in order
to provide "Drag Over" feedback effects, and the <code>DropTarget</code>(s)
receive notifications in order to provide "Drag Under" feedback effects
based upon the operation(s) supported and the data type(s) involved. 
</UL>
<P>

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 <code>Component</code>(s) and associated <code>DropTarget</code>(s). 
<P>
The <code>DragSource</code> object manifests "Drag Over" feedback to the user, in the typical case by animating the GUI <code>Cursor</code> associated with the
logical cursor. 
<P>
<code>DropTarget</code> objects manifest "Drag Under" feedback to the user, in
the typical case, by rendering animations into their associated GUI
<code>Component</code>(s) under the GUI Cursor. 
<P>
The determination of the feedback effects, and the ultimate success
or failure of the data transfer, should one occur, is parameterized
as follows: 
<UL>
<LI> By the transfer "operation" selected by the user, and supported by
both the <code>DragSource</code> and <code>DropTarget</code>: Copy, Move or Reference(link). 
<P>
<LI> By the intersection of the set of data types provided by the
<code>DragSource</code> and the set of data types comprehensible by the 
<code>DropTarget</code>. 
<P>
<LI>When the user terminates the drag operation, normally resulting in a
successful Drop, both the <code>DragSource</code> and <code>DropTarget</code>
receive
notifications that include, and result in the type negotiation and
transfer of, the information associated with the <code>DragSource</code> via a
<code>Transferable</code> object. 
</UL>

<!--
<h2>Package Specification</h2>

##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
  <li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>

<h2>Related Documentation</h2>

For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
  <li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->

@since 1.2
</body>
</html>