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