1 /*
2  * Copyright (c) 1997, 2003, 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 package java.awt.dnd;
27 
28 import java.util.EventListener;
29 
30 /**
31  * The {@code DragSourceListener} defines the
32  * event interface for originators of
33  * Drag and Drop operations to track the state of the user's gesture, and to
34  * provide appropriate "drag over"
35  * feedback to the user throughout the
36  * Drag and Drop operation.
37  * <p>
38  * The drop site is <i>associated with the previous {@code dragEnter()}
39  * invocation</i> if the latest invocation of {@code dragEnter()} on this
40  * listener:
41  * <ul>
42  * <li>corresponds to that drop site and
43  * <li> is not followed by a {@code dragExit()} invocation on this listener.
44  * </ul>
45  *
46  * @since 1.2
47  */
48 
49 public interface DragSourceListener extends EventListener {
50 
51     /**
52      * Called as the cursor's hotspot enters a platform-dependent drop site.
53      * This method is invoked when all the following conditions are true:
54      * <UL>
55      * <LI>The cursor's hotspot enters the operable part of a platform-
56      * dependent drop site.
57      * <LI>The drop site is active.
58      * <LI>The drop site accepts the drag.
59      * </UL>
60      *
61      * @param dsde the {@code DragSourceDragEvent}
62      */
dragEnter(DragSourceDragEvent dsde)63     void dragEnter(DragSourceDragEvent dsde);
64 
65     /**
66      * Called as the cursor's hotspot moves over a platform-dependent drop site.
67      * This method is invoked when all the following conditions are true:
68      * <UL>
69      * <LI>The cursor's hotspot has moved, but still intersects the
70      * operable part of the drop site associated with the previous
71      * dragEnter() invocation.
72      * <LI>The drop site is still active.
73      * <LI>The drop site accepts the drag.
74      * </UL>
75      *
76      * @param dsde the {@code DragSourceDragEvent}
77      */
dragOver(DragSourceDragEvent dsde)78     void dragOver(DragSourceDragEvent dsde);
79 
80     /**
81      * Called when the user has modified the drop gesture.
82      * This method is invoked when the state of the input
83      * device(s) that the user is interacting with changes.
84      * Such devices are typically the mouse buttons or keyboard
85      * modifiers that the user is interacting with.
86      *
87      * @param dsde the {@code DragSourceDragEvent}
88      */
dropActionChanged(DragSourceDragEvent dsde)89     void dropActionChanged(DragSourceDragEvent dsde);
90 
91     /**
92      * Called as the cursor's hotspot exits a platform-dependent drop site.
93      * This method is invoked when any of the following conditions are true:
94      * <UL>
95      * <LI>The cursor's hotspot no longer intersects the operable part
96      * of the drop site associated with the previous dragEnter() invocation.
97      * </UL>
98      * OR
99      * <UL>
100      * <LI>The drop site associated with the previous dragEnter() invocation
101      * is no longer active.
102      * </UL>
103      * OR
104      * <UL>
105      * <LI> The drop site associated with the previous dragEnter() invocation
106      * has rejected the drag.
107      * </UL>
108      *
109      * @param dse the {@code DragSourceEvent}
110      */
dragExit(DragSourceEvent dse)111     void dragExit(DragSourceEvent dse);
112 
113     /**
114      * This method is invoked to signify that the Drag and Drop
115      * operation is complete. The getDropSuccess() method of
116      * the {@code DragSourceDropEvent} can be used to
117      * determine the termination state. The getDropAction() method
118      * returns the operation that the drop site selected
119      * to apply to the Drop operation. Once this method is complete, the
120      * current {@code DragSourceContext} and
121      * associated resources become invalid.
122      *
123      * @param dsde the {@code DragSourceDropEvent}
124      */
dragDropEnd(DragSourceDropEvent dsde)125     void dragDropEnd(DragSourceDropEvent dsde);
126 }
127