1/*
2 * Copyright (c) 1997, 2007, 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
30import java.awt.dnd.DropTargetDragEvent;
31import java.awt.dnd.DropTargetDropEvent;
32
33/**
34 * The {@code DropTargetListener} interface
35 * is the callback interface used by the
36 * {@code DropTarget} class to provide
37 * notification of DnD operations that involve
38 * the subject {@code DropTarget}. Methods of
39 * this interface may be implemented to provide
40 * "drag under" visual feedback to the user throughout
41 * the Drag and Drop operation.
42 * <p>
43 * Create a listener object by implementing the interface and then register it
44 * with a {@code DropTarget}. When the drag enters, moves over, or exits
45 * the operable part of the drop site for that {@code DropTarget}, when
46 * the drop action changes, and when the drop occurs, the relevant method in
47 * the listener object is invoked, and the {@code DropTargetEvent} is
48 * passed to it.
49 * <p>
50 * The operable part of the drop site for the {@code DropTarget} is
51 * the part of the associated {@code Component}'s geometry that is not
52 * obscured by an overlapping top-level window or by another
53 * {@code Component} higher in the Z-order that has an associated active
54 * {@code DropTarget}.
55 * <p>
56 * During the drag, the data associated with the current drag operation can be
57 * retrieved by calling {@code getTransferable()} on
58 * {@code DropTargetDragEvent} instances passed to the listener's
59 * methods.
60 * <p>
61 * Note that {@code getTransferable()} on the
62 * {@code DropTargetDragEvent} instance should only be called within the
63 * respective listener's method and all the necessary data should be retrieved
64 * from the returned {@code Transferable} before that method returns.
65 *
66 * @since 1.2
67 */
68
69public interface DropTargetListener extends EventListener {
70
71    /**
72     * Called while a drag operation is ongoing, when the mouse pointer enters
73     * the operable part of the drop site for the {@code DropTarget}
74     * registered with this listener.
75     *
76     * @param dtde the {@code DropTargetDragEvent}
77     */
78
79    void dragEnter(DropTargetDragEvent dtde);
80
81    /**
82     * Called when a drag operation is ongoing, while the mouse pointer is still
83     * over the operable part of the drop site for the {@code DropTarget}
84     * registered with this listener.
85     *
86     * @param dtde the {@code DropTargetDragEvent}
87     */
88
89    void dragOver(DropTargetDragEvent dtde);
90
91    /**
92     * Called if the user has modified
93     * the current drop gesture.
94     *
95     * @param dtde the {@code DropTargetDragEvent}
96     */
97
98    void dropActionChanged(DropTargetDragEvent dtde);
99
100    /**
101     * Called while a drag operation is ongoing, when the mouse pointer has
102     * exited the operable part of the drop site for the
103     * {@code DropTarget} registered with this listener.
104     *
105     * @param dte the {@code DropTargetEvent}
106     */
107
108    void dragExit(DropTargetEvent dte);
109
110    /**
111     * Called when the drag operation has terminated with a drop on
112     * the operable part of the drop site for the {@code DropTarget}
113     * registered with this listener.
114     * <p>
115     * This method is responsible for undertaking
116     * the transfer of the data associated with the
117     * gesture. The {@code DropTargetDropEvent}
118     * provides a means to obtain a {@code Transferable}
119     * object that represents the data object(s) to
120     * be transferred.<P>
121     * From this method, the {@code DropTargetListener}
122     * shall accept or reject the drop via the
123     * acceptDrop(int dropAction) or rejectDrop() methods of the
124     * {@code DropTargetDropEvent} parameter.
125     * <P>
126     * Subsequent to acceptDrop(), but not before,
127     * {@code DropTargetDropEvent}'s getTransferable()
128     * method may be invoked, and data transfer may be
129     * performed via the returned {@code Transferable}'s
130     * getTransferData() method.
131     * <P>
132     * At the completion of a drop, an implementation
133     * of this method is required to signal the success/failure
134     * of the drop by passing an appropriate
135     * {@code boolean} to the {@code DropTargetDropEvent}'s
136     * dropComplete(boolean success) method.
137     * <P>
138     * Note: The data transfer should be completed before the call  to the
139     * {@code DropTargetDropEvent}'s dropComplete(boolean success) method.
140     * After that, a call to the getTransferData() method of the
141     * {@code Transferable} returned by
142     * {@code DropTargetDropEvent.getTransferable()} is guaranteed to
143     * succeed only if the data transfer is local; that is, only if
144     * {@code DropTargetDropEvent.isLocalTransfer()} returns
145     * {@code true}. Otherwise, the behavior of the call is
146     * implementation-dependent.
147     *
148     * @param dtde the {@code DropTargetDropEvent}
149     */
150
151    void drop(DropTargetDropEvent dtde);
152}
153