DropTargetListener


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  package org.eclipse.swt.dnd;
12  
13  import org.eclipse.swt.internal.SWTEventListener;
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 extends SWTEventListener {
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 != 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 }
251
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags