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 DropTargetDragEvent} is delivered to a
37 * {@code DropTargetListener} via its
38 * dragEnter() and dragOver() methods.
39 * <p>
40 * The {@code DropTargetDragEvent} reports the <i>source drop actions</i>
41 * and the <i>user drop action</i> that reflect the current state of
42 * the drag operation.
43 * <p>
44 * <i>Source drop actions</i> is a bitwise mask of {@code DnDConstants}
45 * that represents the set of drop actions supported by the drag source for
46 * this drag operation.
47 * <p>
48 * <i>User drop action</i> depends on the drop actions supported by the drag
49 * source and the drop action selected by the user. The user can select a drop
50 * action by pressing modifier keys during the drag operation:
51 * <pre>
52 *   Ctrl + Shift -&gt; ACTION_LINK
53 *   Ctrl         -&gt; ACTION_COPY
54 *   Shift        -&gt; ACTION_MOVE
55 * </pre>
56 * If the user selects a drop action, the <i>user drop action</i> is one of
57 * {@code DnDConstants} that represents the selected drop action if this
58 * drop action is supported by the drag source or
59 * {@code DnDConstants.ACTION_NONE} if this drop action is not supported
60 * by the drag source.
61 * <p>
62 * If the user doesn't select a drop action, the set of
63 * {@code DnDConstants} that represents the set of drop actions supported
64 * by the drag source is searched for {@code DnDConstants.ACTION_MOVE},
65 * then for {@code DnDConstants.ACTION_COPY}, then for
66 * {@code DnDConstants.ACTION_LINK} and the <i>user drop action</i> is the
67 * first constant found. If no constant is found the <i>user drop action</i>
68 * is {@code DnDConstants.ACTION_NONE}.
69 *
70 * @since 1.2
71 */
72
73public class DropTargetDragEvent extends DropTargetEvent {
74
75    private static final long serialVersionUID = -8422265619058953682L;
76
77    /**
78     * Construct a {@code DropTargetDragEvent} given the
79     * {@code DropTargetContext} for this operation,
80     * the location of the "Drag" {@code Cursor}'s hotspot
81     * in the {@code Component}'s coordinates, the
82     * user drop action, and the source drop actions.
83     *
84     * @param dtc        The DropTargetContext for this operation
85     * @param cursorLocn The location of the "Drag" Cursor's
86     * hotspot in Component coordinates
87     * @param dropAction The user drop action
88     * @param srcActions The source drop actions
89     *
90     * @throws NullPointerException if cursorLocn is null
91     * @throws IllegalArgumentException if dropAction is not one of
92     *         {@code DnDConstants}.
93     * @throws IllegalArgumentException if srcActions is not
94     *         a bitwise mask of {@code DnDConstants}.
95     * @throws IllegalArgumentException if dtc is {@code null}.
96     */
97
98    public DropTargetDragEvent(DropTargetContext dtc, Point cursorLocn, int dropAction, int srcActions)  {
99        super(dtc);
100
101        if (cursorLocn == null) throw new NullPointerException("cursorLocn");
102
103        if (dropAction != DnDConstants.ACTION_NONE &&
104            dropAction != DnDConstants.ACTION_COPY &&
105            dropAction != DnDConstants.ACTION_MOVE &&
106            dropAction != DnDConstants.ACTION_LINK
107        ) throw new IllegalArgumentException("dropAction" + dropAction);
108
109        if ((srcActions & ~(DnDConstants.ACTION_COPY_OR_MOVE | DnDConstants.ACTION_LINK)) != 0) throw new IllegalArgumentException("srcActions");
110
111        location        = cursorLocn;
112        actions         = srcActions;
113        this.dropAction = dropAction;
114    }
115
116    /**
117     * This method returns a {@code Point}
118     * indicating the {@code Cursor}'s current
119     * location within the {@code Component'}s
120     * coordinates.
121     *
122     * @return the current cursor location in
123     * {@code Component}'s coords.
124     */
125
126    public Point getLocation() {
127        return location;
128    }
129
130
131    /**
132     * This method returns the current {@code DataFlavor}s from the
133     * {@code DropTargetContext}.
134     *
135     * @return current DataFlavors from the DropTargetContext
136     */
137
138    public DataFlavor[] getCurrentDataFlavors() {
139        return getDropTargetContext().getCurrentDataFlavors();
140    }
141
142    /**
143     * This method returns the current {@code DataFlavor}s
144     * as a {@code java.util.List}
145     *
146     * @return a {@code java.util.List} of the Current {@code DataFlavor}s
147     */
148
149    public List<DataFlavor> getCurrentDataFlavorsAsList() {
150        return getDropTargetContext().getCurrentDataFlavorsAsList();
151    }
152
153    /**
154     * This method returns a {@code boolean} indicating
155     * if the specified {@code DataFlavor} is supported.
156     *
157     * @param df the {@code DataFlavor} to test
158     *
159     * @return if a particular DataFlavor is supported
160     */
161
162    public boolean isDataFlavorSupported(DataFlavor df) {
163        return getDropTargetContext().isDataFlavorSupported(df);
164    }
165
166    /**
167     * This method returns the source drop actions.
168     *
169     * @return the source drop actions
170     */
171    public int getSourceActions() { return actions; }
172
173    /**
174     * This method returns the user drop action.
175     *
176     * @return the user drop action
177     */
178    public int getDropAction() { return dropAction; }
179
180    /**
181     * This method returns the Transferable object that represents
182     * the data associated with the current drag operation.
183     *
184     * @return the Transferable associated with the drag operation
185     * @throws InvalidDnDOperationException if the data associated with the drag
186     *         operation is not available
187     *
188     * @since 1.5
189     */
190    public Transferable getTransferable() {
191        return getDropTargetContext().getTransferable();
192    }
193
194    /**
195     * Accepts the drag.
196     *
197     * This method should be called from a
198     * {@code DropTargetListeners dragEnter},
199     * {@code dragOver}, and {@code dropActionChanged}
200     * methods if the implementation wishes to accept an operation
201     * from the srcActions other than the one selected by
202     * the user as represented by the {@code dropAction}.
203     *
204     * @param dragOperation the operation accepted by the target
205     */
206    public void acceptDrag(int dragOperation) {
207        getDropTargetContext().acceptDrag(dragOperation);
208    }
209
210    /**
211     * Rejects the drag as a result of examining either the
212     * {@code dropAction} or the available {@code DataFlavor}
213     * types.
214     */
215    public void rejectDrag() {
216        getDropTargetContext().rejectDrag();
217    }
218
219    /*
220     * fields
221     */
222
223    /**
224     * The location of the drag cursor's hotspot in Component coordinates.
225     *
226     * @serial
227     */
228    private Point               location;
229
230    /**
231     * The source drop actions.
232     *
233     * @serial
234     */
235    private int                 actions;
236
237    /**
238     * The user drop action.
239     *
240     * @serial
241     */
242    private int                 dropAction;
243}
244