info.codesaway.util
Class SystemClipboard

java.lang.Object
  info.codesaway.util.SystemClipboard

public class SystemClipboard
extends Object

Utility class to simplify using the system's clipboard.

This class wraps functionality available from the Clipboard class to allow copying and retrieving a string, a list of files, or an image.

There exists methods to test if the clipboard is empty, or if not empty, if the clipboard can be represented as a string, text, a list of files, or an image.

The clear() method (or alternatively, the empty() method) provides a way to clear the clipboard, removing its contents.

Method Summary

static void	addFlavorListener(FlavorListener listener) Registers the specified FlavorListener to receive FlavorEvents from the system clipboard.
static String	asFilenames() Returns the clipboard's contents with the DataFlavor.javaFileListFlavor as a list of filenames, using the line separator string to delimit each filename.
static String	asFilenames(String delimiter) Returns the clipboard's contents with the DataFlavor.javaFileListFlavor as a list of filenames, using the specified delimiter to delimit each filename.
static List<File>	asFiles() Returns the clipboard's contents with the DataFlavor.javaFileListFlavor.
static Image	asImage() Returns the clipboard's contents with the DataFlavor.imageFlavor.
static String	asString() Returns the clipboard's contents with the DataFlavor.stringFlavor.
static String	asText() Returns the clipboard's contents as text.
static void	clear() Clears the clipboard.
static Clipboard	clipboard() Returns the system clipboard.
static void	copy(CharSequence text) Copies the given character sequence to the clipboard.
static void	copy(Collection<File> files) Copies the given files to the clipboard.
static void	copy(File... files) Copies the given files to the clipboard.
static void	copy(Image image) Copies the given image to the clipboard.
static void	empty() Clears the clipboard.
static DataFlavor[]	getAvailableDataFlavors() Returns an array of DataFlavors in which the current contents of the system clipboard can be provided.
static Object	getClipboard(DataFlavor flavor) Returns the system clipboard's contents in the requested DataFlavor if possible.
static Transferable	getContents(Object requestor) Returns a transferable object representing the current contents of the system clipboard.
static Object	getData(DataFlavor flavor) Returns an object representing the current contents of the system clipboard in the specified DataFlavor.
static FlavorListener[]	getFlavorListeners() Returns an array of all the FlavorListeners currently registered on the system clipboard.
static String	getName() Returns the name of the system clipboard.
static boolean	isDataFlavorAvailable(DataFlavor flavor) Returns whether or not the current contents of the system clipboard can be provided in the specified DataFlavor.
static boolean	isEmpty() Returns true if, and only if, getAvailableDataFlavors().length is 0.
static boolean	isFiles() Returns whether the clipboard's contents can be represented as a List of Files.
static boolean	isImage() Returns whether the clipboard's contents can be represented as an Image.
static boolean	isString() Returns whether the clipboard's contents can be represented as a String.
static boolean	isText() Returns whether the clipboard's contents can be represented as text.
static void	removeFlavorListener(FlavorListener listener) Removes the specified FlavorListener so that it no longer receives FlavorEvents from the system clipboard.
static void	setContents(Transferable contents, ClipboardOwner owner) Sets the current contents of the system clipboard to the specified transferable object and registers the specified clipboard owner as the owner of the new contents.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

clear

public static void clear()

Clears the clipboard.

empty

public static void empty()

Clears the clipboard. This method is identical to clear().

isEmpty

public static boolean isEmpty()

Returns true if, and only if, getAvailableDataFlavors().length is 0.

Returns:

true if getAvailableDataFlavors().length is 0, otherwise false

copy

public static void copy(CharSequence text)

Copies the given character sequence to the clipboard. DataFlavor.stringFlavor is the DataFlavor used for the copy operation.

Note: if text is null, the clipboard will be cleared instead.

Parameters:

text - the character sequence to copy

copy

public static void copy(File... files)

Copies the given files to the clipboard. DataFlavor.javaFileListFlavor is the DataFlavor used for the copy operation.

Note: if files is null, the clipboard will be cleared instead.

Parameters:

files - the Files to copy

copy

public static void copy(Collection<File> files)

Copies the given files to the clipboard. DataFlavor.javaFileListFlavor is the DataFlavor used for the copy operation.

Note: if files is null, the clipboard will be cleared instead.

Parameters:

files - the Files to copy

copy

public static void copy(Image image)

Copies the given image to the clipboard. DataFlavor.imageFlavor is the DataFlavor used for the copy operation.

Note: if image is null, the clipboard will be cleared instead.

Parameters:

image - the Image to copy

asText

public static String asText()

Returns the clipboard's contents as text.

For a String, this is the string itself. For a List of Files, it is the list of the filenames, using the line separator string to delimit each filename.

The line separator string is defined by the system property line.separator, and is not necessarily a single newline character ('\n').

Returns:

the clipboard's contents as text, or null if the clipboard's contents cannot be expressed as text.

See Also:

asString(), asFilenames(), System.getProperty(String)

isText

public static boolean isText()

Returns whether the clipboard's contents can be represented as text.

Returns:

true if the current clipboard contents can be provided as either DataFlavor.stringFlavor or DataFlavor.javaFileListFlavor; false otherwise

asString

public static String asString()

Returns the clipboard's contents with the DataFlavor.stringFlavor.

Returns:

the clipboard's contents if they can be expressed as a String, or null if they cannot.

isString

public static boolean isString()

Returns whether the clipboard's contents can be represented as a String.

Returns:

true if the current clipboard contents can be provided as DataFlavor.stringFlavor; false otherwise

asFiles

public static List<File> asFiles()

Returns the clipboard's contents with the DataFlavor.javaFileListFlavor.

Note: the returned list cannot be modified - an UnsupportedOperationException will be thrown if any attempt is made. This is done to prevent modification to the clipboard's internal data, since such modifications do not change the clipboard. However, you can create a new list containing the returned files, modify this new list, and copy it at a later time - this will set the clipboard (to the new list's contents).

Returns:

the clipboard's contents if they can be expressed as a List of Files, or null if they cannot.

isFiles

public static boolean isFiles()

Returns whether the clipboard's contents can be represented as a List of Files.

Returns:

true if the current clipboard contents can be provided as DataFlavor.javaFileListFlavor; false otherwise

asFilenames

public static String asFilenames()

Returns the clipboard's contents with the DataFlavor.javaFileListFlavor as a list of filenames, using the line separator string to delimit each filename.

The line separator string is defined by the system property line.separator, and is not necessarily a single newline character ('\n').

Returns:

the clipboard's contents if they can be expressed as a list of filenames, or null if they cannot.

See Also:

System.getProperty(String)

asFilenames

public static String asFilenames(String delimiter)

Returns the clipboard's contents with the DataFlavor.javaFileListFlavor as a list of filenames, using the specified delimiter to delimit each filename.

Parameters:

delimiter - the string used to delimit each filename

Returns:

the clipboard's contents if they can be expressed as a list of filenames, or null if they cannot.

asImage

public static Image asImage()

Returns the clipboard's contents with the DataFlavor.imageFlavor.

Returns:

the clipboard's contents if they can be expressed as an Image, or null if they cannot.

isImage

public static boolean isImage()

Returns whether the clipboard's contents can be represented as an Image.

Returns:

true if the current clipboard contents can be provided as DataFlavor.imageFlavor; false otherwise

clipboard

public static Clipboard clipboard()

Returns the system clipboard.

Returns:

the system clipboard

addFlavorListener

public static void addFlavorListener(FlavorListener listener)

Registers the specified FlavorListener to receive FlavorEvents from the system clipboard. If listener is null, no exception is thrown and no action is performed.

Parameters:

listener - the listener to be added

See Also:

removeFlavorListener(java.awt.datatransfer.FlavorListener), getFlavorListeners(), FlavorListener, FlavorEvent

getAvailableDataFlavors

public static DataFlavor[] getAvailableDataFlavors()

Returns an array of DataFlavors in which the current contents of the system clipboard can be provided. If there are no DataFlavors available, this method returns a zero-length array.

Returns:

an array of DataFlavors in which the current contents of the system clipboard can be provided

Throws:

IllegalStateException - if the system clipboard is currently unavailable

getContents

public static Transferable getContents(Object requestor)

Returns a transferable object representing the current contents of the system clipboard. If the clipboard currently has no contents, it returns null. The parameter Object requestor is not currently used. The method throws IllegalStateException if the clipboard is currently unavailable. For example, on some platforms, the system clipboard is unavailable while it is accessed by another application.

Parameters:

requestor - the object requesting the clip data (not used)

Returns:

the current transferable object on the clipboard

Throws:

IllegalStateException - if the clipboard is currently unavailable

See Also:

Toolkit.getSystemClipboard()

getClipboard

public static Object getClipboard(DataFlavor flavor)

Returns the system clipboard's contents in the requested DataFlavor if possible.

Parameters:

flavor - the requested flavor for the data

Returns:

the data in the requested flavor, or null if the data doesn't support the given DataFlavor

Throws:

NullPointerException - if flavor is null

getData

public static Object getData(DataFlavor flavor)
                      throws UnsupportedFlavorException,
                             IOException

Returns an object representing the current contents of the system clipboard in the specified DataFlavor. The class of the object returned is defined by the representation class of flavor.

Parameters:

flavor - the requested DataFlavor for the contents

Returns:

an object representing the current contents of the system clipboard in the specified DataFlavor

Throws:

NullPointerException - if flavor is null

IllegalStateException - if this clipboard is currently unavailable

UnsupportedFlavorException - if the requested DataFlavor is not available

IOException - if the data in the requested DataFlavor can not be retrieved

See Also:

DataFlavor.getRepresentationClass()

getFlavorListeners

public static FlavorListener[] getFlavorListeners()

Returns an array of all the FlavorListeners currently registered on the system clipboard.

Returns:

all of the system clipboard's FlavorListeners or an empty array if no listeners are currently registered

See Also:

addFlavorListener(java.awt.datatransfer.FlavorListener), removeFlavorListener(java.awt.datatransfer.FlavorListener), FlavorListener, FlavorEvent

getName

public static String getName()

Returns the name of the system clipboard.

Returns:

the name of the system clipboard

See Also:

Toolkit.getSystemClipboard()

isDataFlavorAvailable

public static boolean isDataFlavorAvailable(DataFlavor flavor)

Returns whether or not the current contents of the system clipboard can be provided in the specified DataFlavor.

Parameters:

flavor - the requested DataFlavor for the contents

Returns:

true if the current contents of the system clipboard can be provided in the specified DataFlavor; false otherwise

Throws:

NullPointerException - if flavor is null

IllegalStateException - if the system clipboard is currently unavailable

removeFlavorListener

public static void removeFlavorListener(FlavorListener listener)

Removes the specified FlavorListener so that it no longer receives FlavorEvents from the system clipboard. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to the system clipboard. If listener is null, no exception is thrown and no action is performed.

Parameters:

listener - the listener to be removed

See Also:

addFlavorListener(java.awt.datatransfer.FlavorListener), getFlavorListeners(), FlavorListener, FlavorEvent

setContents

public static void setContents(Transferable contents,
                               ClipboardOwner owner)

Sets the current contents of the system clipboard to the specified transferable object and registers the specified clipboard owner as the owner of the new contents.

If there is an existing owner different from the argument owner, that owner is notified that it no longer holds ownership of the clipboard contents via an invocation of ClipboardOwner.lostOwnership() on that owner. An implementation of setContents() is free not to invoke lostOwnership() directly from this method. For example, lostOwnership() may be invoked later on a different thread. The same applies to FlavorListeners registered on this clipboard.

The method throws IllegalStateException if the clipboard is currently unavailable. For example, on some platforms, the system clipboard is unavailable while it is accessed by another application.

Parameters:

contents - the transferable object representing the clipboard content

owner - the object which owns the clipboard content

Throws:

IllegalStateException - if the system clipboard is currently unavailable

See Also:

Toolkit.getSystemClipboard()