org.eclipse.swt.dnd.Transfer source code

1 /*******************************************************************************
2  * Copyright (c) 2000, 2008 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  *     IBM Corporation - initial API and implementation
10  * Port to the D programming language:
11  *     Frank Benoit <benoit@tionex.de>
12  *******************************************************************************/
13 module org.eclipse.swt.dnd.Transfer;
14 
15 import java.lang.all;
16 
17 
18 import org.eclipse.swt.internal.Converter;
19 import org.eclipse.swt.internal.gtk.OS;
20 import org.eclipse.swt.dnd.TransferData;
21 
22 
23 /**
24  * <code>Transfer</code> provides a mechanism for converting between a java
25  * representation of data and a platform specific representation of data and
26  * vice versa.  It is used in data transfer operations such as drag and drop and
27  * clipboard copy/paste.
28  *
29  * <p>You should only need to become familiar with this class if you are
30  * implementing a Transfer subclass and you are unable to subclass the
31  * ByteArrayTransfer class.</p>
32  *
33  * @see ByteArrayTransfer
34  * @see <a href="http://www.eclipse.org/swt/snippets/#dnd">Drag and Drop snippets</a>
35  * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: DNDExample</a>
36  * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
37  */
38 public abstract class Transfer {
39 
40 /**
41  * Returns a list of the platform specific data types that can be converted using
42  * this transfer agent.
43  *
44  * <p>Only the data type fields of the <code>TransferData</code> objects are filled
45  * in.</p>
46  *
47  * @return a list of the data types that can be converted using this transfer agent
48  */
49 abstract public TransferData[] getSupportedTypes();
50 
51 /**
52  * Returns true if the <code>TransferData</code> data type can be converted
53  * using this transfer agent, or false otherwise (including if transferData is
54  * <code>null</code>).
55  *
56  * @param transferData a platform specific description of a data type; only the data
57  *  type fields of the <code>TransferData</code> object need to be filled in
58  *
59  * @return true if the transferData data type can be converted using this transfer
60  * agent
61  */
62 abstract public bool isSupportedType(TransferData transferData);
63 
64 /**
65  * Returns the platform specific names of the  data types that can be converted
66  * using this transfer agent.
67  *
68  * @return the platform specific names of the data types that can be converted
69  * using this transfer agent.
70  */
71 abstract public String[] getTypeNames();
72 
73 /**
74  * Returns the platform specific ids of the  data types that can be converted using
75  * this transfer agent.
76  *
77  * @return the platform specific ids of the data types that can be converted using
78  * this transfer agent
79  */
80 abstract public int[] getTypeIds();
81 
82 /**
83  * Converts a java representation of data to a platform specific representation of
84  * the data.
85  *
86  * <p>On a successful conversion, the transferData.result field will be set as follows:
87  * <ul>
88  * <li>Windows: COM.S_OK
89  * <li>Motif: 1
90  * <li>GTK: 1
91  * <li>Photon: 1
92  * </ul></p>
93  *
94  * <p>If this transfer agent is unable to perform the conversion, the transferData.result
95  * field will be set to a failure value as follows:
96  * <ul>
97  * <li>Windows: COM.DV_E_TYMED or COM.E_FAIL
98  * <li>Motif: 0
99  * <li>GTK: 0
100  * <li>Photon: 0
101  * </ul></p>
102  *
103  * @param object a java representation of the data to be converted; the type of
104  * Object that is passed in is dependent on the <code>Transfer</code> subclass.
105  *
106  * @param transferData an empty TransferData object; this object will be
107  * filled in on return with the platform specific representation of the data
108  *
109  * @exception org.eclipse.swt.SWTException <ul>
110  *    <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
111  * </ul>
112  */
113 abstract public void javaToNative (Object object, TransferData transferData);
114 
115 /**
116  * Converts a platform specific representation of data to a java representation.
117  *
118  * @param transferData the platform specific representation of the data to be
119  * converted
120  *
121  * @return a java representation of the converted data if the conversion was
122  * successful; otherwise null.  If transferData is <code>null</code> then
123  * <code>null</code> is returned.  The type of Object that is returned is
124  * dependent on the <code>Transfer</code> subclass.
125  */
126 abstract public Object nativeToJava(TransferData transferData);
127 
128 /**
129  * Registers a name for a data type and returns the associated unique identifier.
130  *
131  * <p>You may register the same type more than once, the same unique identifier
132  * will be returned if the type has been previously registered.</p>
133  *
134  * <p>Note: On windows, do <b>not</b> call this method with pre-defined
135  * Clipboard Format types such as CF_TEXT or CF_BITMAP because the
136  * pre-defined identifier will not be returned</p>
137  *
138  * @param formatName the name of a data type
139  *
140  * @return the unique identifier associated with this data type
141  */
142 public static int registerType(String formatName){
143     if (formatName is null) return OS.GDK_NONE;
144     char* buffer = toStringz( formatName );
145     return cast(int)/*64bit*/OS.gdk_atom_intern(buffer, false);
146 }
147 
148 /**
149  * Test that the object is of the correct format for this Transfer class.
150  *
151  * @param object a java representation of the data to be converted
152  *
153  * @return true if object is of the correct form for this transfer type
154  *
155  * @since 3.1
156  */
157 public bool validate(Object object) {
158     return true;
159 }
160 }