/*******************************************************************************
* Copyright (c) 2000, 2007 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.swt.dnd;
import org.eclipse.swt.internal.wpf.*;
import org.eclipse.swt.*;
import org.eclipse.swt.widgets.*;
/**
* The Clipboard
provides a mechanism for transferring data from one
* application to another or within an application.
*
*
IMPORTANT: This class is not intended to be subclassed.
*/ public class Clipboard { private Display display; /** * Constructs a new instance of this class. Creating an instance of a Clipboard * may cause system resources to be allocated depending on the platform. It is therefore * mandatory that the Clipboard instance be disposed when no longer required. * * @param display the display on which to allocate the clipboard * * @exception SWTException* The SWT class library is intended to be subclassed * only at specific, controlled points. This method enforces this * rule unless it is overridden. *
* IMPORTANT: By providing an implementation of this * method that allows a subclass of a class which does not * normally allow subclassing to be created, the implementer * agrees to be fully responsible for the fact that any such * subclass will likely fail between SWT releases and will be * strongly platform specific. No support is provided for * user-written classes which are implemented in this fashion. *
* The ability to subclass outside of the allowed SWT classes * is intended purely to enable those not on the SWT development * team to implement patches in order to get around specific * limitations in advance of when those limitations can be * addressed by the team. Subclassing should not be attempted * without an intimate and detailed understanding of the hierarchy. *
* * @exception SWTExceptionSWTException
if the receiver can not
* be accessed by the caller. This may include both checks on
* the state of the receiver and more generally on the entire
* execution context. This method should be called by
* widget implementors to enforce the standard SWT invariants.
*
* Currently, it is an error to invoke any method (other than
* isDisposed()
) on a widget that has had its
* dispose()
method called. It is also an error
* to call widget methods from any thread that is different
* from the thread that created the widget.
*
* In future releases of SWT, there may be more or fewer error * checks and exceptions may be thrown for different reasons. *
* * @exception SWTExceptionNote that there are clipboard assistant applications that take ownership * of data or make copies of data when it is placed on the clipboard. In these * cases, it may not be possible to clear the clipboard.
* *The clipboards value is either one of the clipboard constants defined in
* class DND
, or must be built by bitwise OR'ing together
* (that is, using the int
"|" operator) two or more
* of those DND
clipboard constants.
NOTE: On some platforms the data will not be available once the application * has exited or the display has been disposed.
* * @exception SWTExceptionNote: getAvailableTypeNames
is a utility for writing a Transfer
* sub-class. It should NOT be used within an application because it provides
* platform specific information.
The clipboards value is either one of the clipboard constants defined in
* class DND
, or must be built by bitwise OR'ing together
* (that is, using the int
"|" operator) two or more
* of those DND
clipboard constants.
Transfer
to
* determine the type of object returned.
*
* The following snippet shows text and RTF text being retrieved from the * clipboard:
* *
* Clipboard clipboard = new Clipboard(display);
* TextTransfer textTransfer = TextTransfer.getInstance();
* String textData = (String)clipboard.getContents(textTransfer);
* if (textData != null) System.out.println("Text is "+textData);
* RTFTransfer rtfTransfer = RTFTransfer.getInstance();
* String rtfData = (String)clipboard.getContents(rtfTransfer);
* if (rtfData != null) System.out.println("RTF Text is "+rtfData);
* clipboard.dispose();
*
*
* @param transfer the transfer agent for the type of data being requested
* @return the data obtained from the clipboard or null if no data of this type is available
*
* @exception SWTException Transfer
to
* determine the type of object returned.
*
* The following snippet shows text and RTF text being retrieved from the * clipboard:
* *
* Clipboard clipboard = new Clipboard(display);
* TextTransfer textTransfer = TextTransfer.getInstance();
* String textData = (String)clipboard.getContents(textTransfer);
* if (textData != null) System.out.println("Text is "+textData);
* RTFTransfer rtfTransfer = RTFTransfer.getInstance();
* String rtfData = (String)clipboard.getContents(rtfTransfer, DND.CLIPBOARD);
* if (rtfData != null) System.out.println("RTF Text is "+rtfData);
* clipboard.dispose();
*
*
* The clipboards value is either one of the clipboard constants defined in
* class DND
, or must be built by bitwise OR'ing together
* (that is, using the int
"|" operator) two or more
* of those DND
clipboard constants.
true
if the clipboard has been disposed,
* and false
otherwise.
* * This method gets the dispose state for the clipboard. * When a clipboard has been disposed, it is an error to * invoke any other method using the clipboard. *
* * @returntrue
when the widget is disposed and false
otherwise
*
* @since 3.0
*/
public boolean isDisposed () {
return (display == null);
}
/**
* Place data of the specified type on the system clipboard. More than one type
* of data can be placed on the system clipboard at the same time. Setting the
* data clears any previous data from the system clipboard, regardless of type.
*
* NOTE: On some platforms, the data is immediately copied to the system * clipboard but on other platforms it is provided upon request. As a result, * if the application modifies the data object it has set on the clipboard, that * modification may or may not be available when the data is subsequently * requested.
* *The following snippet shows text and RTF text being set on the copy/paste * clipboard: *
* *
* Clipboard clipboard = new Clipboard(display);
* String textData = "Hello World";
* String rtfData = "{\\rtf1\\b\\i Hello World}";
* TextTransfer textTransfer = TextTransfer.getInstance();
* RTFTransfer rtfTransfer = RTFTransfer.getInstance();
* Transfer[] transfers = new Transfer[]{textTransfer, rtfTransfer};
* Object[] data = new Object[]{textData, rtfData};
* clipboard.setContents(data, transfers);
* clipboard.dispose();
*
*
* @param data the data to be set in the clipboard
* @param dataTypes the transfer agents that will convert the data to its
* platform specific format; each entry in the data array must have a
* corresponding dataType
*
* @exception IllegalArgumentException NOTE: ERROR_CANNOT_SET_CLIPBOARD should be an SWTException, since it is a * recoverable error, but can not be changed due to backward compatibility.
*/ public void setContents(Object[] data, Transfer[] dataTypes) { setContents(data, dataTypes, DND.CLIPBOARD); } /** * Place data of the specified type on the specified clipboard. More than one * type of data can be placed on the specified clipboard at the same time. * Setting the data clears any previous data from the specified * clipboard, regardless of type. * *NOTE: On some platforms, the data is immediately copied to the specified * clipboard but on other platforms it is provided upon request. As a result, * if the application modifies the data object it has set on the clipboard, that * modification may or may not be available when the data is subsequently * requested.
* *The clipboards value is either one of the clipboard constants defined in
* class DND
, or must be built by bitwise OR'ing together
* (that is, using the int
"|" operator) two or more
* of those DND
clipboard constants.
The following snippet shows text and RTF text being set on the copy/paste * clipboard: *
* *
* Clipboard clipboard = new Clipboard(display);
* String textData = "Hello World";
* String rtfData = "{\\rtf1\\b\\i Hello World}";
* TextTransfer textTransfer = TextTransfer.getInstance();
* RTFTransfer rtfTransfer = RTFTransfer.getInstance();
* Transfer[] transfers = new Transfer[]{textTransfer, rtfTransfer};
* Object[] data = new Object[]{textData, rtfData};
* clipboard.setContents(data, transfers, DND.CLIPBOARD);
* clipboard.dispose();
*
*
* @param data the data to be set in the clipboard
* @param dataTypes the transfer agents that will convert the data to its
* platform specific format; each entry in the data array must have a
* corresponding dataType
* @param clipboards on which to set the data
*
* @exception IllegalArgumentException NOTE: ERROR_CANNOT_SET_CLIPBOARD should be an SWTException, since it is a * recoverable error, but can not be changed due to backward compatibility.
* * @see DND#CLIPBOARD * @see DND#SELECTION_CLIPBOARD * * @since 3.1 */ public void setContents(Object[] data, Transfer[] dataTypes, int clipboards) { checkWidget(); if (data == null || dataTypes == null || data.length != dataTypes.length) { DND.error(SWT.ERROR_INVALID_ARGUMENT); } int pDataObject = OS.gcnew_DataObject(); for (int i = 0; i < dataTypes.length; i++) { Transfer transfer = dataTypes[i]; Object value = data[i]; int[] types = transfer.getTypeIds(); for (int j = 0; j < types.length; j++) { TransferData transferData = new TransferData(); transferData.type = types[j]; transfer.javaToNative(value, transferData); if (transferData.pValue != 0) { int pFormat = Transfer.getWPFFormat(transferData.type); OS.DataObject_SetData(pDataObject, pFormat, transferData.pValue, true); OS.GCHandle_Free(pFormat); OS.GCHandle_Free(transferData.pValue); } } } OS.Clipboard_SetDataObject(pDataObject, false); OS.GCHandle_Free(pDataObject); } }