001 /*
002 * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.dnd;
027
028 import java.awt.Component;
029 import java.awt.Cursor;
030
031 import java.awt.Image;
032 import java.awt.Point;
033
034 import java.awt.event.InputEvent;
035
036 import java.awt.datatransfer.Transferable;
037
038 import java.util.EventObject;
039
040 import java.util.Collections;
041 import java.util.List;
042 import java.util.Iterator;
043
044 import java.io.IOException;
045 import java.io.ObjectInputStream;
046 import java.io.ObjectOutputStream;
047
048 /**
049 * A <code>DragGestureEvent</code> is passed
050 * to <code>DragGestureListener</code>'s
051 * dragGestureRecognized() method
052 * when a particular <code>DragGestureRecognizer</code> detects that a
053 * platform dependent drag initiating gesture has occurred
054 * on the <code>Component</code> that it is tracking.
055 *
056 * @version 1.31
057 * @see java.awt.dnd.DragGestureRecognizer
058 * @see java.awt.dnd.DragGestureListener
059 * @see java.awt.dnd.DragSource
060 */
061
062 public class DragGestureEvent extends EventObject {
063
064 private static final long serialVersionUID = 9080172649166731306L;
065
066 /**
067 * Constructs a <code>DragGestureEvent</code> given the
068 * <code>DragGestureRecognizer</code> firing this event,
069 * an <code>int</code> representing
070 * the user's preferred action, a <code>Point</code>
071 * indicating the origin of the drag, and a <code>List</code>
072 * of events that comprise the gesture.
073 * <P>
074 * @param dgr The <code>DragGestureRecognizer</code> firing this event
075 * @param act The the user's preferred action
076 * @param ori The origin of the drag
077 * @param evs The <code>List</code> of events that comprise the gesture
078 * <P>
079 * @throws IllegalArgumentException if input parameters are {@code null}
080 */
081
082 public DragGestureEvent(DragGestureRecognizer dgr, int act,
083 Point ori, List<? extends InputEvent> evs) {
084 super (dgr);
085
086 if ((component = dgr.getComponent()) == null)
087 throw new IllegalArgumentException("null component");
088 if ((dragSource = dgr.getDragSource()) == null)
089 throw new IllegalArgumentException("null DragSource");
090
091 if (evs == null || evs.isEmpty())
092 throw new IllegalArgumentException(
093 "null or empty list of events");
094
095 if (act != DnDConstants.ACTION_COPY
096 && act != DnDConstants.ACTION_MOVE
097 && act != DnDConstants.ACTION_LINK)
098 throw new IllegalArgumentException("bad action");
099
100 if (ori == null)
101 throw new IllegalArgumentException("null origin");
102
103 events = evs;
104 action = act;
105 origin = ori;
106 }
107
108 /**
109 * Returns the source as a <code>DragGestureRecognizer</code>.
110 * <P>
111 * @return the source as a <code>DragGestureRecognizer</code>
112 */
113
114 public DragGestureRecognizer getSourceAsDragGestureRecognizer() {
115 return (DragGestureRecognizer) getSource();
116 }
117
118 /**
119 * Returns the <code>Component</code> associated
120 * with this <code>DragGestureEvent</code>.
121 * <P>
122 * @return the Component
123 */
124
125 public Component getComponent() {
126 return component;
127 }
128
129 /**
130 * Returns the <code>DragSource</code>.
131 * <P>
132 * @return the <code>DragSource</code>
133 */
134
135 public DragSource getDragSource() {
136 return dragSource;
137 }
138
139 /**
140 * Returns a <code>Point</code> in the coordinates
141 * of the <code>Component</code> over which the drag originated.
142 * <P>
143 * @return the Point where the drag originated in Component coords.
144 */
145
146 public Point getDragOrigin() {
147 return origin;
148 }
149
150 /**
151 * Returns an <code>Iterator</code> for the events
152 * comprising the gesture.
153 * <P>
154 * @return an Iterator for the events comprising the gesture
155 */
156
157 public Iterator<InputEvent> iterator() {
158 return events.iterator();
159 }
160
161 /**
162 * Returns an <code>Object</code> array of the
163 * events comprising the drag gesture.
164 * <P>
165 * @return an array of the events comprising the gesture
166 */
167
168 public Object[] toArray() {
169 return events.toArray();
170 }
171
172 /**
173 * Returns an array of the events comprising the drag gesture.
174 * <P>
175 * @param array the array of <code>EventObject</code> sub(types)
176 * <P>
177 * @return an array of the events comprising the gesture
178 */
179
180 public Object[] toArray(Object[] array) {
181 return events.toArray(array);
182 }
183
184 /**
185 * Returns an <code>int</code> representing the
186 * action selected by the user.
187 * <P>
188 * @return the action selected by the user
189 */
190
191 public int getDragAction() {
192 return action;
193 }
194
195 /**
196 * Returns the initial event that triggered the gesture.
197 * <P>
198 * @return the first "triggering" event in the sequence of the gesture
199 */
200
201 public InputEvent getTriggerEvent() {
202 return getSourceAsDragGestureRecognizer().getTriggerEvent();
203 }
204
205 /**
206 * Starts the drag operation given the <code>Cursor</code> for this drag
207 * operation and the <code>Transferable</code> representing the source data
208 * for this drag operation.
209 * <br>
210 * If a <code>null</code> <code>Cursor</code> is specified no exception will
211 * be thrown and default drag cursors will be used instead.
212 * <br>
213 * If a <code>null</code> <code>Transferable</code> is specified
214 * <code>NullPointerException</code> will be thrown.
215 * @param dragCursor The initial {@code Cursor} for this drag operation
216 * or {@code null} for the default cursor handling;
217 * see
218 * <a href="DragSourceContext.html#defaultCursor">DragSourceContext</a>
219 * for more details on the cursor handling mechanism
220 * during drag and drop
221 * @param transferable The <code>Transferable</code> representing the source
222 * data for this drag operation.
223 *
224 * @throws InvalidDnDOperationException if the Drag and Drop
225 * system is unable to initiate a drag operation, or if the user
226 * attempts to start a drag while an existing drag operation is
227 * still executing.
228 * @throws NullPointerException if the {@code Transferable} is {@code null}
229 * @since 1.4
230 */
231 public void startDrag(Cursor dragCursor, Transferable transferable)
232 throws InvalidDnDOperationException {
233 dragSource.startDrag(this , dragCursor, transferable, null);
234 }
235
236 /**
237 * Starts the drag given the initial <code>Cursor</code> to display,
238 * the <code>Transferable</code> object,
239 * and the <code>DragSourceListener</code> to use.
240 * <P>
241 * @param dragCursor The initial {@code Cursor} for this drag operation
242 * or {@code null} for the default cursor handling;
243 * see
244 * <a href="DragSourceContext.html#defaultCursor">DragSourceContext</a>
245 * for more details on the cursor handling mechanism
246 * during drag and drop
247 * @param transferable The source's Transferable
248 * @param dsl The source's DragSourceListener
249 * <P>
250 * @throws InvalidDnDOperationException if
251 * the Drag and Drop system is unable to
252 * initiate a drag operation, or if the user
253 * attempts to start a drag while an existing
254 * drag operation is still executing.
255 */
256
257 public void startDrag(Cursor dragCursor, Transferable transferable,
258 DragSourceListener dsl) throws InvalidDnDOperationException {
259 dragSource.startDrag(this , dragCursor, transferable, dsl);
260 }
261
262 /**
263 * Start the drag given the initial <code>Cursor</code> to display,
264 * a drag <code>Image</code>, the offset of
265 * the <code>Image</code>,
266 * the <code>Transferable</code> object, and
267 * the <code>DragSourceListener</code> to use.
268 * <P>
269 * @param dragCursor The initial {@code Cursor} for this drag operation
270 * or {@code null} for the default cursor handling;
271 * see
272 * <a href="DragSourceContext.html#defaultCursor">DragSourceContext</a>
273 * for more details on the cursor handling mechanism
274 * during drag and drop
275 * @param dragImage The source's dragImage
276 * @param imageOffset The dragImage's offset
277 * @param transferable The source's Transferable
278 * @param dsl The source's DragSourceListener
279 * <P>
280 * @throws InvalidDnDOperationException if
281 * the Drag and Drop system is unable to
282 * initiate a drag operation, or if the user
283 * attempts to start a drag while an existing
284 * drag operation is still executing.
285 */
286
287 public void startDrag(Cursor dragCursor, Image dragImage,
288 Point imageOffset, Transferable transferable,
289 DragSourceListener dsl) throws InvalidDnDOperationException {
290 dragSource.startDrag(this , dragCursor, dragImage, imageOffset,
291 transferable, dsl);
292 }
293
294 /**
295 * Serializes this <code>DragGestureEvent</code>. Performs default
296 * serialization and then writes out this object's <code>List</code> of
297 * gesture events if and only if the <code>List</code> can be serialized.
298 * If not, <code>null</code> is written instead. In this case, a
299 * <code>DragGestureEvent</code> created from the resulting deserialized
300 * stream will contain an empty <code>List</code> of gesture events.
301 *
302 * @serialData The default serializable fields, in alphabetical order,
303 * followed by either a <code>List</code> instance, or
304 * <code>null</code>.
305 * @since 1.4
306 */
307 private void writeObject(ObjectOutputStream s) throws IOException {
308 s.defaultWriteObject();
309
310 s.writeObject(SerializationTester.test(events) ? events : null);
311 }
312
313 /**
314 * Deserializes this <code>DragGestureEvent</code>. This method first
315 * performs default deserialization for all non-<code>transient</code>
316 * fields. An attempt is then made to deserialize this object's
317 * <code>List</code> of gesture events as well. This is first attempted
318 * by deserializing the field <code>events</code>, because, in releases
319 * prior to 1.4, a non-<code>transient</code> field of this name stored the
320 * <code>List</code> of gesture events. If this fails, the next object in
321 * the stream is used instead. If the resulting <code>List</code> is
322 * <code>null</code>, this object's <code>List</code> of gesture events
323 * is set to an empty <code>List</code>.
324 *
325 * @since 1.4
326 */
327 private void readObject(ObjectInputStream s)
328 throws ClassNotFoundException, IOException {
329 ObjectInputStream.GetField f = s.readFields();
330
331 dragSource = (DragSource) f.get("dragSource", null);
332 component = (Component) f.get("component", null);
333 origin = (Point) f.get("origin", null);
334 action = f.get("action", 0);
335
336 // Pre-1.4 support. 'events' was previously non-transient
337 try {
338 events = (List) f.get("events", null);
339 } catch (IllegalArgumentException e) {
340 // 1.4-compatible byte stream. 'events' was written explicitly
341 events = (List) s.readObject();
342 }
343
344 // Implementation assumes 'events' is never null.
345 if (events == null) {
346 events = Collections.EMPTY_LIST;
347 }
348 }
349
350 /*
351 * fields
352 */
353
354 private transient List events;
355
356 /**
357 * The DragSource associated with this DragGestureEvent.
358 *
359 * @serial
360 */
361 private DragSource dragSource;
362
363 /**
364 * The Component associated with this DragGestureEvent.
365 *
366 * @serial
367 */
368 private Component component;
369
370 /**
371 * The origin of the drag.
372 *
373 * @serial
374 */
375 private Point origin;
376
377 /**
378 * The user's preferred action.
379 *
380 * @serial
381 */
382 private int action;
383 }
|