DragGestureRecognizer


1   /*
2    * @(#)DragGestureRecognizer.java   1.20 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   package java.awt.dnd;
9   
10  import java.awt.event.InputEvent  ;
11  import java.awt.Component  ;
12  import java.awt.Point  ;
13  
14  import java.util.TooManyListenersException  ;
15  import java.util.ArrayList  ;
16  
17  import java.io.IOException  ;
18  import java.io.ObjectInputStream  ;
19  import java.io.ObjectOutputStream  ;
20  import java.io.Serializable  ;
21  
22  /**
23   * The <code>DragGestureRecognizer</code> is an 
24   * abstract base class for the specification
25   * of a platform-dependent listener that can be associated with a particular
26   * <code>Component</code> in order to 
27   * identify platform-dependent drag initiating gestures.
28   * <p>
29   * The appropriate <code>DragGestureRecognizer</code>
30   * subclass is obtained from the
31   * <code>DragSource</code> asssociated with 
32   * a particular <code>Component</code>, or from the <code>Toolkit</code>
33   * object via its createDragGestureRecognizer() method.
34   * <p>
35   * Once the <code>DragGestureRecognizer</code> 
36   * is associated with a particular <code>Component</code>
37   * it will register the appropriate listener interfaces on that 
38   * <code>Component</code>
39   * in order to track the input events delivered to the <code>Component</code>.
40   * <p>
41   * Once the <code>DragGestureRecognizer</code> identifies a sequence of events
42   * on the <code>Component</code> as a drag initiating gesture, it will notify
43   * its unicast <code>DragGestureListener</code> by 
44   * invoking its gestureRecognized() method.
45   * <P>
46   * When a concrete <code>DragGestureRecognizer</code> 
47   * instance detects a drag initiating
48   * gesture on the <code>Component</code> it is associated with,
49   * it will fire a <code>DragGestureEvent</code> to 
50   * the <code>DragGestureListener</code> registered on
51   * its unicast event source for <code>DragGestureListener</code>
52   * events. This <code>DragGestureListener</code> is responsible 
53   * for causing the associated
54   * <code>DragSource</code> to start the Drag and Drop operation (if
55   * appropriate). 
56   * <P>
57   * @author Laurence P. G. Cable
58   * @version 1.20
59   * @see java.awt.dnd.DragGestureListener
60   * @see java.awt.dnd.DragGestureEvent
61   * @see java.awt.dnd.DragSource
62   */
63  
64  public abstract class DragGestureRecognizer implements Serializable   {
65  
66      private static final long serialVersionUID = 8996673345831063337L;
67  
68      /**
69       * Construct a new <code>DragGestureRecognizer</code> 
70       * given the <code>DragSource</code> to be used 
71       * in this Drag and Drop operation, the <code>Component</code> 
72       * this <code>DragGestureRecognizer</code> should "observe" 
73       * for drag initiating gestures, the action(s) supported 
74       * for this Drag and Drop operation, and the 
75       * <code>DragGestureListener</code> to notify
76       * once a drag initiating gesture has been detected.
77       * <P>
78       * @param ds  the <code>DragSource</code> this 
79       * <code>DragGestureRecognizer</code> 
80       * will use to process the Drag and Drop operation
81       *
82       * @param c the <code>Component</code> 
83       * this <code>DragGestureRecognizer</code> 
84       * should "observe" the event stream to, 
85       * in order to detect a drag initiating gesture.
86       * If this value is <code>null</code>, the 
87       * <code>DragGestureRecognizer</code>
88       * is not associated with any <code>Component</code>.
89       *
90       * @param sa  the set (logical OR) of the 
91       * <code>DnDConstants</code> 
92       * that this Drag and Drop operation will support
93       *
94       * @param dgl the <code>DragGestureRecognizer</code> 
95       * to notify when a drag gesture is detected
96       * <P>
97       * @throws <code>IllegalArgumentException</code> 
98       * if ds is <code>null</code>.
99       */
100 
101     protected DragGestureRecognizer(DragSource   ds, Component   c, int sa, DragGestureListener   dgl) {
102     super();
103 
104     if (ds == null) throw new IllegalArgumentException  ("null DragSource");
105 
106     dragSource    = ds;
107     component     = c;
108     sourceActions = sa & (DnDConstants.ACTION_COPY_OR_MOVE | DnDConstants.ACTION_LINK);
109 
110     try {
111         if (dgl != null) addDragGestureListener(dgl);
112     } catch (TooManyListenersException   tmle) {
113         // cant happen ...
114     }
115     }
116 
117     /**
118      * Construct a new <code>DragGestureRecognizer</code> 
119      * given the <code>DragSource</code> to be used in this 
120      * Drag and Drop
121      * operation, the <code>Component</code> this 
122      * <code>DragGestureRecognizer</code> should "observe" 
123      * for drag initiating gestures, and the action(s) 
124      * supported for this Drag and Drop operation.
125      * <P>
126      * @param ds  the <code>DragSource</code> this 
127      * <code>DragGestureRecognizer</code> will use to 
128      * process the Drag and Drop operation
129      *
130      * @param c   the <code>Component</code> this 
131      * <code>DragGestureRecognizer</code> should "observe" the event 
132      * stream to, in order to detect a drag initiating gesture.
133      * If this value is <code>null</code>, the 
134      * <code>DragGestureRecognizer</code>
135      * is not associated with any <code>Component</code>.
136      *
137      * @param sa the set (logical OR) of the <code>DnDConstants</code> 
138      * that this Drag and Drop operation will support
139      * <P>
140      * @throws <code>IllegalArgumentException</code> 
141      * if ds is <code>null</code>.
142      */
143 
144     protected DragGestureRecognizer(DragSource   ds, Component   c, int sa) {
145     this(ds, c, sa, null);
146     }
147 
148     /**
149      * Construct a new <code>DragGestureRecognizer</code> 
150      * given the <code>DragSource</code> to be used 
151      * in this Drag and Drop operation, and 
152      * the <code>Component</code> this 
153      * <code>DragGestureRecognizer</code> 
154      * should "observe" for drag initiating gestures.
155      * <P>
156      * @param ds the <code>DragSource</code> this 
157      * <code>DragGestureRecognizer</code> 
158      * will use to process the Drag and Drop operation
159      *
160      * @param c the <code>Component</code> 
161      * this <code>DragGestureRecognizer</code> 
162      * should "observe" the event stream to, 
163      * in order to detect a drag initiating gesture.
164      * If this value is <code>null</code>, 
165      * the <code>DragGestureRecognizer</code>
166      * is not associated with any <code>Component</code>.
167      * <P>
168      * @throws <code>IllegalArgumentException</code> 
169      * if ds is <code>null</code>.
170      */
171 
172     protected DragGestureRecognizer(DragSource   ds, Component   c) {
173     this(ds, c, DnDConstants.ACTION_NONE);
174     }
175 
176     /**
177      * Construct a new <code>DragGestureRecognizer</code> 
178      * given the <code>DragSource</code> to be used in this 
179      * Drag and Drop operation.
180      * <P>
181      * @param ds the <code>DragSource</code> this 
182      * <code>DragGestureRecognizer</code> will 
183      * use to process the Drag and Drop operation
184      * <P>
185      * @throws <code>IllegalArgumentException</code> 
186      * if ds is <code>null</code>.
187      */
188 
189     protected DragGestureRecognizer(DragSource   ds) {
190     this(ds, null);
191     }
192 
193     /**
194      * register this DragGestureRecognizer's Listeners with the Component
195      *
196      * subclasses must override this method
197      */
198 
199     protected abstract void registerListeners();
200 
201     /**
202      * unregister this DragGestureRecognizer's Listeners with the Component
203      *
204      * subclasses must override this method
205      */
206 
207     protected abstract void unregisterListeners();
208 
209     /**
210      * This method returns the <code>DragSource</code> 
211      * this <code>DragGestureRecognizer</code> 
212      * will use in order to process the Drag and Drop 
213      * operation.
214      * <P>
215      * @return the DragSource
216      */
217 
218     public DragSource   getDragSource() { return dragSource; }
219 
220     /**
221      * This method returns the <code>Component</code> 
222      * that is to be "observed" by the 
223      * <code>DragGestureRecognizer</code> 
224      * for drag initiating gestures.
225      * <P>
226      * @return The Component this DragGestureRecognizer 
227      * is associated with
228      */
229 
230     public synchronized Component   getComponent() { return component; }
231 
232     /**
233      * set the Component that the DragGestureRecognizer is associated with
234      *
235      * registerListeners() and unregisterListeners() are called as a side
236      * effect as appropriate.
237      * <P>
238      * @param c The <code>Component</code> or <code>null</code>
239      */
240 
241     public synchronized void setComponent(Component   c) {
242     if (component != null && dragGestureListener != null)
243         unregisterListeners();
244 
245     component = c;
246 
247     if (component != null && dragGestureListener != null)
248         registerListeners();
249     }
250 
251     /**
252      * This method returns an int representing the 
253      * type of action(s) this Drag and Drop 
254      * operation will support.
255      * <P>
256      * @return the currently permitted source action(s)
257      */
258 
259     public synchronized int getSourceActions() { return sourceActions; }
260 
261     /**
262      * This method sets the permitted source drag action(s) 
263      * for this Drag and Drop operation.
264      * <P>
265      * @param actions the permitted source drag action(s)
266      */
267 
268     public synchronized void setSourceActions(int actions) {
269     sourceActions = actions & (DnDConstants.ACTION_COPY_OR_MOVE | DnDConstants.ACTION_LINK);
270     }
271 
272     /**
273      * This method returns the first event in the 
274      * series of events that initiated 
275      * the Drag and Drop operation.
276      * <P>
277      * @return the initial event that triggered the drag gesture
278      */
279 
280     public InputEvent   getTriggerEvent() { return events.isEmpty() ? null : (InputEvent  )events.get(0); }
281 
282     /**
283      * Reset the Recognizer, if its currently recognizing a gesture, ignore
284      * it.
285      */
286 
287     public void resetRecognizer() { events.clear(); }
288 
289     /**
290      * Register a new <code>DragGestureListener</code>.
291      * <P>
292      * @param dgl the <code>DragGestureListener</code> to register 
293      * with this <code>DragGestureRecognizer</code>.
294      * <P>
295      * @throws java.util.TooManyListenersException if a 
296      * <code>DragGestureListener</code> has already been added.
297      */
298 
299     public synchronized void addDragGestureListener(DragGestureListener   dgl) throws TooManyListenersException   {
300     if (dragGestureListener != null)
301         throw new TooManyListenersException  ();
302     else {
303         dragGestureListener = dgl;
304 
305         if (component != null) registerListeners();
306     }
307     }
308 
309     /**
310      * unregister the current DragGestureListener
311      * <P>
312      * @param dgl the <code>DragGestureListener</code> to unregister 
313      * from this <code>DragGestureRecognizer</code>
314      * <P>
315      * @throws <code>IllegalArgumentException</code> if 
316      * dgl is not (equal to) the currently registered <code>DragGestureListener</code>.
317      */
318 
319     public synchronized void removeDragGestureListener(DragGestureListener   dgl) {
320     if (dragGestureListener == null || !dragGestureListener.equals(dgl))
321         throw new IllegalArgumentException  ();
322     else {
323         dragGestureListener = null;
324 
325         if (component != null) unregisterListeners();
326     }
327     }
328 
329     /**
330      * Notify the DragGestureListener that a Drag and Drop initiating
331      * gesture has occurred. Then reset the state of the Recognizer.
332      * <P>
333      * @param dragAction The action initially selected by the users gesture
334      * @param p          The point (in Component coords) where the gesture originated
335      */
336     protected synchronized void fireDragGestureRecognized(int dragAction, Point   p) {
337         try {
338             if (dragGestureListener != null) {
339                 dragGestureListener.dragGestureRecognized(new DragGestureEvent  (this, dragAction, p, events));
340             }
341         } finally {
342             events.clear();
343         }
344     }
345 
346     /**
347      * Listeners registered on the Component by this Recognizer shall record
348      * all Events that are recognized as part of the series of Events that go
349      * to comprise a Drag and Drop initiating gesture via this API.
350      *<P>
351      * This method is used by a <code>DragGestureRecognizer</code> 
352      * implementation to add an <code>InputEvent</code> 
353      * subclass (that it believes is one in a series
354      * of events that comprise a Drag and Drop operation) 
355      * to the array of events that this 
356      * <code>DragGestureRecognizer</code> maintains internally.
357      * <P>
358      * @param awtie the <code>InputEvent</code> 
359      * to add to this <code>DragGestureRecognizer</code>'s 
360      * internal array of events. Note that <code>null</code>
361      * is not a valid value, and will be ignored.
362      */
363 
364     protected synchronized void appendEvent(InputEvent   awtie) {
365     events.add(awtie);
366     }
367 
368     /**
369      * Serializes this <code>DragGestureRecognizer</code>. This method first
370      * performs default serialization. Then, this object's
371      * <code>DragGestureListener</code> is written out if and only if it can be
372      * serialized. If not, <code>null</code> is written instead.
373      *
374      * @serialData The default serializable fields, in alphabetical order,
375      *             followed by either a <code>DragGestureListener</code>, or
376      *             <code>null</code>.
377      * @since 1.4
378      */
379     private void writeObject(ObjectOutputStream   s) throws IOException   {
380         s.defaultWriteObject();
381 
382         s.writeObject(SerializationTester.test(dragGestureListener)
383                       ? dragGestureListener : null);
384     }
385 
386     /**
387      * Deserializes this <code>DragGestureRecognizer</code>. This method first
388      * performs default deserialization for all non-<code>transient</code>
389      * fields. This object's <code>DragGestureListener</code> is then
390      * deserialized as well by using the next object in the stream.
391      *
392      * @since 1.4
393      */
394     private void readObject(ObjectInputStream   s)
395         throws ClassNotFoundException  , IOException  
396     {
397         s.defaultReadObject();
398 
399         dragGestureListener = (DragGestureListener  )s.readObject();
400     }
401 
402     /*
403      * fields
404      */
405 
406     /**
407      * The <code>DragSource</code> 
408      * associated with this 
409      * <code>DragGestureRecognizer</code>.
410      *
411      * @serial
412      */
413     protected DragSource            dragSource;
414  
415     /**
416      * The <code>Component</code> 
417      * associated with this <code>DragGestureRecognizer</code>.
418      *
419      * @serial
420      */
421     protected Component             component;
422 
423     /**
424      * The <code>DragGestureListener</code> 
425      * associated with this <code>DragGestureRecognizer</code>.
426      */
427     protected transient DragGestureListener   dragGestureListener;
428 
429   /**
430    * An <code>int</code> representing 
431    * the type(s) of action(s) used 
432    * in this Drag and Drop operation.  
433    *
434    * @serial
435    */
436   protected int  sourceActions;
437 
438    /**
439     * The list of events (in order) that 
440     * the <code>DragGestureRecognizer</code> 
441     * "recognized" as a "gesture" that triggers a drag.
442     *
443     * @serial
444     */
445    protected ArrayList  <InputEvent  > events = new ArrayList  <InputEvent  >(1);
446 }
447
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags