KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > dnd > 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 JavaDoc;
11 import java.awt.Component JavaDoc;
12 import java.awt.Point JavaDoc;
13
14 import java.util.TooManyListenersException JavaDoc;
15 import java.util.ArrayList JavaDoc;
16
17 import java.io.IOException JavaDoc;
18 import java.io.ObjectInputStream JavaDoc;
19 import java.io.ObjectOutputStream JavaDoc;
20 import java.io.Serializable JavaDoc;
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 JavaDoc {
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 JavaDoc ds, Component JavaDoc c, int sa, DragGestureListener JavaDoc dgl) {
102     super();
103
104     if (ds == null) throw new IllegalArgumentException JavaDoc("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 JavaDoc 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 JavaDoc ds, Component JavaDoc 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 JavaDoc ds, Component JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getTriggerEvent() { return events.isEmpty() ? null : (InputEvent JavaDoc)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 JavaDoc dgl) throws TooManyListenersException JavaDoc {
300     if (dragGestureListener != null)
301         throw new TooManyListenersException JavaDoc();
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 JavaDoc dgl) {
320     if (dragGestureListener == null || !dragGestureListener.equals(dgl))
321         throw new IllegalArgumentException JavaDoc();
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 JavaDoc p) {
337         try {
338             if (dragGestureListener != null) {
339                 dragGestureListener.dragGestureRecognized(new DragGestureEvent JavaDoc(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 JavaDoc 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 JavaDoc s) throws IOException JavaDoc {
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 JavaDoc s)
395         throws ClassNotFoundException JavaDoc, IOException JavaDoc
396     {
397         s.defaultReadObject();
398
399         dragGestureListener = (DragGestureListener JavaDoc)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 JavaDoc dragSource;
414  
415     /**
416      * The <code>Component</code>
417      * associated with this <code>DragGestureRecognizer</code>.
418      *
419      * @serial
420      */

421     protected Component JavaDoc component;
422
423     /**
424      * The <code>DragGestureListener</code>
425      * associated with this <code>DragGestureRecognizer</code>.
426      */

427     protected transient DragGestureListener JavaDoc 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 JavaDoc<InputEvent JavaDoc> events = new ArrayList JavaDoc<InputEvent JavaDoc>(1);
446 }
447
Popular Tags