1/*
2 * Copyright (c) 2001, 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
28/**
29 * An abstract adapter class for receiving drag source events. The methods in
30 * this class are empty. This class exists only as a convenience for creating
31 * listener objects.
32 * <p>
33 * Extend this class to create a {@code DragSourceEvent} listener
34 * and override the methods for the events of interest. (If you implement the
35 * {@code DragSourceListener} interface, you have to define all of
36 * the methods in it. This abstract class defines null methods for them
37 * all, so you only have to define methods for events you care about.)
38 * <p>
39 * Create a listener object using the extended class and then register it with
40 * a {@code DragSource}. When the drag enters, moves over, or exits
41 * a drop site, when the drop action changes, and when the drag ends, the
42 * relevant method in the listener object is invoked, and the
43 * {@code DragSourceEvent} is passed to it.
44 * <p>
45 * The drop site is <i>associated with the previous {@code dragEnter()}
46 * invocation</i> if the latest invocation of {@code dragEnter()} on this
47 * adapter corresponds to that drop site and is not followed by a
48 * {@code dragExit()} invocation on this adapter.
49 *
50 * @see DragSourceEvent
51 * @see DragSourceListener
52 * @see DragSourceMotionListener
53 *
54 * @author David Mendenhall
55 * @since 1.4
56 */
57public abstract class DragSourceAdapter
58    implements DragSourceListener, DragSourceMotionListener {
59
60    /**
61     * Called as the cursor's hotspot enters a platform-dependent drop site.
62     * This method is invoked when all the following conditions are true:
63     * <UL>
64     * <LI>The cursor's hotspot enters the operable part of
65     * a platform-dependent drop site.
66     * <LI>The drop site is active.
67     * <LI>The drop site accepts the drag.
68     * </UL>
69     *
70     * @param dsde the {@code DragSourceDragEvent}
71     */
72    public void dragEnter(DragSourceDragEvent dsde) {}
73
74    /**
75     * Called as the cursor's hotspot moves over a platform-dependent drop site.
76     * This method is invoked when all the following conditions are true:
77     * <UL>
78     * <LI>The cursor's hotspot has moved, but still intersects the
79     * operable part of the drop site associated with the previous
80     * dragEnter() invocation.
81     * <LI>The drop site is still active.
82     * <LI>The drop site accepts the drag.
83     * </UL>
84     *
85     * @param dsde the {@code DragSourceDragEvent}
86     */
87    public void dragOver(DragSourceDragEvent dsde) {}
88
89    /**
90     * Called whenever the mouse is moved during a drag operation.
91     *
92     * @param dsde the {@code DragSourceDragEvent}
93     */
94    public void dragMouseMoved(DragSourceDragEvent dsde) {}
95
96    /**
97     * Called when the user has modified the drop gesture.
98     * This method is invoked when the state of the input
99     * device(s) that the user is interacting with changes.
100     * Such devices are typically the mouse buttons or keyboard
101     * modifiers that the user is interacting with.
102     *
103     * @param dsde the {@code DragSourceDragEvent}
104     */
105    public void dropActionChanged(DragSourceDragEvent dsde) {}
106
107    /**
108     * Called as the cursor's hotspot exits a platform-dependent drop site.
109     * This method is invoked when any of the following conditions are true:
110     * <UL>
111     * <LI>The cursor's hotspot no longer intersects the operable part
112     * of the drop site associated with the previous dragEnter() invocation.
113     * </UL>
114     * OR
115     * <UL>
116     * <LI>The drop site associated with the previous dragEnter() invocation
117     * is no longer active.
118     * </UL>
119     * OR
120     * <UL>
121     * <LI> The drop site associated with the previous dragEnter() invocation
122     * has rejected the drag.
123     * </UL>
124     *
125     * @param dse the {@code DragSourceEvent}
126     */
127    public void dragExit(DragSourceEvent dse) {}
128
129    /**
130     * This method is invoked to signify that the Drag and Drop
131     * operation is complete. The getDropSuccess() method of
132     * the {@code DragSourceDropEvent} can be used to
133     * determine the termination state. The getDropAction() method
134     * returns the operation that the drop site selected
135     * to apply to the Drop operation. Once this method is complete, the
136     * current {@code DragSourceContext} and
137     * associated resources become invalid.
138     *
139     * @param dsde the {@code DragSourceDropEvent}
140     */
141    public void dragDropEnd(DragSourceDropEvent dsde) {}
142}
143