Mercurial > projects > dwt-mac

comparison dwt/dnd/Transfer.d @ 0:380af2bdd8e5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Upload of whole dwt tree
author Jacob Carlborg <doob@me.com> <jacob.carlborg@gmail.com>
date Sat, 09 Aug 2008 17:00:02 +0200
parents
children d8635bb48c7c
comparison
equal deleted inserted replaced
-1:000000000000 0:380af2bdd8e5
1 /*******************************************************************************
2 * Copyright (c) 2000, 2007 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 *******************************************************************************/
11 module dwt.dnd;
12
13
14 /**
15 * <code>Transfer</code> provides a mechanism for converting between a java
16 * representation of data and a platform specific representation of data and
17 * vice versa. It is used in data transfer operations such as drag and drop and
18 * clipboard copy/paste.
19 *
20 * <p>You should only need to become familiar with this class if you are
21 * implementing a Transfer subclass and you are unable to subclass the
22 * ByteArrayTransfer class.</p>
23 *
24 * @see ByteArrayTransfer
25 */
26 public abstract class Transfer {
27
28 /**
29 * Returns a list of the platform specific data types that can be converted using
30 * this transfer agent.
31 *
32 * <p>Only the data type fields of the <code>TransferData</code> objects are filled
33 * in.</p>
34 *
35 * @return a list of the data types that can be converted using this transfer agent
36 */
37 abstract public TransferData[] getSupportedTypes();
38
39 /**
40 * Returns true if the <code>TransferData</code> data type can be converted
41 * using this transfer agent, or false otherwise (including if transferData is
42 * <code>null</code>).
43 *
44 * @param transferData a platform specific description of a data type; only the data
45 * type fields of the <code>TransferData</code> object need to be filled in
46 *
47 * @return true if the transferData data type can be converted using this transfer
48 * agent
49 */
50 abstract public bool isSupportedType(TransferData transferData);
51
52 /**
53 * Returns the platform specific ids of the data types that can be converted using
54 * this transfer agent.
55 *
56 * @return the platform specific ids of the data types that can be converted using
57 * this transfer agent
58 */
59 abstract protected int[] getTypeIds();
60
61 /**
62 * Returns the platform specific names of the data types that can be converted
63 * using this transfer agent.
64 *
65 * @return the platform specific names of the data types that can be converted
66 * using this transfer agent.
67 */
68 abstract protected String[] getTypeNames();
69
70 /**
71 * Converts a java representation of data to a platform specific representation of
72 * the data.
73 *
74 * <p>On a successful conversion, the transferData.result field will be set as follows:
75 * <ul>
76 * <li>Windows: COM.S_OK
77 * <li>Motif: 1
78 * <li>GTK: 1
79 * <li>Photon: 1
80 * </ul></p>
81 *
82 * <p>If this transfer agent is unable to perform the conversion, the transferData.result
83 * field will be set to a failure value as follows:
84 * <ul>
85 * <li>Windows: COM.DV_E_TYMED or COM.E_FAIL
86 * <li>Motif: 0
87 * <li>GTK: 0
88 * <li>Photon: 0
89 * </ul></p>
90 *
91 * @param object a java representation of the data to be converted; the type of
92 * Object that is passed in is dependent on the <code>Transfer</code> subclass.
93 *
94 * @param transferData an empty TransferData object; this object will be
95 * filled in on return with the platform specific representation of the data
96 *
97 * @exception dwt.DWTException <ul>
98 * <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
99 * </ul>
100 */
101 abstract protected void javaToNative (Object object, TransferData transferData);
102
103 /**
104 * Converts a platform specific representation of data to a java representation.
105 *
106 * @param transferData the platform specific representation of the data to be
107 * converted
108 *
109 * @return a java representation of the converted data if the conversion was
110 * successful; otherwise null. If transferData is <code>null</code> then
111 * <code>null</code> is returned. The type of Object that is returned is
112 * dependent on the <code>Transfer</code> subclass.
113 */
114 abstract protected Object nativeToJava(TransferData transferData);
115
116 /**
117 * Registers a name for a data type and returns the associated unique identifier.
118 *
119 * <p>You may register the same type more than once, the same unique identifier
120 * will be returned if the type has been previously registered.</p>
121 *
122 * <p>Note: On windows, do <b>not</b> call this method with pre-defined
123 * Clipboard Format types such as CF_TEXT or CF_BITMAP because the
124 * pre-defined identifier will not be returned</p>
125 *
126 * @param formatName the name of a data type
127 *
128 * @return the unique identifier associated with this data type
129 */
130 public static int registerType(String formatName) {
131 int length = formatName.length();
132 // TODO - hashcode may not be unique - need another way
133 if (length > 4) return formatName.toHash();
134 int type = 0;
135 if (length > 0) type |= (formatName.charAt(0) & 0xff) << 24;
136 if (length > 1) type |= (formatName.charAt(1) & 0xff) << 16;
137 if (length > 2) type |= (formatName.charAt(2) & 0xff) << 8;
138 if (length > 3) type |= formatName.charAt(3) & 0xff;
139 return type;
140 }
141
142 /**
143 * Test that the object is of the correct format for this Transfer class.
144 *
145 * @param object a java representation of the data to be converted
146 *
147 * @return true if object is of the correct form for this transfer type
148 *
149 * @since 3.1
150 */
151 protected bool validate(Object object) {
152 return true;
153 }
154 }