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

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2013 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
  17 import org.eclipse.swt.*;
  18
  19 /**
  20  * Class DND contains all the constants used in defining a
  21  * DragSource or a DropTarget.
  22  *
  23  * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  24  */
  25 public class DND {
  26
  27         /**
  28          * The transfer mechanism for data that is being cut
  29          * and then pasted or copied and then pasted (value is 1).
  30          *
  31          * @see Clipboard
  32          *
  33          * @since 3.1
  34          */
  35         public final static int CLIPBOARD = 1 << 0;
  36
  37         /**
  38          * The transfer mechanism for clients that use the selection
  39          * mechanism (value is 2).
  40          *
  41          * @see Clipboard
  42          *
  43          * @since 3.1
  44          */
  45         public final static int SELECTION_CLIPBOARD = 1 << 1;
  46
  47         /**
  48          * Drag and Drop Operation: no drag/drop operation performed
  49          * (value is 0).
  50          */
  51         public final static int DROP_NONE = 0;
  52
  53         /**
  54          * Drag and Drop Operation: a copy of the data in the drag source is
  55          * added to the drop target (value is 1 &lt;&lt; 0).
  56          */
  57         public final static int DROP_COPY = 1 << 0;
  58
  59         /**
  60          * Drag and Drop Operation: a copy of the data is added to the drop target and
  61          * the drag source removes the original data and any references to the data,
  62          * and updates its display (value is 1 &lt;&lt; 1).
  63          * <p>
  64          * <b>Warning:</b> Some applications (most notably Firefox, Thunderbird, and Safari) return
  65          * {@link DND#DROP_MOVE} even if they just open a dropped file and don't copy
  66          * anything, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=30543">bug 30543</a>.
  67          * </p>
  68          * <p>
  69          * <b>To avoid data loss</b>, you may want to not remove the original data
  70          * when you handle a {@link DND#DragEnd} for a {@link FileTransfer} whose
  71          * {@link org.eclipse.swt.widgets.Event#detail} is {@link #DROP_MOVE}.
  72          * </p>
  73          */
  74         public final static int DROP_MOVE = 1 << 1;
  75
  76         /**
  77          * Drag and Drop Operation: the drop target makes a link to the data in
  78          * the drag source (value is 1 &lt;&lt; 2).
  79          */
  80         public final static int DROP_LINK = 1 << 2;
  81
  82         /**
  83          * Drag and Drop Operation: the drop target moves the data and the drag source removes
  84          * any references to the data and updates its display.  This is not available on all platforms
  85          * and is only used when a non-SWT application is the drop target.  In this case, the SWT
  86          * drag source is informed in the dragFinished event that the drop target has moved the data.
  87          * (value is 1 &lt;&lt; 3).
  88          *
  89          * @see DragSourceListener#dragFinished
  90          */
  91         public final static int DROP_TARGET_MOVE = 1 << 3;
  92
  93         /**
  94          * Drag and Drop Operation: During a dragEnter event or a dragOperationChanged, if no modifier keys
  95          * are pressed, the operation is set to DROP_DEFAULT.  The application can choose what the default
  96          * operation should be by setting a new value in the operation field.  If no value is choosen, the
  97          * default operation for the platform will be selected (value is 1 &lt;&lt; 4).
  98          *
  99          * @see DropTargetListener#dragEnter
 100          * @see DropTargetListener#dragOperationChanged
 101          * @since 2.0
 102          */
 103         public final static int DROP_DEFAULT = 1 << 4;
 104
 105         /**
 106          * DragSource Event: the drop has successfully completed or has been terminated (such as hitting
 107          * the ESC key); perform cleanup such as removing data on a move operation (value is 2000).
 108          */
 109         public static final int DragEnd         = 2000;
 110
 111         /**
 112          * DragSource Event: the data to be dropped is required from the drag source (value is 2001).
 113          */
 114         public static final int DragSetData = 2001;
 115
 116         /**
 117          * DropTarget Event: the cursor has entered the drop target boundaries (value is 2002).
 118          */
 119         public static final int DragEnter       = 2002;
 120
 121         /**
 122          * DropTarget Event: the cursor has left the drop target boundaries OR the drop
 123          * operation has been cancelled (such as by hitting ECS) OR the drop is about to
 124          * happen (user has released the mouse button over this target) (value is 2003).
 125          */
 126         public static final int DragLeave       = 2003;
 127
 128         /**
 129          * DropTarget Event: the cursor is over the drop target (value is 2004).
 130          */
 131         public static final int DragOver        = 2004;
 132
 133         /**
 134          * DropTarget Event: the operation being performed has changed usually due to the user
 135          * changing the selected modifier keys while dragging (value is 2005).
 136          */
 137         public static final int DragOperationChanged = 2005;
 138
 139         /**
 140          * DropTarget Event: the data has been dropped (value is 2006).
 141          */
 142         public static final int Drop = 2006;
 143
 144         /**
 145          * DropTarget Event: the drop target is given a last chance to modify the drop (value is 2007).
 146          */
 147         public static final int DropAccept      = 2007;
 148
 149         /**
 150          * DragSource Event: a drag is about to begin (value is 2008).
 151          */
 152         public static final int DragStart = 2008;
 153
 154         /**
 155          * DropTarget drag under effect: No effect is shown (value is 0).
 156          */
 157         public static final int FEEDBACK_NONE = 0;
 158
 159         /**
 160          * DropTarget drag under effect: The item under the cursor is selected; applies to tables
 161          * and trees (value is 1).
 162          */
 163         public static final int FEEDBACK_SELECT = 1;
 164
 165         /**
 166          * DropTarget drag under effect: An insertion mark is shown before the item under the cursor; applies to
 167          * tables and trees (value is 2).
 168          */
 169         public static final int FEEDBACK_INSERT_BEFORE = 2;
 170
 171         /**
 172          * DropTarget drag under effect: An insertion mark is shown after the item under the cursor; applies to
 173          * tables and trees (value is 4).
 174          */
 175         public static final int FEEDBACK_INSERT_AFTER = 4;
 176
 177         /**
 178          * DropTarget drag under effect: The widget is scrolled up or down to allow the user to drop on items that
 179          * are not currently visible; applies to tables and trees (value is 8).
 180          */
 181         public static final int FEEDBACK_SCROLL = 8;
 182
 183         /**
 184          * DropTarget drag under effect: The item currently under the cursor is expanded to allow the user to
 185          * select a drop target from a sub item; applies to trees (value is 16).
 186          */
 187         public static final int FEEDBACK_EXPAND = 16;
 188
 189         /**
 190          * Error code: drag source can not be initialized (value is 2000).
 191          */
 192         public static final int ERROR_CANNOT_INIT_DRAG = 2000;
 193
 194         /**
 195          * Error code: drop target cannot be initialized (value is 2001).
 196          */
 197         public static final int ERROR_CANNOT_INIT_DROP = 2001;
 198
 199         /**
 200          * Error code: Data can not be set on system clipboard (value is 2002).
 201          */
 202         public static final int ERROR_CANNOT_SET_CLIPBOARD = 2002;
 203
 204         /**
 205          * Error code: Data does not have correct format for type (value is 2003).
 206          * @since 3.1
 207          */
 208         public static final int ERROR_INVALID_DATA = 2003;
 209
 210         /**
 211          * DropTarget Key: The string constant for looking up the drop target
 212          * for a control using <code>getData(String)</code>. When a drop target
 213          * is created for a control, it is stored as a property in the control
 214          * using <code>setData(String, Object)</code>.
 215          *
 216          * @since 3.4
 217          */
 218         public static final String DROP_TARGET_KEY = "DropTarget"; //$NON-NLS-1$
 219
 220         /**
 221          * DragSource Key: The string constant for looking up the drag source
 222          * for a control using <code>getData(String)</code>. When a drag source
 223          * is created for a control, it is stored as a property in the control
 224          * using <code>setData(String, Object)</code>.
 225          *
 226          * @since 3.4
 227          */
 228         public static final String DRAG_SOURCE_KEY = "DragSource"; //$NON-NLS-1$
 229
 230         static final String INIT_DRAG_MESSAGE = "Cannot initialize Drag"; //$NON-NLS-1$
 231         static final String INIT_DROP_MESSAGE = "Cannot initialize Drop"; //$NON-NLS-1$
 232         static final String CANNOT_SET_CLIPBOARD_MESSAGE = "Cannot set data in clipboard"; //$NON-NLS-1$
 233         static final String INVALID_DATA_MESSAGE = "Data does not have correct format for type"; //$NON-NLS-1$
 234
 235 /**
 236  * Throws an appropriate exception based on the passed in error code.
 237  *
 238  * @param code the DND error code
 239  */
 240 public static void error (int code) {
 241         error (code, 0);
 242 }
 243
 244 /**
 245  * Throws an appropriate exception based on the passed in error code.
 246  * The <code>hresult</code> argument should be either 0, or the
 247  * platform specific error code.
 248  * <p>
 249  * In DND, errors are reported by throwing one of three exceptions:</p>
 250  * <dl>
 251  * <dd>java.lang.IllegalArgumentException</dd>
 252  * <dt>thrown whenever one of the API methods is invoked with an illegal argument</dt>
 253  * <dd>org.eclipse.swt.SWTException (extends java.lang.RuntimeException)</dd>
 254  * <dt>thrown whenever a recoverable error happens internally in SWT</dt>
 255  * <dd>org.eclipse.swt.SWTError (extends java.lang.Error)</dd>
 256  * <dt>thrown whenever a <b>non-recoverable</b> error happens internally in SWT</dt>
 257  * </dl>
 258  * <p>
 259  * This method provides the logic which maps between error codes
 260  * and one of the above exceptions.
 261  * </p>
 262  *
 263  * @param code the DND error code.
 264  * @param hresult the platform specific error code.
 265  *
 266  * @see SWTError
 267  * @see SWTException
 268  * @see IllegalArgumentException
 269  */
 270 public static void error (int code, int hresult) {
 271         switch (code) {
 272                 /* OS Failure/Limit (fatal, may occur only on some platforms) */
 273                 case DND.ERROR_CANNOT_INIT_DRAG:{
 274                         String msg = DND.INIT_DRAG_MESSAGE;
 275                         if (hresult != 0) msg += " result = "+hresult; //$NON-NLS-1$
 276                         throw new SWTError (code, msg);
 277                 }
 278                 case DND.ERROR_CANNOT_INIT_DROP:{
 279                         String msg = DND.INIT_DROP_MESSAGE;
 280                         if (hresult != 0) msg += " result = "+hresult; //$NON-NLS-1$
 281                         throw new SWTError (code, msg);
 282                 }
 283                 case DND.ERROR_CANNOT_SET_CLIPBOARD:{
 284                         String msg = DND.CANNOT_SET_CLIPBOARD_MESSAGE;
 285                         if (hresult != 0) msg += " result = "+hresult; //$NON-NLS-1$
 286                         throw new SWTError (code, msg);
 287                 }
 288                 case DND.ERROR_INVALID_DATA:{
 289                         String msg = DND.INVALID_DATA_MESSAGE;
 290                         if (hresult != 0) msg += " result = "+hresult; //$NON-NLS-1$
 291                         throw new SWTException (code, msg);
 292                 }
 293         }
 294
 295         /* Unknown/Undefined Error */
 296         SWT.error(code);
 297 }
 298
 299 }