Top Description Fields Constructors Methods
org.eclipse.swt.dnd

public Class Clipboard

extends Object
Class Inheritance
Imports
org.eclipse.swt.*, org.eclipse.swt.graphics.*, org.eclipse.swt.internal.*, org.eclipse.swt.internal.gtk.*, org.eclipse.swt.internal.gtk3.*, org.eclipse.swt.internal.gtk4.*, org.eclipse.swt.widgets.*
The Clipboard provides a mechanism for transferring data from one application to another or within an application.

Important Note

This class is not intended to be subclassed.

See Also
Clipboard snippets, SWT Example: ClipboardExample, Sample code and further information

Field Summary

Modifier and TypeField and Description
private Display
display

pack-priv static long
GTKCLIPBOARD

pack-priv static long
GTKPRIMARYCLIPBOARD

private static long
TARGET

Constructor Summary

AccessConstructor and Description
public
Clipboard(Display
the display on which to allocate the clipboard
display)

Constructs a new instance of this class.

Method Summary

Modifier and TypeMethod and Description
protected void
checkSubclass()

Checks that this class can be subclassed.

protected void
checkWidget()

Throws an SWTException if the receiver can not be accessed by the caller.

public void
clearContents()

If this clipboard is currently the owner of the data on the system clipboard, clear the contents.

public void
clearContents(int
to be cleared
clipboards)

If this clipboard is currently the owner of the data on the specified clipboard, clear the contents.

public void
dispose()

Disposes of the operating system resources associated with the clipboard.

private int[]
getAvailableClipboardTypes()

private int[]
getAvailablePrimaryTypes()

public String[]

Returns:

a platform specific list of the data types currently available on the system clipboard
getAvailableTypeNames()

Returns a platform specific list of the data types currently available on the system clipboard.

public TransferData[]

Returns:

array of data types currently available on the system clipboard
getAvailableTypes()

Returns an array of the data types currently available on the system clipboard.

public TransferData[]

Returns:

array of data types currently available on the specified clipboard
getAvailableTypes(int
from which to get the data types
clipboards)

Returns an array of the data types currently available on the specified clipboard.

public Object

Returns:

the data obtained from the clipboard or null if no data of this type is available
getContents(Transfer
the transfer agent for the type of data being requested
transfer)

Retrieve the data of the specified type currently available on the system clipboard.

public Object

Returns:

the data obtained from the clipboard or null if no data of this type is available
getContents(Transfer
the transfer agent for the type of data being requested
transfer, int
on which to look for data
clipboards)

Retrieve the data of the specified type currently available on the specified clipboard.

private Object
getContents_gtk4(Transfer transfer, int clipboards)

pack-priv long
gtk_clipboard_wait_for_contents(long clipboard, long target)

public boolean

Returns:

true when the widget is disposed and false otherwise
isDisposed()

Returns true if the clipboard has been disposed, and false otherwise.

public void
setContents(Object[]
the data to be set in the clipboard
data, Transfer[]
the transfer agents that will convert the data to its platform specific format; each entry in the data array must have a corresponding dataType
dataTypes)

Place data of the specified type on the system clipboard.

public void
setContents(Object[]
the data to be set in the clipboard
data, Transfer[]
the transfer agents that will convert the data to its platform specific format; each entry in the data array must have a corresponding dataType
dataTypes, int
on which to set the data
clipboards)

Place data of the specified type on the specified clipboard.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

displayback to summary
private Display display
GTKCLIPBOARDback to summary
pack-priv static long GTKCLIPBOARD
GTKPRIMARYCLIPBOARDback to summary
pack-priv static long GTKPRIMARYCLIPBOARD
TARGETback to summary
private static long TARGET

Constructor Detail

Clipboardback to summary
public Clipboard(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.

Parameters
display:Display

the display on which to allocate the clipboard

Exceptions
SWTException:
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
  • ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
See Also
Clipboard#dispose, Clipboard#checkSubclass

Method Detail

checkSubclassback to summary
protected void checkSubclass()

Checks that this class can be subclassed.

The SWT class library is intended to be subclassed only at specific, controlled points. This method enforces this rule unless it is overridden.

Important Note

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.

Exceptions
SWTException:
  • ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
checkWidgetback to summary
protected void checkWidget()

Throws an SWTException 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.

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
clearContentsback to summary
public void clearContents()

If this clipboard is currently the owner of the data on the system clipboard, clear the contents. If this clipboard is not the owner, then nothing is done. Note 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.

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Since
3.1
clearContentsback to summary
public void clearContents(int clipboards)

If this clipboard is currently the owner of the data on the specified clipboard, clear the contents. If this clipboard is not the owner, then nothing is done.

Note 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.

Parameters
clipboards:int

to be cleared

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Since
3.1
See Also
DND#CLIPBOARD, DND#SELECTION_CLIPBOARD
disposeback to summary
public void dispose()

Disposes of the operating system resources associated with the clipboard. The data will still be available on the system clipboard after the dispose method is called.

Note

On some platforms the data will not be available once the application has exited or the display has been disposed.

Exceptions
SWTException:
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
getAvailableClipboardTypesback to summary
private int[] getAvailableClipboardTypes()
getAvailablePrimaryTypesback to summary
private int[] getAvailablePrimaryTypes()
getAvailableTypeNamesback to summary
public String[] getAvailableTypeNames()

Returns a platform specific list of the data types currently available on the system clipboard.

Note

getAvailableTypeNames is a utility for writing a Transfer sub-class. It should NOT be used within an application because it provides platform specific information.

Returns:String[]

a platform specific list of the data types currently available on the system clipboard

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
getAvailableTypesback to summary
public TransferData[] getAvailableTypes()

Returns an array of the data types currently available on the system clipboard. Use with Transfer.isSupportedType.

Returns:TransferData[]

array of data types currently available on the system clipboard

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Since
3.0
See Also
Transfer#isSupportedType
getAvailableTypesback to summary
public TransferData[] getAvailableTypes(int clipboards)

Returns an array of the data types currently available on the specified clipboard. Use with Transfer.isSupportedType.

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.

Parameters
clipboards:int

from which to get the data types

Returns:TransferData[]

array of data types currently available on the specified clipboard

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Since
3.1
See Also
Transfer#isSupportedType, DND#CLIPBOARD, DND#SELECTION_CLIPBOARD
getContentsback to summary
public Object getContents(Transfer transfer)

Retrieve the data of the specified type currently available on the system clipboard. Refer to the specific subclass of 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();
Parameters
transfer:Transfer

the transfer agent for the type of data being requested

Returns:Object

the data obtained from the clipboard or null if no data of this type is available

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
IllegalArgumentException:
  • ERROR_NULL_ARGUMENT - if transfer is null
See Also
Transfer
getContentsback to summary
public Object getContents(Transfer transfer, int clipboards)

Retrieve the data of the specified type currently available on the specified clipboard. Refer to the specific subclass of 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.

Parameters
transfer:Transfer

the transfer agent for the type of data being requested

clipboards:int

on which to look for data

Returns:Object

the data obtained from the clipboard or null if no data of this type is available

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
IllegalArgumentException:
  • ERROR_NULL_ARGUMENT - if transfer is null
Since
3.1
See Also
Transfer, DND#CLIPBOARD, DND#SELECTION_CLIPBOARD
getContents_gtk4back to summary
private Object getContents_gtk4(Transfer transfer, int clipboards)
gtk_clipboard_wait_for_contentsback to summary
pack-priv long gtk_clipboard_wait_for_contents(long clipboard, long target)
isDisposedback to summary
public boolean isDisposed()

Returns 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.

Returns:boolean

true when the widget is disposed and false otherwise

Since
3.0
setContentsback to summary
public void setContents(Object[] data, Transfer[] dataTypes)

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();
Parameters
data:Object[]

the data to be set in the clipboard

dataTypes:Transfer[]

the transfer agents that will convert the data to its platform specific format; each entry in the data array must have a corresponding dataType

Exceptions
IllegalArgumentException:
  • ERROR_INVALID_ARGUMENT - if data is null or datatypes is null or the length of data is not the same as the length of dataTypes
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
SWTError:
  • ERROR_CANNOT_SET_CLIPBOARD - if the clipboard is locked or otherwise unavailable

NOTE: ERROR_CANNOT_SET_CLIPBOARD should be an SWTException, since it is a recoverable error, but can not be changed due to backward compatibility.

setContentsback to summary
public void setContents(Object[] data, Transfer[] dataTypes, int clipboards)

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();
Parameters
data:Object[]

the data to be set in the clipboard

dataTypes:Transfer[]

the transfer agents that will convert the data to its platform specific format; each entry in the data array must have a corresponding dataType

clipboards:int

on which to set the data

Exceptions
IllegalArgumentException:
  • ERROR_INVALID_ARGUMENT - if data is null or datatypes is null or the length of data is not the same as the length of dataTypes
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
SWTError:
  • ERROR_CANNOT_SET_CLIPBOARD - if the clipboard is locked or otherwise unavailable

NOTE: ERROR_CANNOT_SET_CLIPBOARD should be an SWTException, since it is a recoverable error, but can not be changed due to backward compatibility.

Since
3.1
See Also
DND#CLIPBOARD, DND#SELECTION_CLIPBOARD