DragGestureEvent


1   /*
2    * @(#)DragGestureEvent.java    1.23 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   
9   package java.awt.dnd;
10  
11  import java.awt.Component  ;
12  import java.awt.Cursor  ;
13  
14  import java.awt.Image  ;
15  import java.awt.Point  ;
16  
17  import java.awt.event.InputEvent  ;
18  
19  import java.awt.datatransfer.Transferable  ;
20  
21  import java.util.EventObject  ;
22  
23  import java.util.Collections  ;
24  import java.util.List  ;
25  import java.util.Iterator  ;
26  
27  import java.io.IOException  ;
28  import java.io.ObjectInputStream  ;
29  import java.io.ObjectOutputStream  ;
30  import java.io.Serializable  ;
31  
32  
33  /**
34   * A <code>DragGestureEvent</code> is passed 
35   * to <code>DragGestureListener</code>'s  
36   * dragGestureRecognized() method
37   * when a particular <code>DragGestureRecognizer</code> detects that a 
38   * platform dependent drag initiating gesture has occurred 
39   * on the <code>Component</code> that it is tracking.
40   * 
41   * @version 1.23
42   * @see java.awt.dnd.DragGestureRecognizer
43   * @see java.awt.dnd.DragGestureListener
44   * @see java.awt.dnd.DragSource
45   */
46  
47  public class DragGestureEvent extends EventObject   {
48  
49      private static final long serialVersionUID = 9080172649166731306L;
50  
51      /**
52       * Construct a <code>DragGestureEvent</code> given the
53       * <code>DragGestureRecognizer</code> firing this event, 
54       * an <code>int</code> representing
55       * the user's preferred action, a <code>Point</code> 
56       * indicating the origin of the drag, and a <code>List</code> 
57       * of events that comprise the gesture.
58       * <P>
59       * @param dgr The <code>DragGestureRecognizer</code> firing this event
60       * @param act The the user's preferred action
61       * @param ori The origin of the drag
62       * @param evs The <code>List</code> of events that comprise the gesture
63       * <P>
64       * @throws <code>IllegalArgumentException</code> if 
65       * input parameters are null
66       */
67  
68      public DragGestureEvent(DragGestureRecognizer   dgr, int act, Point   ori,
69                  List  <? extends InputEvent  > evs)
70      {
71      super(dgr);
72  
73      if ((component = dgr.getComponent()) == null)
74          throw new IllegalArgumentException  ("null component");
75      if ((dragSource = dgr.getDragSource()) == null)
76          throw new IllegalArgumentException  ("null DragSource");
77  
78      if (evs == null || evs.isEmpty())
79          throw new IllegalArgumentException  ("null or empty list of events");
80  
81      if (act != DnDConstants.ACTION_COPY &&
82          act != DnDConstants.ACTION_MOVE &&
83          act != DnDConstants.ACTION_LINK)
84          throw new IllegalArgumentException  ("bad action");
85  
86      if (ori == null) throw new IllegalArgumentException  ("null origin");
87  
88      events     = evs;
89      action     = act;
90      origin     = ori;
91      }
92  
93      /**
94       * Returns the source as a <code>DragGestureRecognizer</code>.
95       * <P>
96       * @return the source as a <code>DragGestureRecognizer</code>
97       */
98  
99      public DragGestureRecognizer   getSourceAsDragGestureRecognizer() {
100     return (DragGestureRecognizer  )getSource();
101     }
102 
103     /**
104      * Returns the <code>Component</code> associated 
105      * with this <code>DragGestureEvent</code>.
106      * <P>
107      * @return the Component
108      */
109 
110     public Component   getComponent() { return component; }
111 
112     /**
113      * Returns the <code>DragSource</code>.
114      * <P>
115      * @return the <code>DragSource</code>
116      */
117 
118     public DragSource   getDragSource() { return dragSource; }
119 
120     /**
121      * Returns a <code>Point</code> in the coordinates
122      * of the <code>Component</code> over which the drag originated.
123      * <P>
124      * @return the Point where the drag originated in Component coords.
125      */
126 
127     public Point   getDragOrigin() {
128     return origin;
129     }
130 
131     /**
132      * Returns an <code>Iterator</code> for the events
133      * comprising the gesture.
134      * <P>
135      * @return an Iterator for the events comprising the gesture
136      */
137 
138     public Iterator  <InputEvent  > iterator() { return events.iterator(); }
139 
140     /**
141      * Returns an <code>Object</code> array of the 
142      * events comprising the drag gesture.
143      * <P>
144      * @return an array of the events comprising the gesture
145      */
146 
147     public Object  [] toArray() { return events.toArray(); }
148 
149     /**
150      * Returns an array of the events comprising the drag gesture.
151      * <P>
152      * @param array the array of <code>EventObject</code> sub(types)
153      * <P>
154      * @return an array of the events comprising the gesture
155      */
156 
157     public Object  [] toArray(Object  [] array) { return events.toArray(array); }
158 
159     /**
160      * Returns an <code>int</code> representing the 
161      * action selected by the user.
162      * <P>
163      * @return the action selected by the user
164      */
165 
166     public int getDragAction() { return action; }
167 
168     /**
169      * Returns the initial event that triggered the gesture. 
170      * <P>
171      * @return the first "triggering" event in the sequence of the gesture
172      */
173 
174     public InputEvent   getTriggerEvent() {
175     return getSourceAsDragGestureRecognizer().getTriggerEvent();
176     }
177 
178     /**
179      * Starts the drag operation given the <code>Cursor</code> for this drag
180      * operation and the <code>Transferable</code> representing the source data
181      * for this drag operation.
182      * <br>
183      * If a <code>null</code> <code>Cursor</code> is specified no exception will
184      * be thrown and default drag cursors will be used instead.
185      * <br>
186      * If a <code>null</code> <code>Transferable</code> is specified 
187      * <code>NullPointerException</code> will be thrown.
188      * 
189      * @param dragCursor   The <code>Cursor</code> for this drag operation 
190      * @param transferable The <code>Transferable</code> representing the source
191      *                     data for this drag operation.
192      *
193      * @throws <code>InvalidDnDOperationException</code> if the Drag and Drop
194      *         system is unable to initiate a drag operation, or if the user 
195      *         attempts to start a drag while an existing drag operation is
196      *         still executing. 
197      * @throws <code>NullPointerException</code> if the
198      *         <code>Transferable</code> is <code>null</code>.
199      * @since 1.4
200      */
201     public void startDrag(Cursor   dragCursor, Transferable   transferable) 
202       throws InvalidDnDOperationException   {
203         dragSource.startDrag(this, dragCursor, transferable, null);
204     }
205 
206     /**
207      * Starts the drag given the initial <code>Cursor</code> to display, 
208      * the <code>Transferable</code> object, 
209      * and the <code>DragSourceListener</code> to use.
210      * <P>
211      * @param dragCursor   The initial drag Cursor
212      * @param transferable The source's Transferable
213      * @param dsl      The source's DragSourceListener
214      * <P>
215      * @throws <code>InvalidDnDOperationException</code> if 
216      * the Drag and Drop system is unable to
217      * initiate a drag operation, or if the user 
218      * attempts to start a drag while an existing
219      * drag operation is still executing.
220      */
221 
222     public void startDrag(Cursor   dragCursor, Transferable   transferable, DragSourceListener   dsl) throws InvalidDnDOperationException   {
223     dragSource.startDrag(this, dragCursor, transferable, dsl);
224     }
225 
226     /**
227      * Start the drag given the initial <code>Cursor</code> to display,
228      * a drag <code>Image</code>, the offset of 
229      * the <code>Image</code>, 
230      * the <code>Transferable</code> object, and 
231      * the <code>DragSourceListener</code> to use.
232      * <P>
233      * @param dragCursor   The initial drag Cursor
234      * @param dragImage    The source's dragImage
235      * @param imageOffset  The dragImage's offset
236      * @param transferable The source's Transferable
237      * @param dsl      The source's DragSourceListener
238      * <P>
239      * @throws <code>InvalidDnDOperationException</code> if 
240      * the Drag and Drop system is unable to
241      * initiate a drag operation, or if the user 
242      * attempts to start a drag while an existing
243      * drag operation is still executing.
244      */
245 
246     public void startDrag(Cursor   dragCursor, Image   dragImage, Point   imageOffset, Transferable   transferable, DragSourceListener   dsl) throws InvalidDnDOperationException   {
247     dragSource.startDrag(this,  dragCursor, dragImage, imageOffset, transferable, dsl);
248     }
249 
250     /**
251      * Serializes this <code>DragGestureEvent</code>. Performs default
252      * serialization and then writes out this object's <code>List</code> of
253      * gesture events if and only if the <code>List</code> can be serialized.
254      * If not, <code>null</code> is written instead. In this case, a
255      * <code>DragGestureEvent</code> created from the resulting deserialized
256      * stream will contain an empty <code>List</code> of gesture events.
257      *
258      * @serialData The default serializable fields, in alphabetical order,
259      *             followed by either a <code>List</code> instance, or
260      *             <code>null</code>.
261      * @since 1.4
262      */
263     private void writeObject(ObjectOutputStream   s) throws IOException   {
264         s.defaultWriteObject();
265 
266         s.writeObject(SerializationTester.test(events) ? events : null);
267     }
268 
269     /**
270      * Deserializes this <code>DragGestureEvent</code>. This method first
271      * performs default deserialization for all non-<code>transient</code>
272      * fields. An attempt is then made to deserialize this object's
273      * <code>List</code> of gesture events as well. This is first attempted
274      * by deserializing the field <code>events</code>, because, in releases
275      * prior to 1.4, a non-<code>transient</code> field of this name stored the
276      * <code>List</code> of gesture events. If this fails, the next object in
277      * the stream is used instead. If the resulting <code>List</code> is
278      * <code>null</code>, this object's <code>List</code> of gesture events
279      * is set to an empty <code>List</code>.
280      *
281      * @since 1.4
282      */
283     private void readObject(ObjectInputStream   s)
284         throws ClassNotFoundException  , IOException  
285     {
286         ObjectInputStream.GetField   f = s.readFields();
287 
288         dragSource = (DragSource  )f.get("dragSource", null);
289         component = (Component  )f.get("component", null);
290         origin = (Point  )f.get("origin", null);
291         action = f.get("action", 0);
292 
293         // Pre-1.4 support. 'events' was previously non-transient
294         try {
295             events = (List  )f.get("events", null);
296         } catch (IllegalArgumentException   e) {
297             // 1.4-compatible byte stream. 'events' was written explicitly
298             events = (List  )s.readObject();
299         }
300 
301         // Implementation assumes 'events' is never null.
302         if (events == null) {
303             events = Collections.EMPTY_LIST;
304         }
305     }
306 
307     /*
308      * fields
309      */
310 
311     private transient List   events;
312 
313     /**
314      * The DragSource associated with this DragGestureEvent.
315      *
316      * @serial
317      */
318     private DragSource   dragSource;
319 
320     /**
321      * The Component associated with this DragGestureEvent.
322      *
323      * @serial
324      */
325     private Component    component;
326 
327     /**
328      * The origin of the drag.
329      *
330      * @serial
331      */
332     private Point        origin;
333 
334     /**
335      * The user's preferred action.
336      *
337      * @serial
338      */
339     private int        action;
340 }
341
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags