|
 |
|
|
org.eclipse.swt.dnd
Class Clipboard
java.lang.Object
org.eclipse.swt.dnd.Clipboard
-
public class Clipboard
- extends
Object
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.
-
See Also:
-
Clipboard snippets,
SWT Example: ClipboardExample,
Sample code and further information
-
Restriction:
- This class is not intended to be subclassed by clients.
Constructor Summary
|
Clipboard
(
Display display)
Constructs a new instance of this class. |
Method Summary
|
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. |
void
|
clearContents
()
If this clipboard is currently the owner of the data on the system clipboard,
clear the contents. |
void
|
clearContents
(int clipboards)
If this clipboard is currently the owner of the data on the specified
clipboard, clear the contents. |
void
|
dispose
()
Disposes of the operating system resources associated with the clipboard. |
String[]
|
getAvailableTypeNames
()
Returns a platform specific list of the data types currently available on the
system clipboard. |
TransferData[]
|
getAvailableTypes
()
Returns an array of the data types currently available on the system
clipboard. |
TransferData[]
|
getAvailableTypes
(int clipboards)
Returns an array of the data types currently available on the specified
clipboard. |
Object
|
getContents
(
Transfer transfer)
Retrieve the data of the specified type currently available on the system
clipboard. |
Object
|
getContents
(
Transfer transfer,
int clipboards)
Retrieve the data of the specified type currently available on the specified
clipboard. |
boolean
|
isDisposed
()
Returns true if the clipboard has been disposed,
and false otherwise. |
void
|
setContents
(
Object[] data,
Transfer[] dataTypes)
Place data of the specified type on the system clipboard. |
void
|
setContents
(
Object[] data,
Transfer[] dataTypes,
int clipboards)
Place data of the specified type on the specified clipboard. |
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
Clipboard
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 - the display on which to allocate the clipboard
-
Throws:
-
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:
-
dispose() ,
checkSubclass()
checkSubclass
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: 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.
-
-
Throws:
-
SWTException
-
- ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
checkWidget
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.
-
-
Throws:
-
SWTException
-
- ERROR_WIDGET_DISPOSED - if the receiver has been disposed
- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
clearContents
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.
-
-
Throws:
-
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
clearContents
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 - to be cleared
-
Throws:
-
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
dispose
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.
-
-
Throws:
-
SWTException
-
- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
getContents
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 - the transfer agent for the type of data being requested
-
Returns:
- the data obtained from the clipboard or null if no data of this type is available
-
Throws:
-
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
getContents
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 - the transfer agent for the type of data being requested -
clipboards - on which to look for data
-
Returns:
- the data obtained from the clipboard or null if no data of this type is available
-
Throws:
-
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
isDisposed
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:
-
true when the widget is disposed and false otherwise -
Since:
- 3.0
setContents
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 - the data to be set in the clipboard -
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
-
Throws:
-
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.
setContents
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 - the data to be set in the clipboard -
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 -
clipboards - on which to set the data
-
Throws:
-
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
getAvailableTypes
public
TransferData[] getAvailableTypes()
- Returns an array of the data types currently available on the system
clipboard. Use with Transfer.isSupportedType.
-
-
Returns:
- array of data types currently available on the system clipboard
-
Throws:
-
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(org.eclipse.swt.dnd.TransferData)
getAvailableTypes
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 - from which to get the data types
-
Returns:
- array of data types currently available on the specified clipboard
-
Throws:
-
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(org.eclipse.swt.dnd.TransferData) ,
DND.CLIPBOARD ,
DND.SELECTION_CLIPBOARD
getAvailableTypeNames
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:
- a platform specific list of the data types currently available on the
system clipboard
-
Throws:
-
SWTException
-
- ERROR_WIDGET_DISPOSED - if the receiver has been disposed
- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
|
|
|