DropTargetContext


1   /*
2    * @(#)DropTargetContext.java   1.37 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.Component  ;
11  
12  import java.awt.datatransfer.DataFlavor  ;
13  import java.awt.datatransfer.Transferable  ;
14  import java.awt.datatransfer.UnsupportedFlavorException  ;
15  
16  import java.awt.dnd.peer.DropTargetContextPeer;
17  
18  import java.io.IOException  ;
19  import java.io.Serializable  ;
20  
21  import java.util.Arrays  ;
22  import java.util.List  ;
23  
24  
25  /**
26   * A <code>DropTargetContext</code> is created 
27   * whenever the logical cursor associated
28   * with a Drag and Drop operation coincides with the visible geometry of
29   * a <code>Component</code> associated with a <code>DropTarget</code>.
30   * The <code>DropTargetContext</code> provides 
31   * the mechanism for a potential receiver
32   * of a drop operation to both provide the end user with the appropriate
33   * drag under feedback, but also to effect the subsequent data transfer
34   * if appropriate.
35   *
36   * @version     1.37, 05/05/04
37   * @since 1.2
38   */
39  
40  public class DropTargetContext implements Serializable   {
41  
42      private static final long serialVersionUID = -634158968993743371L;
43  
44      /**
45       * Construct a <code>DropTargetContext</code> 
46       * given a specified <code>DropTarget</code>.
47       * <P>
48       * @param dt the DropTarget to associate with
49       */
50  
51      DropTargetContext(DropTarget   dt) {
52      super();
53  
54      dropTarget = dt;
55      }
56  
57      /**
58       * This method returns the <code>DropTarget</code> associated with this
59       * <code>DropTargetContext</code>.
60       * <P>
61       * @return the <code>DropTarget</code> associated with this <code>DropTargetContext</code>
62       */
63  
64      public DropTarget   getDropTarget() { return dropTarget; }
65  
66      /**
67       * This method returns the <code>Component</code> associated with
68       * this <code>DropTargetContext</code>.
69       * <P>
70       * @return the Component associated with this Context
71       */
72  
73      public Component   getComponent() { return dropTarget.getComponent(); }
74  
75      /**
76       * Called when associated with the <code>DropTargetContextPeer</code>.
77       * <P>
78       * @param dtcp the <code>DropTargetContextPeer</code>
79       */
80  
81      public void addNotify(DropTargetContextPeer dtcp) {
82      dropTargetContextPeer = dtcp;
83      }
84  
85      /**
86       * Called when disassociated with the <code>DropTargetContextPeer</code>.
87       */
88  
89      public void removeNotify() {
90      dropTargetContextPeer = null;
91      transferable          = null;
92      }
93  
94      /**
95       * This method sets the current actions acceptable to 
96       * this <code>DropTarget</code>.
97       * <P>
98       * @param actions an <code>int</code> representing the supported action(s)
99       */
100 
101     protected void setTargetActions(int actions) {
102         DropTargetContextPeer peer = getDropTargetContextPeer();
103         if (peer != null) {
104             synchronized (peer) {
105                 peer.setTargetActions(actions);
106                 getDropTarget().doSetDefaultActions(actions);
107             }
108         } else {
109             getDropTarget().doSetDefaultActions(actions);
110         }
111     }
112 
113     /**
114      * This method returns an <code>int</code> representing the 
115      * current actions this <code>DropTarget</code> will accept.
116      * <P>
117      * @return the current actions acceptable to this <code>DropTarget</code>
118      */
119 
120     protected int getTargetActions() {
121         DropTargetContextPeer peer = getDropTargetContextPeer();
122         return ((peer != null)
123             ? peer.getTargetActions() 
124             : dropTarget.getDefaultActions()
125     );
126     }
127 
128     /**
129      * This method signals that the drop is completed and 
130      * if it was successful or not.
131      * <P>
132      * @param success true for success, false if not
133      * <P>
134      * @throws InvalidDnDOperationException if a drop is not outstanding/extant
135      */
136 
137     public void dropComplete(boolean success) throws InvalidDnDOperationException  {
138         DropTargetContextPeer peer = getDropTargetContextPeer();
139         if (peer != null) {
140         peer.dropComplete(success);
141         }
142     }
143 
144     /**
145      * accept the Drag.
146      * <P>
147      * @param dragOperation the supported action(s)
148      */
149 
150     protected void acceptDrag(int dragOperation) {
151         DropTargetContextPeer peer = getDropTargetContextPeer();
152         if (peer != null) {
153             peer.acceptDrag(dragOperation);
154         }
155     }
156 
157     /**
158      * reject the Drag.
159      */
160 
161     protected void rejectDrag() {
162         DropTargetContextPeer peer = getDropTargetContextPeer();
163         if (peer != null) {
164             peer.rejectDrag();
165         }
166     }
167 
168     /**
169      * called to signal that the drop is acceptable
170      * using the specified operation.
171      * must be called during DropTargetListener.drop method invocation.
172      * <P>
173      * @param dropOperation the supported action(s)
174      */
175 
176     protected void acceptDrop(int dropOperation) {
177         DropTargetContextPeer peer = getDropTargetContextPeer();
178         if (peer != null) {
179             peer.acceptDrop(dropOperation);
180         }
181     }
182 
183     /**
184      * called to signal that the drop is unacceptable.
185      * must be called during DropTargetListener.drop method invocation.
186      */
187 
188     protected void rejectDrop() {
189         DropTargetContextPeer peer = getDropTargetContextPeer();
190         if (peer != null) {
191             peer.rejectDrop();
192         }
193     }
194 
195     /**
196      * get the available DataFlavors of the 
197      * <code>Transferable</code> operand of this operation.
198      * <P>
199      * @return a <code>DataFlavor[]</code> containing the
200      * supported <code>DataFlavor</code>s of the 
201      * <code>Transferable</code> operand.
202      */
203 
204     protected DataFlavor  [] getCurrentDataFlavors() {
205         DropTargetContextPeer peer = getDropTargetContextPeer();
206         return peer != null ? peer.getTransferDataFlavors() : new DataFlavor  [0];
207     }
208 
209     /** 
210      * This method returns a the currently available DataFlavors 
211      * of the <code>Transferable</code> operand
212      * as a <code>java.util.List</code>.
213      * <P>
214      * @return the currently available 
215      * DataFlavors as a <code>java.util.List</code>
216      */
217 
218     protected List  <DataFlavor  > getCurrentDataFlavorsAsList() {
219     return Arrays.asList(getCurrentDataFlavors());
220     }
221 
222     /**
223      * This method returns a <code>boolean</code> 
224      * indicating if the given <code>DataFlavor</code> is
225      * supported by this <code>DropTargetContext</code>.
226      * <P>
227      * @param df the <code>DataFlavor</code>
228      * <P>
229      * @return if the <code>DataFlavor</code> specified is supported
230      */
231 
232     protected boolean isDataFlavorSupported(DataFlavor   df) {
233     return getCurrentDataFlavorsAsList().contains(df);
234     }
235 
236     /**
237      * get the Transferable (proxy) operand of this operation
238      * <P>
239      * @throws InvalidDnDOperationException if a drag is not outstanding/extant
240      * <P>
241      * @return the <code>Transferable</code>
242      */
243 
244     protected Transferable   getTransferable() throws InvalidDnDOperationException   {
245         DropTargetContextPeer peer = getDropTargetContextPeer();
246         if (peer == null) {
247         throw new InvalidDnDOperationException  ();
248     } else {
249             if (transferable == null) {
250                 Transferable   t = peer.getTransferable();
251                 boolean isLocal = peer.isTransferableJVMLocal();
252                 synchronized (this) {
253                     if (transferable == null) {
254                         transferable = createTransferableProxy(t, isLocal);
255                     }
256                 }
257         }
258 
259         return transferable;
260     }
261     }
262 
263     /**
264      * Get the <code>DropTargetContextPeer</code>
265      * <P>
266      * @return the platform peer
267      */
268 
269     DropTargetContextPeer getDropTargetContextPeer() { 
270     return dropTargetContextPeer;
271     }
272 
273     /**
274      * Creates a TransferableProxy to proxy for the specified
275      * Transferable.
276      * 
277      * @param t the <tt>Transferable</tt> to be proxied
278      * @param local <tt>true</tt> if <tt>t</tt> represents
279      *        the result of a local drag-n-drop operation.
280      * @return the new <tt>TransferableProxy</tt> instance.   
281      */
282     protected Transferable   createTransferableProxy(Transferable   t, boolean local) {
283     return new TransferableProxy(t, local);
284     }
285 
286 /****************************************************************************/
287 
288   
289     /**
290      * <code>TransferableProxy</code> is a helper inner class that implements
291      * <code>Transferable</code> interface and serves as a proxy for another 
292      * <code>Transferable</code> object which represents data transfer for
293      * a particular drag-n-drop operation.
294      * <p>
295      * The proxy forwards all requests to the encapsulated transferable 
296      * and automatically performs additional conversion on the data 
297      * returned by the encapsulated transferable in case of local transfer.
298      */
299 
300     protected class TransferableProxy implements Transferable   {
301 
302     /**
303          * Constructs a <code>TransferableProxy</code> given 
304          * a specified <code>Transferable</code> object representing
305          * data transfer for a particular drag-n-drop operation and 
306          * a <code>boolean</code> which indicates whether the 
307          * drag-n-drop operation is local (within the same JVM).
308          * <p>
309          * @param t the <code>Transferable</code> object
310          * @param local <code>true</code>, if <code>t</code> represents
311          *        the result of local drag-n-drop operation
312          */
313     TransferableProxy(Transferable   t, boolean local) {
314         proxy = new sun.awt.datatransfer.TransferableProxy(t, local);
315         transferable = t;
316         isLocal  = local;
317     }
318 
319     /** 
320          * Returns an array of DataFlavor objects indicating the flavors 
321          * the data can be provided in by the encapsulated transferable.
322          * <p>
323          * @return an array of data flavors in which the data can be 
324          *         provided by the encapsulated transferable
325          */
326         public DataFlavor  [] getTransferDataFlavors() {
327         return proxy.getTransferDataFlavors();
328     }
329 
330     /**
331          * Returns whether or not the specified data flavor is supported by
332          * the encapsulated transferable.
333          * @param flavor the requested flavor for the data
334          * @return <code>true</code> if the data flavor is supported,
335          *         <code>false</code> otherwise
336          */
337         public boolean isDataFlavorSupported(DataFlavor   flavor) {
338         return proxy.isDataFlavorSupported(flavor);
339     }
340 
341         /**
342          * Returns an object which represents the data provided by 
343          * the encapsulated transferable for the requested data flavor.
344          * <p>
345          * In case of local transfer a serialized copy of the object
346          * returned by the encapsulated transferable is provided when 
347          * the data is requested in application/x-java-serialized-object 
348          * data flavor.
349          *
350          * @param df the requested flavor for the data
351          * @throws IOException if the data is no longer available
352          *              in the requested flavor.
353          * @throws UnsupportedFlavorException if the requested data flavor is
354          *              not supported.
355          */
356         public Object   getTransferData(DataFlavor   df)
357         throws UnsupportedFlavorException  , IOException  
358     {
359         return proxy.getTransferData(df);
360     }
361 
362     /*
363      * fields
364      */
365 
366     // We don't need to worry about client code changing the values of
367     // these variables. Since TransferableProxy is a protected class, only
368     // subclasses of DropTargetContext can access it. And DropTargetContext
369     // cannot be subclassed by client code because it does not have a
370     // public constructor.
371 
372         /**
373          * The encapsulated <code>Transferable</code> object.
374          */
375     protected Transferable    transferable;
376 
377         /**
378          * A <code>boolean</code> indicating if the encapsulated 
379          * <code>Transferable</code> object represents the result
380          * of local drag-n-drop operation (within the same JVM).
381          */
382     protected boolean   isLocal;
383 
384     private sun.awt.datatransfer.TransferableProxy proxy;
385     }
386 
387 /****************************************************************************/
388 
389     /*
390      * fields
391      */
392 
393     /**
394      * The DropTarget associated with this DropTargetContext.
395      *
396      * @serial
397      */
398     private DropTarget   dropTarget;
399 
400     private transient DropTargetContextPeer dropTargetContextPeer;
401 
402     private transient Transferable   transferable;
403 }
404
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags