2
|
1 |
<!--
|
|
2 |
Copyright 1998-1999 Sun Microsystems, Inc. All Rights Reserved.
|
|
3 |
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
4 |
|
|
5 |
This code is free software; you can redistribute it and/or modify it
|
|
6 |
under the terms of the GNU General Public License version 2 only, as
|
|
7 |
published by the Free Software Foundation. Sun designates this
|
|
8 |
particular file as subject to the "Classpath" exception as provided
|
|
9 |
by Sun in the LICENSE file that accompanied this code.
|
|
10 |
|
|
11 |
This code is distributed in the hope that it will be useful, but WITHOUT
|
|
12 |
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
13 |
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
14 |
version 2 for more details (a copy is included in the LICENSE file that
|
|
15 |
accompanied this code).
|
|
16 |
|
|
17 |
You should have received a copy of the GNU General Public License version
|
|
18 |
2 along with this work; if not, write to the Free Software Foundation,
|
|
19 |
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
20 |
|
|
21 |
Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
|
|
22 |
CA 95054 USA or visit www.sun.com if you need additional information or
|
|
23 |
have any questions.
|
|
24 |
-->
|
|
25 |
|
|
26 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
27 |
<html>
|
|
28 |
<body bgcolor="white">
|
|
29 |
|
|
30 |
Drag and Drop is a direct manipulation gesture found in many Graphical
|
|
31 |
User Interface systems that provides a mechanism to transfer
|
|
32 |
information between two entities logically associated with presentation
|
|
33 |
elements in the GUI. Normally driven by a physical gesture of a
|
|
34 |
human user using an appropriate input device, Drag and Drop provides both
|
|
35 |
a mechanism to enable continuous feedback regarding the
|
|
36 |
possible outcome of any subsequent data transfer to the user during
|
|
37 |
navigation over the presentation elements in the GUI, and the facilities
|
|
38 |
to provide for any subsequent data negotiation and transfer.
|
|
39 |
<P>
|
|
40 |
This package defines the classes and interfaces necessary to perform Drag
|
|
41 |
and Drop operations in Java. It
|
|
42 |
defines classes for the drag-source and the drop-target, as well as
|
|
43 |
events for transferring the data being dragged. This package also provides
|
|
44 |
a means for giving visual feedback to the user throughout the
|
|
45 |
duration of the Drag and Drop operation.
|
|
46 |
<P>
|
|
47 |
A typical Drag and Drop operation can be decomposed into the following
|
|
48 |
states (not entirely sequentially):
|
|
49 |
<UL>
|
|
50 |
<LI>A <code>DragSource</code> comes into existence,
|
|
51 |
associated with some presentation
|
|
52 |
element (<code>Component</code>) in the GUI, to initiate a Drag and Drop of
|
|
53 |
some potentially <code>Transferable</code> data.
|
|
54 |
<P>
|
|
55 |
<LI>1 or more <code>DropTarget</code>(s) come into/go out of
|
|
56 |
existence, associated
|
|
57 |
with presentation elements in the GUI (Components), potentially
|
|
58 |
capable of consuming <code>Transferable</code> data types.
|
|
59 |
<P>
|
|
60 |
<LI> A <code>DragGestureRecognizer</code> is
|
|
61 |
obtained from the <code>DragSource</code> and is
|
|
62 |
associated with a <code>Component</code> in order
|
|
63 |
to track and identify any Drag
|
|
64 |
initiating gesture by the user over the <code>Component</code>.
|
|
65 |
<P>
|
|
66 |
<LI> A user makes a Drag gesture over the <code>Component</code>,
|
|
67 |
which the registered
|
|
68 |
<code>DragGestureRecognizer</code> detects, and notifies its
|
|
69 |
<code>DragGestureListener</code> of.
|
|
70 |
<P>
|
|
71 |
Note: Although this API consistently refers to the stimulus for a
|
|
72 |
drag and drop operation being a physical gesture by a human user, this
|
|
73 |
does not preclude a programmatically driven DnD operation given the
|
|
74 |
appropriate implementation of a <code>DragSource</code>. This package
|
|
75 |
contains the abstract class <code>MouseDragGestureRecognizer</code> for
|
|
76 |
recognizing mouse device gestures. Other abstract subclasses may be
|
|
77 |
provided by the platform to support other input devices or
|
|
78 |
particular <code>Component</code> class semantics.
|
|
79 |
<P>
|
|
80 |
<LI> The <code>DragGestureListener</code> causes the
|
|
81 |
<code>DragSource</code> to initiate the Drag
|
|
82 |
and Drop operation on behalf of the user, perhaps animating the
|
|
83 |
GUI Cursor and/or rendering an <code>Image</code> of the item(s) that are the
|
|
84 |
subject of the operation.
|
|
85 |
<P>
|
|
86 |
<LI> As the user gestures navigate over <code>Component</code>(s)
|
|
87 |
in the GUI with
|
|
88 |
associated <code>DropTarget</code>(s), the <code>DragSource</code>
|
|
89 |
receives notifications in order
|
|
90 |
to provide "Drag Over" feedback effects, and the <code>DropTarget</code>(s)
|
|
91 |
receive notifications in order to provide "Drag Under" feedback effects
|
|
92 |
based upon the operation(s) supported and the data type(s) involved.
|
|
93 |
</UL>
|
|
94 |
<P>
|
|
95 |
|
|
96 |
The gesture itself moves a logical cursor across the GUI hierarchy,
|
|
97 |
intersecting the geometry of GUI Component(s), possibly resulting in
|
|
98 |
the logical "Drag" cursor entering, crossing, and subsequently
|
|
99 |
leaving <code>Component</code>(s) and associated <code>DropTarget</code>(s).
|
|
100 |
<P>
|
|
101 |
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
|
|
102 |
logical cursor.
|
|
103 |
<P>
|
|
104 |
<code>DropTarget</code> objects manifest "Drag Under" feedback to the user, in
|
|
105 |
the typical case, by rendering animations into their associated GUI
|
|
106 |
<code>Component</code>(s) under the GUI Cursor.
|
|
107 |
<P>
|
|
108 |
The determination of the feedback effects, and the ultimate success
|
|
109 |
or failure of the data transfer, should one occur, is parameterized
|
|
110 |
as follows:
|
|
111 |
<UL>
|
|
112 |
<LI> By the transfer "operation" selected by the user, and supported by
|
|
113 |
both the <code>DragSource</code> and <code>DropTarget</code>: Copy, Move or Reference(link).
|
|
114 |
<P>
|
|
115 |
<LI> By the intersection of the set of data types provided by the
|
|
116 |
<code>DragSource</code> and the set of data types comprehensible by the
|
|
117 |
<code>DropTarget</code>.
|
|
118 |
<P>
|
|
119 |
<LI>When the user terminates the drag operation, normally resulting in a
|
|
120 |
successful Drop, both the <code>DragSource</code> and <code>DropTarget</code>
|
|
121 |
receive
|
|
122 |
notifications that include, and result in the type negotiation and
|
|
123 |
transfer of, the information associated with the <code>DragSource</code> via a
|
|
124 |
<code>Transferable</code> object.
|
|
125 |
</UL>
|
|
126 |
|
|
127 |
<!--
|
|
128 |
<h2>Package Specification</h2>
|
|
129 |
|
|
130 |
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
|
|
131 |
<ul>
|
|
132 |
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
|
|
133 |
</ul>
|
|
134 |
|
|
135 |
<h2>Related Documentation</h2>
|
|
136 |
|
|
137 |
For overviews, tutorials, examples, guides, and tool documentation, please see:
|
|
138 |
<ul>
|
|
139 |
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
|
|
140 |
</ul>
|
|
141 |
-->
|
|
142 |
|
|
143 |
@since 1.2
|
|
144 |
</body>
|
|
145 |
</html>
|