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
26package java.awt.dnd;
27
28import 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
49public 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     */
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     */
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     */
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     */
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     */
125    void dragDropEnd(DragSourceDropEvent dsde);
126}
127