1/*
2 * Copyright (c) 1997, 2013, 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.awt.Point;
29
30import java.awt.datatransfer.DataFlavor;
31import java.awt.datatransfer.Transferable;
32
33import java.util.List;
34
35/**
36 * The {@code DropTargetDropEvent} is delivered
37 * via the {@code DropTargetListener} drop() method.
38 * <p>
39 * The {@code DropTargetDropEvent} reports the <i>source drop actions</i>
40 * and the <i>user drop action</i> that reflect the current state of the
41 * drag-and-drop operation.
42 * <p>
43 * <i>Source drop actions</i> is a bitwise mask of {@code DnDConstants}
44 * that represents the set of drop actions supported by the drag source for
45 * this drag-and-drop operation.
46 * <p>
47 * <i>User drop action</i> depends on the drop actions supported by the drag
48 * source and the drop action selected by the user. The user can select a drop
49 * action by pressing modifier keys during the drag operation:
50 * <pre>
51 *   Ctrl + Shift -&gt; ACTION_LINK
52 *   Ctrl         -&gt; ACTION_COPY
53 *   Shift        -&gt; ACTION_MOVE
54 * </pre>
55 * If the user selects a drop action, the <i>user drop action</i> is one of
56 * {@code DnDConstants} that represents the selected drop action if this
57 * drop action is supported by the drag source or
58 * {@code DnDConstants.ACTION_NONE} if this drop action is not supported
59 * by the drag source.
60 * <p>
61 * If the user doesn't select a drop action, the set of
62 * {@code DnDConstants} that represents the set of drop actions supported
63 * by the drag source is searched for {@code DnDConstants.ACTION_MOVE},
64 * then for {@code DnDConstants.ACTION_COPY}, then for
65 * {@code DnDConstants.ACTION_LINK} and the <i>user drop action</i> is the
66 * first constant found. If no constant is found the <i>user drop action</i>
67 * is {@code DnDConstants.ACTION_NONE}.
68 *
69 * @since 1.2
70 */
71
72public class DropTargetDropEvent extends DropTargetEvent {
73
74    private static final long serialVersionUID = -1721911170440459322L;
75
76    /**
77     * Construct a {@code DropTargetDropEvent} given
78     * the {@code DropTargetContext} for this operation,
79     * the location of the drag {@code Cursor}'s
80     * hotspot in the {@code Component}'s coordinates,
81     * the currently
82     * selected user drop action, and the current set of
83     * actions supported by the source.
84     * By default, this constructor
85     * assumes that the target is not in the same virtual machine as
86     * the source; that is, {@link #isLocalTransfer()} will
87     * return {@code false}.
88     *
89     * @param dtc        The {@code DropTargetContext} for this operation
90     * @param cursorLocn The location of the "Drag" Cursor's
91     * hotspot in {@code Component} coordinates
92     * @param dropAction the user drop action.
93     * @param srcActions the source drop actions.
94     *
95     * @throws NullPointerException
96     * if cursorLocn is {@code null}
97     * @throws IllegalArgumentException
98     *         if dropAction is not one of  {@code DnDConstants}.
99     * @throws IllegalArgumentException
100     *         if srcActions is not a bitwise mask of {@code DnDConstants}.
101     * @throws IllegalArgumentException if dtc is {@code null}.
102     */
103
104    public DropTargetDropEvent(DropTargetContext dtc, Point cursorLocn, int dropAction, int srcActions)  {
105        super(dtc);
106
107        if (cursorLocn == null) throw new NullPointerException("cursorLocn");
108
109        if (dropAction != DnDConstants.ACTION_NONE &&
110            dropAction != DnDConstants.ACTION_COPY &&
111            dropAction != DnDConstants.ACTION_MOVE &&
112            dropAction != DnDConstants.ACTION_LINK
113        ) throw new IllegalArgumentException("dropAction = " + dropAction);
114
115        if ((srcActions & ~(DnDConstants.ACTION_COPY_OR_MOVE | DnDConstants.ACTION_LINK)) != 0) throw new IllegalArgumentException("srcActions");
116
117        location        = cursorLocn;
118        actions         = srcActions;
119        this.dropAction = dropAction;
120    }
121
122    /**
123     * Construct a {@code DropTargetEvent} given the
124     * {@code DropTargetContext} for this operation,
125     * the location of the drag {@code Cursor}'s hotspot
126     * in the {@code Component}'s
127     * coordinates, the currently selected user drop action,
128     * the current set of actions supported by the source,
129     * and a {@code boolean} indicating if the source is in the same JVM
130     * as the target.
131     *
132     * @param dtc        The DropTargetContext for this operation
133     * @param cursorLocn The location of the "Drag" Cursor's
134     * hotspot in Component's coordinates
135     * @param dropAction the user drop action.
136     * @param srcActions the source drop actions.
137     * @param isLocal  True if the source is in the same JVM as the target
138     *
139     * @throws NullPointerException
140     *         if cursorLocn is  {@code null}
141     * @throws IllegalArgumentException
142     *         if dropAction is not one of {@code DnDConstants}.
143     * @throws IllegalArgumentException if srcActions is not a bitwise mask of {@code DnDConstants}.
144     * @throws IllegalArgumentException  if dtc is {@code null}.
145     */
146
147    public DropTargetDropEvent(DropTargetContext dtc, Point cursorLocn, int dropAction, int srcActions, boolean isLocal)  {
148        this(dtc, cursorLocn, dropAction, srcActions);
149
150        isLocalTx = isLocal;
151    }
152
153    /**
154     * This method returns a {@code Point}
155     * indicating the {@code Cursor}'s current
156     * location in the {@code Component}'s coordinates.
157     *
158     * @return the current {@code Cursor} location in Component's coords.
159     */
160
161    public Point getLocation() {
162        return location;
163    }
164
165
166    /**
167     * This method returns the current DataFlavors.
168     *
169     * @return current DataFlavors
170     */
171
172    public DataFlavor[] getCurrentDataFlavors() {
173        return getDropTargetContext().getCurrentDataFlavors();
174    }
175
176    /**
177     * This method returns the currently available
178     * {@code DataFlavor}s as a {@code java.util.List}.
179     *
180     * @return the currently available DataFlavors as a java.util.List
181     */
182
183    public List<DataFlavor> getCurrentDataFlavorsAsList() {
184        return getDropTargetContext().getCurrentDataFlavorsAsList();
185    }
186
187    /**
188     * This method returns a {@code boolean} indicating if the
189     * specified {@code DataFlavor} is available
190     * from the source.
191     *
192     * @param df the {@code DataFlavor} to test
193     *
194     * @return if the DataFlavor specified is available from the source
195     */
196
197    public boolean isDataFlavorSupported(DataFlavor df) {
198        return getDropTargetContext().isDataFlavorSupported(df);
199    }
200
201    /**
202     * This method returns the source drop actions.
203     *
204     * @return the source drop actions.
205     */
206    public int getSourceActions() { return actions; }
207
208    /**
209     * This method returns the user drop action.
210     *
211     * @return the user drop actions.
212     */
213    public int getDropAction() { return dropAction; }
214
215    /**
216     * This method returns the {@code Transferable} object
217     * associated with the drop.
218     *
219     * @return the {@code Transferable} associated with the drop
220     */
221
222    public Transferable getTransferable() {
223        return getDropTargetContext().getTransferable();
224    }
225
226    /**
227     * accept the drop, using the specified action.
228     *
229     * @param dropAction the specified action
230     */
231
232    public void acceptDrop(int dropAction) {
233        getDropTargetContext().acceptDrop(dropAction);
234    }
235
236    /**
237     * reject the Drop.
238     */
239
240    public void rejectDrop() {
241        getDropTargetContext().rejectDrop();
242    }
243
244    /**
245     * This method notifies the {@code DragSource}
246     * that the drop transfer(s) are completed.
247     *
248     * @param success a {@code boolean} indicating that the drop transfer(s) are completed.
249     */
250
251    public void dropComplete(boolean success) {
252        getDropTargetContext().dropComplete(success);
253    }
254
255    /**
256     * This method returns an {@code int} indicating if
257     * the source is in the same JVM as the target.
258     *
259     * @return if the Source is in the same JVM
260     */
261
262    public boolean isLocalTransfer() {
263        return isLocalTx;
264    }
265
266    /*
267     * fields
268     */
269
270    private static final Point  zero     = new Point(0,0);
271
272    /**
273     * The location of the drag cursor's hotspot in Component coordinates.
274     *
275     * @serial
276     */
277    private Point               location   = zero;
278
279    /**
280     * The source drop actions.
281     *
282     * @serial
283     */
284    private int                 actions    = DnDConstants.ACTION_NONE;
285
286    /**
287     * The user drop action.
288     *
289     * @serial
290     */
291    private int                 dropAction = DnDConstants.ACTION_NONE;
292
293    /**
294     * {@code true} if the source is in the same JVM as the target.
295     *
296     * @serial
297     */
298    private boolean             isLocalTx = false;
299}
300