Mercurial Mercurial > jdk-sandbox / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
jdk/src/share/classes/java/awt/dnd/package.html
changeset 2 90ce3da70b43
child 5506 202f599c92aa 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/awt/dnd/package.html	Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,145 @@
+<!--
+ 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>
jdk-sandbox