1/* 2 * Copyright (c) 1998, 2017, 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/** 27 * Drag and Drop is a direct manipulation gesture found in many Graphical User 28 * Interface systems that provides a mechanism to transfer information between 29 * two entities logically associated with presentation elements in the GUI. 30 * Normally driven by a physical gesture of a human user using an appropriate 31 * input device, Drag and Drop provides both a mechanism to enable continuous 32 * feedback regarding the possible outcome of any subsequent data transfer to 33 * the user during navigation over the presentation elements in the GUI, and the 34 * facilities to provide for any subsequent data negotiation and transfer. 35 * <p> 36 * This package defines the classes and interfaces necessary to perform Drag and 37 * Drop operations in Java. It defines classes for the drag-source and the 38 * drop-target, as well as events for transferring the data being dragged. This 39 * package also provides a means for giving visual feedback to the user 40 * throughout the duration of the Drag and Drop operation. 41 * <p> 42 * A typical Drag and Drop operation can be decomposed into the following states 43 * (not entirely sequentially): 44 * <ul> 45 * <li>A {@code DragSource} comes into existence, associated with some 46 * presentation element ({@code Component}) in the GUI, to initiate a Drag 47 * and Drop of some potentially {@code Transferable} data.</li> 48 * <li>1 or more {@code DropTarget}(s) come into/go out of existence, 49 * associated with presentation elements in the GUI (Components), 50 * potentially capable of consuming {@code Transferable} data types.</li> 51 * <li>A {@code DragGestureRecognizer} is obtained from the 52 * {@code DragSource} and is associated with a {@code Component} in order to 53 * track and identify any Drag initiating gesture by the user over the 54 * {@code Component}.</li> 55 * <li>A user makes a Drag gesture over the {@code Component}, which the 56 * registered {@code DragGestureRecognizer} detects, and notifies its 57 * {@code DragGestureListener} of. 58 * <p> 59 * Note: Although this API consistently refers to the stimulus for a drag 60 * and drop operation being a physical gesture by a human user, this does 61 * not preclude a programmatically driven DnD operation given the 62 * appropriate implementation of a {@code DragSource}. This package 63 * contains the abstract class {@code MouseDragGestureRecognizer} for 64 * recognizing mouse device gestures. Other abstract subclasses may be 65 * provided by the platform to support other input devices or particular 66 * {@code Component} class semantics.</li> 67 * <li>The {@code DragGestureListener} causes the {@code DragSource} to 68 * initiate the Drag and Drop operation on behalf of the user, perhaps 69 * animating the GUI Cursor and/or rendering an {@code Image} of the item(s) 70 * that are the subject of the operation.</li> 71 * <li>As the user gestures navigate over {@code Component}(s) in the GUI 72 * with associated {@code DropTarget}(s), the {@code DragSource} receives 73 * notifications in order to provide "Drag Over" feedback effects, and the 74 * {@code DropTarget}(s) receive notifications in order to provide 75 * "Drag Under" feedback effects based upon the operation(s) supported and 76 * the data type(s) involved.</li> 77 * </ul> 78 * <p> 79 * The gesture itself moves a logical cursor across the GUI hierarchy, 80 * intersecting the geometry of GUI Component(s), possibly resulting in the 81 * logical "Drag" cursor entering, crossing, and subsequently leaving 82 * {@code Component}(s) and associated {@code DropTarget}(s). 83 * <p> 84 * The {@code DragSource} object manifests "Drag Over" feedback to the user, in 85 * the typical case by animating the GUI {@code Cursor} associated with the 86 * logical cursor. 87 * <p> 88 * {@code DropTarget} objects manifest "Drag Under" feedback to the user, in the 89 * typical case, by rendering animations into their associated GUI 90 * {@code Component}(s) under the GUI Cursor. 91 * <p> 92 * The determination of the feedback effects, and the ultimate success or 93 * failure of the data transfer, should one occur, is parameterized as follows: 94 * <ul> 95 * <li>By the transfer "operation" selected by the user, and supported by 96 * both the {@code DragSource} and {@code DropTarget}: Copy, Move or 97 * Reference(link).</li> 98 * <li>By the intersection of the set of data types provided by the 99 * {@code DragSource} and the set of data types comprehensible by the 100 * {@code DropTarget}.</li> 101 * <li>When the user terminates the drag operation, normally resulting in a 102 * successful Drop, both the {@code DragSource} and {@code DropTarget} 103 * receive notifications that include, and result in the type negotiation 104 * and transfer of, the information associated with the {@code DragSource} 105 * via a {@code Transferable} object.</li> 106 * </ul> 107 * 108 * @since 1.2 109 */ 110package java.awt.dnd; 111