bundles/org.eclipse.swt.win32.win32.x86_64/src/org/eclipse/swt/dnd/Transfer.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
  17 import org.eclipse.swt.internal.ole.win32.*;
  18 import org.eclipse.swt.internal.win32.*;
  19
  20 /**
  21  * <code>Transfer</code> provides a mechanism for converting between a java
  22  * representation of data and a platform specific representation of data and
  23  * vice versa.  It is used in data transfer operations such as drag and drop and
  24  * clipboard copy/paste.
  25  *
  26  * <p>You should only need to become familiar with this class if you are
  27  * implementing a Transfer subclass and you are unable to subclass the
  28  * ByteArrayTransfer class.</p>
  29  *
  30  * @see ByteArrayTransfer
  31  * @see <a href="http://www.eclipse.org/swt/snippets/#dnd">Drag and Drop snippets</a>
  32  * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: DNDExample</a>
  33  * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  34  */
  35 public abstract class Transfer {
  36
  37 private static final int RETRY_LIMIT = 10;
  38 /*
  39  * Feature in Windows. When another application has control
  40  * of the clipboard, the clipboard is locked and it's not
  41  * possible to retrieve data until the other application is
  42  * finished. To allow other applications to get the
  43  * data, use PeekMessage() to enable cross thread
  44  * message sends.
  45  */
  46 int getData(IDataObject dataObject, FORMATETC pFormatetc, STGMEDIUM pmedium) {
  47         if (dataObject.GetData(pFormatetc, pmedium) == COM.S_OK) return COM.S_OK;
  48         try {Thread.sleep(50);} catch (Throwable t) {}
  49         int result = dataObject.GetData(pFormatetc, pmedium);
  50         int retryCount = 0;
  51         while (result != COM.S_OK && retryCount++ < RETRY_LIMIT) {
  52                 MSG msg = new MSG();
  53                 OS.PeekMessage(msg, 0, 0, 0, OS.PM_NOREMOVE | OS.PM_NOYIELD);
  54                 try {Thread.sleep(50);} catch (Throwable t) {}
  55                 result = dataObject.GetData(pFormatetc, pmedium);
  56         }
  57         return result;
  58 }
  59
  60 /**
  61  * Returns a list of the platform specific data types that can be converted using
  62  * this transfer agent.
  63  *
  64  * <p>Only the data type fields of the <code>TransferData</code> objects are filled
  65  * in.</p>
  66  *
  67  * @return a list of the data types that can be converted using this transfer agent
  68  */
  69 abstract public TransferData[] getSupportedTypes();
  70
  71 /**
  72  * Returns true if the <code>TransferData</code> data type can be converted
  73  * using this transfer agent, or false otherwise (including if transferData is
  74  * <code>null</code>).
  75  *
  76  * @param transferData a platform specific description of a data type; only the data
  77  *  type fields of the <code>TransferData</code> object need to be filled in
  78  *
  79  * @return true if the transferData data type can be converted using this transfer
  80  * agent
  81  */
  82 abstract public boolean isSupportedType(TransferData transferData);
  83
  84 /**
  85  * Returns the platform specific ids of the  data types that can be converted using
  86  * this transfer agent.
  87  *
  88  * @return the platform specific ids of the data types that can be converted using
  89  * this transfer agent
  90  */
  91 abstract protected int[] getTypeIds();
  92
  93 /**
  94  * Returns the platform specific names of the  data types that can be converted
  95  * using this transfer agent.
  96  *
  97  * @return the platform specific names of the data types that can be converted
  98  * using this transfer agent.
  99  */
 100 abstract protected String[] getTypeNames();
 101
 102 /**
 103  * Converts a java representation of data to a platform specific representation of
 104  * the data.
 105  *
 106  * <p>On a successful conversion, the transferData.result field will be set as follows:</p>
 107  * <ul>
 108  * <li>Windows: COM.S_OK
 109  * <li>GTK: 1
 110  * </ul>
 111  *
 112  * <p>If this transfer agent is unable to perform the conversion, the transferData.result
 113  * field will be set to a failure value as follows:</p>
 114  * <ul>
 115  * <li>Windows: COM.DV_E_TYMED or COM.E_FAIL
 116  * <li>GTK: 0
 117  * </ul>
 118  *
 119  * @param object a java representation of the data to be converted; the type of
 120  * Object that is passed in is dependent on the <code>Transfer</code> subclass.
 121  *
 122  * @param transferData an empty TransferData object; this object will be
 123  * filled in on return with the platform specific representation of the data
 124  *
 125  * @exception org.eclipse.swt.SWTException <ul>
 126  *    <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
 127  * </ul>
 128  */
 129 abstract protected void javaToNative (Object object, TransferData transferData);
 130
 131 /**
 132  * Converts a platform specific representation of data to a java representation.
 133  *
 134  * @param transferData the platform specific representation of the data to be
 135  * converted
 136  *
 137  * @return a java representation of the converted data if the conversion was
 138  * successful; otherwise null.  If transferData is <code>null</code> then
 139  * <code>null</code> is returned.  The type of Object that is returned is
 140  * dependent on the <code>Transfer</code> subclass.
 141  */
 142 abstract protected Object nativeToJava(TransferData transferData);
 143
 144 /**
 145  * Registers a name for a data type and returns the associated unique identifier.
 146  *
 147  * <p>You may register the same type more than once, the same unique identifier
 148  * will be returned if the type has been previously registered.</p>
 149  *
 150  * <p>Note: On windows, do <b>not</b> call this method with pre-defined
 151  * Clipboard Format types such as CF_TEXT or CF_BITMAP because the
 152  * pre-defined identifier will not be returned</p>
 153  *
 154  * @param formatName the name of a data type
 155  *
 156  * @return the unique identifier associated with this data type
 157  */
 158 public static int registerType(String formatName) {
 159         // Look name up in the registry
 160         // If name is not in registry, add it and return assigned value.
 161         // If name already exists in registry, return its assigned value
 162         TCHAR chFormatName = new TCHAR(0, formatName, true);
 163         return OS.RegisterClipboardFormat(chFormatName);
 164 }
 165
 166 /**
 167  * Test that the object is of the correct format for this Transfer class.
 168  *
 169  * @param object a java representation of the data to be converted
 170  *
 171  * @return true if object is of the correct form for this transfer type
 172  *
 173  * @since 3.1
 174  */
 175 protected boolean validate(Object object) {
 176         return true;
 177 }
 178 }