bundles/org.eclipse.swt.win32.win32.x86_64/src/org/eclipse/swt/dnd/DropTargetListener.java

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