| <!-- |
| Copyright (c) 1998, 1999, Oracle and/or its affiliates. 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. Oracle designates this |
| particular file as subject to the "Classpath" exception as provided |
| by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| or visit www.oracle.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> |