ExClipboard


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  package org.openide.util.datatransfer;
20  
21  import java.awt.datatransfer.*;
22  
23  import javax.swing.event.EventListenerList  ;
24  
25  
26  // and holding a list of services built over data flavors. [???]
27  
28  /** Extended clipboard that supports listeners that can be notified about
29  * changes of content. Also contains support for attaching content convertors.
30  *
31  * @author Jaroslav Tulach
32  */
33  public abstract class ExClipboard extends Clipboard {
34      /** listeners */
35      private EventListenerList   listeners = new EventListenerList  ();
36  
37      /** Make a new clipboard.
38      * @param name name of the clipboard
39      */
40      public ExClipboard(String   name) {
41          super(name);
42      }
43  
44      /** Add a listener to clipboard operations.
45      * @param list the listener
46      */
47      public final void addClipboardListener(ClipboardListener list) {
48          listeners.add(ClipboardListener.class, list);
49      }
50  
51      /** Remove a listener to clipboard operations.
52      * @param list the listener
53      */
54      public final void removeClipboardListener(ClipboardListener list) {
55          listeners.remove(ClipboardListener.class, list);
56      }
57  
58      /** Fires event about change of content in the clipboard.
59      */
60      protected final void fireClipboardChange() {
61          Object  [] l = listeners.getListenerList();
62          ClipboardEvent ev = null;
63  
64          for (int i = l.length - 2; i >= 0; i -= 2) {
65              ClipboardListener list = (ClipboardListener) l[i + 1];
66  
67              if (ev == null) {
68                  ev = new ClipboardEvent(this);
69              }
70  
71              list.clipboardChanged(ev);
72          }
73      }
74  
75      /** Obtain a list of convertors assigned to
76      * this clipboard.
77      * @return the convertors
78      */
79      protected abstract Convertor[] getConvertors();
80  
81      /** Method that takes a transferable, applies all convertors,
82      * and creates a new transferable using the abilities of the
83      * convertors.
84      * <P>
85      * This method is used when the contents of the clipboard are changed and
86      * also can be used by Drag &amp; Drop to process transferables between source
87      * and target.
88      * <p>
89      * Note that it is possible for the results to vary according to order
90      * of the convertors as specified by {@link #getConvertors}. For example,
91      * the input transferable may contain flavor A, and there may be a convertor
92      * from A to B, and one from B to C; flavor B will always be available, but
93      * flavor C will only be available if the convertor list is in the order
94      * that these were mentioned. Since the standard clipboard implementation
95      * searches for convertors in lookup as well as manifests, ordering might be
96      * specified between a set of layer-supplied convertors by means of folder
97      * ordering attributes.
98      *
99      * @param t input transferable
100     * @return new transferable
101     */
102     public Transferable convert(Transferable t) {
103         Convertor[] convertors = getConvertors();
104 
105         for (int i = 0; i < convertors.length; i++) {
106             if (t == null) {
107                 return null;
108             }
109 
110             t = convertors[i].convert(t);
111         }
112 
113         return t;
114     }
115 
116     /** Notifies the transferable that it has been accepted by a drop.
117     * Works only for ExTransferable, other types of transferables are
118     * not notified.
119     *
120     * @param t transferable to notify its listeners
121     * @param action which action has been performed
122     */
123     public static void transferableAccepted(Transferable t, int action) {
124         if (t instanceof ExTransferable) {
125             ((ExTransferable) t).fireAccepted(action);
126         } else if (t.isDataFlavorSupported(ExTransferable.multiFlavor)) {
127             try {
128                 MultiTransferObject mto = (MultiTransferObject) t.getTransferData(ExTransferable.multiFlavor);
129                 int cnt = mto.getCount();
130 
131                 for (int i = 0; i < cnt; i++) {
132                     transferableAccepted(mto.getTransferableAt(i), action);
133                 }
134             } catch (Exception   e) {
135                 // shouldn't occure
136             }
137         }
138     }
139 
140     /** Notifies the transferable that it has been rejected by a drop.
141     * Works only for ExTransferable, other types of transferables are
142     * not notified.
143     *
144     * @param t transferable to notify its listeners
145     */
146     public static void transferableRejected(Transferable t) {
147         if (t instanceof ExTransferable) {
148             ((ExTransferable) t).fireRejected();
149         } else if (t.isDataFlavorSupported(ExTransferable.multiFlavor)) {
150             try {
151                 MultiTransferObject mto = (MultiTransferObject) t.getTransferData(ExTransferable.multiFlavor);
152                 int cnt = mto.getCount();
153 
154                 for (int i = 0; i < cnt; i++) {
155                     transferableRejected(mto.getTransferableAt(i));
156                 }
157             } catch (Exception   e) {
158                 // shouldn't occure
159             }
160         }
161     }
162 
163     public synchronized void setContents(Transferable contents, ClipboardOwner owner) {
164         if (this.contents != null) {
165             transferableOwnershipLost(this.contents);
166         }
167 
168         super.setContents(contents, owner);
169     }
170 
171     /** Notifies the transferable that it has lost ownership in clipboard.
172     * Works only for ExTransferable, other types of transferables are
173     * not notified.
174     *
175     * @param t transferable to notify its listeners
176     */
177     public static void transferableOwnershipLost(Transferable t) {
178         if (t instanceof ExTransferable) {
179             ((ExTransferable) t).fireOwnershipLost();
180         } else if (t.isDataFlavorSupported(ExTransferable.multiFlavor)) {
181             try {
182                 MultiTransferObject mto = (MultiTransferObject) t.getTransferData(ExTransferable.multiFlavor);
183                 int cnt = mto.getCount();
184 
185                 for (int i = 0; i < cnt; i++) {
186                     transferableOwnershipLost(mto.getTransferableAt(i));
187                 }
188             } catch (Exception   e) {
189                 // shouldn't occure
190             }
191         }
192     }
193 
194     /** Convertor that can convert the {@link Transferable contents} of a clipboard to
195     * additional {@link DataFlavor flavors}.
196     */
197     public interface Convertor {
198         /** Convert a given transferable to a new transferable,
199         * generally one which adds new flavors based on the existing flavors.
200         * The recommended usage is as follows:
201         *
202         * <br><code><pre>
203         * public Transferable convert (final Transferable t) {
204         *   if (! t.isDataFlavorSupported (fromFlavor)) return t;
205         *   if (t.isDataFlavorSupported (toFlavor)) return t;
206         *   ExTransferable et = ExTransferable.create (t);
207         *   et.put (new ExTransferable.Single (toFlavor) {
208         *     public Object getData () throws IOException, UnsupportedFlavorException {
209         *       FromObject from = (FromObject) t.getTransferData (fromFlavor);
210         *       ToObject to = translateFormats (from);
211         *       return to;
212         *     }
213         *   });
214         *   return et;
215         * }
216         * </pre></code>
217         *
218         * <br>Note that this does not perform the conversion until <code>toFlavor</code> is
219         * actually requested, nor does it advertise <code>toFlavor</code> as being available
220         * unless <code>fromFlavor</code> already was.
221         *
222         * <p>You may also want to convert some flavor to a node selection, in which case you should do:
223         *
224         * <br><code><pre>
225         * public Transferable convert (final Transferable t) {
226         *   if (! t.isDataFlavorSupported (DataFlavor.stringFlavor)) return t;
227         *   if (NodeTransfer.findPaste (t) != null) return t;
228         *   ExTransferable et = ExTransferable.create (t);
229         *   et.put (NodeTransfer.createPaste (new NodeTransfer.Paste () {
230         *     public PasteType[] types (Node target) {
231         *       if (isSuitable (target)) {
232         *         return new PasteType[] { new PasteType () {
233         *           public Transferable paste () throws IOException {
234         *             try {
235         *               String s = (String) t.getTransferData (DataFlavor.stringFlavor);
236         *               addNewSubnode (target, s);
237         *             } catch (UnsupportedFlavorException ufe) {
238         *               throw new IOException (ufe.toString ());
239         *             }
240         *             return t;
241         *           }
242         *         }};
243         *       } else {
244         *         return new PasteType[0];
245         *       }
246         *     }
247         *   }));
248         *   return et;
249         * }
250         * </pre></code>
251         *
252         * <p>Convertors should generally avoid removing flavors from the transferable,
253         * or changing the data for an existing flavor.
254         *
255         * @param t the incoming basic transferable
256         * @return a possible enhanced transferable
257         */
258         public Transferable convert(Transferable t);
259     }
260 }
261
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags