Mercurial > projects > dwt-mac

comparison dwt/dnd/DropTargetListener.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 e831403a80a9
comparison
equal deleted inserted replaced
-1:000000000000 0:380af2bdd8e5
1 /*******************************************************************************
2 * Copyright (c) 2000, 2003 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 import dwt.internal.DWTEventListener;
14
15 /**
16 * The <code>DropTargetListener</code> class provides event notification to the application
17 * for DropTarget events.
18 *
19 * <p>As the user moves the cursor into, over and out of a Control that has been designated
20 * as a DropTarget, events indicate what operation can be performed and what data can be
21 * transferred if a drop where to occur at that point.
22 * The application can respond to these events and change the type of data that will
23 * be dropped by modifying event.currentDataType, or change the operation that will be performed
24 * by modifying the event.detail field or stop any drop from happening on the current target
25 * by setting the event.detail field to DND_DROP_NONE.</p>
26 *
27 * <p>When the user causes a drop to happen by releasing the mouse over a valid drop target,
28 * the application has one last chance to change the data type of the drop through the
29 * DropAccept event. If the drop is still allowed, the DropAccept event is immediately
30 * followed by the Drop event. In the Drop event, the application can still change the
31 * operation that is performed but the data type is fixed.</p>
32 *
33 * @see DropTargetEvent
34 *
35 */
36 public interface DropTargetListener : DWTEventListener {
37
38 /**
39 * The cursor has entered the drop target boundaries.
40 *
41 * <p>The following fields in the DropTargetEvent apply:
42 * <ul>
43 * <li>(in)widget
44 * <li>(in)time
45 * <li>(in)x
46 * <li>(in)y
47 * <li>(in)dataTypes
48 * <li>(in,out)currentDataType
49 * <li>(in)operations
50 * <li>(in,out)detail
51 * <li>(in,out)feedback
52 * </ul></p>
53 *
54 * <p>The <code>operation</code> value is determined by the modifier keys pressed by the user.
55 * If no keys are pressed the <code>event.detail</code> field is set to DND.DROP_DEFAULT.
56 * If the application does not set the <code>event.detail</code> to something other
57 * than <code>DND.DROP_DEFAULT</code> the operation will be set to the platform defined standard
58 * default.</p>
59 *
60 * <p>The <code>currentDataType</code> is determined by the first transfer agent specified in
61 * setTransfer() that matches a data type provided by the drag source.</p>
62 *
63 * <p>It is possible to get a DragEnter event when the drag source does not provide any matching data.
64 * In this case, the default operation is DND.DROP_NONE and the currentDataType is null.</p>
65 *
66 * <p>The application can change the operation that will be performed by modifying the
67 * <code>detail</code> field but the choice must be one of the values in the <code>operations</code>
68 * field or DND.DROP_NONE.</p>
69 *
70 * <p>The application can also change the type of data being requested by
71 * modifying the <code>currentDataTypes</code> field but the value must be one of the values
72 * in the <code>dataTypes</code> list.</p>
73 *
74 * @param event the information associated with the drag enter event
75 *
76 * @see DropTargetEvent
77 */
78 public void dragEnter(DropTargetEvent event);
79
80 /**
81 * The cursor has left the drop target boundaries OR the drop has been cancelled OR the data
82 * is about to be dropped.
83 *
84 * <p>The following fields in the DropTargetEvent apply:
85 * <ul>
86 * <li>(in)widget
87 * <li>(in)time
88 * <li>(in)x
89 * <li>(in)y
90 * <li>(in)dataTypes
91 * <li>(in)currentDataType
92 * <li>(in)operations
93 * <li>(in)detail
94 * </ul></p>
95 *
96 * @param event the information associated with the drag leave event
97 *
98 * @see DropTargetEvent
99 */
100 public void dragLeave(DropTargetEvent event);
101
102 /**
103 * The operation being performed has changed (usually due to the user changing the selected modifier key(s)
104 * while dragging).
105 *
106 * <p>The following fields in the DropTargetEvent apply:
107 * <ul>
108 * <li>(in)widget
109 * <li>(in)time
110 * <li>(in)x
111 * <li>(in)y
112 * <li>(in)dataTypes
113 * <li>(in,out)currentDataType
114 * <li>(in)operations
115 * <li>(in,out)detail
116 * <li>(in,out)feedback
117 * </ul></p>
118 *
119 * <p>The <code>operation</code> value is determined by the modifier keys pressed by the user.
120 * If no keys are pressed the <code>event.detail</code> field is set to DND.DROP_DEFAULT.
121 * If the application does not set the <code>event.detail</code> to something other than
122 * <code>DND.DROP_DEFAULT</code> the operation will be set to the platform defined standard default.</p>
123 *
124 * <p>The <code>currentDataType</code> value is determined by the value assigned to
125 * <code>currentDataType</code> in previous dragEnter and dragOver calls.</p>
126 *
127 * <p>The application can change the operation that will be performed by modifying the
128 * <code>detail</code> field but the choice must be one of the values in the <code>operations</code>
129 * field.</p>
130 *
131 * <p>The application can also change the type of data being requested by modifying
132 * the <code>currentDataTypes</code> field but the value must be one of the values in the
133 * <code>dataTypes</code> list.</p>
134 *
135 * @param event the information associated with the drag operation changed event
136 *
137 * @see DropTargetEvent
138 */
139 public void dragOperationChanged(DropTargetEvent event);
140
141 /**
142 * The cursor is moving over the drop target.
143 *
144 * <p>The following fields in the DropTargetEvent apply:
145 * <ul>
146 * <li>(in)widget
147 * <li>(in)time
148 * <li>(in)x
149 * <li>(in)y
150 * <li>(in)dataTypes
151 * <li>(in,out)currentDataType
152 * <li>(in)operations
153 * <li>(in,out)detail
154 * <li>(in,out)feedback
155 * </ul></p>
156 *
157 * <p>The <code>operation</code> value is determined by the value assigned to
158 * <code>currentDataType</code> in previous dragEnter and dragOver calls.</p>
159 *
160 * <p>The <code>currentDataType</code> value is determined by the value assigned to
161 * <code>currentDataType</code> in previous dragEnter and dragOver calls.</p>
162 *
163 * <p>The application can change the operation that will be performed by modifying the
164 * <code>detail</code> field but the choice must be one of the values in the <code>operations</code>
165 * field.</p>
166 *
167 * <p>The application can also change the type of data being requested by modifying the
168 * <code>currentDataTypes</code> field but the value must be one of the values in the
169 * <code>dataTypes</code> list.</p>
170 *
171 * <p>NOTE: At this point the <code>data</code> field is null. On some platforms, it is possible
172 * to obtain the data being transferred before the transfer occurs but in most platforms this is
173 * not possible. On those platforms where the data is available, the application can access the
174 * data as follows:</p>
175 *
176 * <pre><code>
177 * public void dragOver(DropTargetEvent event) {
178 * TextTransfer textTransfer = TextTransfer.getInstance();
179 * String data = (String)textTransfer.nativeToJava(event.currentDataType);
180 * if (data !is null) {
181 * System.out.println("Data to be dropped is (Text)"+data);
182 * }
183 * };
184 * </code></pre>
185 *
186 * @param event the information associated with the drag over event
187 *
188 * @see DropTargetEvent
189 */
190 public void dragOver(DropTargetEvent event);
191
192 /**
193 * The data is being dropped. The data field contains java format of the data being dropped.
194 * To determine the type of the data object, refer to the documentation for the Transfer subclass
195 * specified in event.currentDataType.
196 *
197 * <p>The following fields in DropTargetEvent apply:
198 * <ul>
199 * <li>(in)widget
200 * <li>(in)time
201 * <li>(in)x
202 * <li>(in)y
203 * <li>(in,out)detail
204 * <li>(in)currentDataType
205 * <li>(in)data
206 * </ul></p>
207 *
208 * <p>The application can refuse to perform the drop operation by setting the detail
209 * field to DND.DROP_NONE.</p>
210 *
211 * @param event the information associated with the drop event
212 *
213 * @see DropTargetEvent
214 */
215 public void drop(DropTargetEvent event);
216
217 /**
218 * The drop is about to be performed.
219 * The drop target is given a last chance to change the nature of the drop.
220 *
221 * <p>The following fields in the DropTargetEvent apply:
222 * <ul>
223 * <li>(in)widget
224 * <li>(in)time
225 * <li>(in)x
226 * <li>(in)y
227 * <li>(in)dataTypes
228 * <li>(in,out)currentDataType
229 * <li>(in)operations
230 * <li>(in,out)detail
231 * </ul></p>
232 *
233 * <p>The application can veto the drop by setting the <code>event.detail</code> field to
234 * <code>DND.DROP_NONE</code>.</p>
235 *
236 * <p>The application can change the operation that will be performed by modifying the
237 * <code>detail</code> field but the choice must be one of the values in the
238 * <code>operations</code> field.</p>
239 *
240 * <p>The application can also change the type of data being requested by modifying the
241 * <code>currentDataTypes</code> field but the value must be one of the values in the <
242 * code>dataTypes</code> list.</p>
243 *
244 * @param event the information associated with the drop accept event
245 *
246 * @see DropTargetEvent
247 */
248 public void dropAccept(DropTargetEvent event);
249
250 }