chemaxon.marvin.modules.datatransfer

Class ClipboardHandler

java.lang.Object

chemaxon.marvin.modules.datatransfer.ClipboardHandler

@PublicAPI
public final class ClipboardHandler
extends java.lang.Object

Facade of the Clipboard handling in Marvin.

Utility class that can be used to transfer Molecule or other data from Marvin to the system clipboard using cut/copy/paste operations.

Since:

Marvin 5.3 11/25/2009

Author:

Istvan Fajth

Method Summary

Modifier and Type	Method and Description
static void	addTransferable(java.lang.String name, java.lang.String className, java.lang.Integer priority, java.lang.Integer inputPriority, boolean isdefault, boolean copyAsTransferable) Deprecated. use addTransferable(String, String, Integer, Integer, boolean, boolean, boolean) instead.
static void	addTransferable(java.lang.String name, java.lang.String className, java.lang.Integer priority, java.lang.Integer inputPriority, boolean isdefault, boolean copyAsTransferable, boolean dndTransferable) Add a TransferableDescriptor to the registry, and constructing it by the given parameters.
static void	addTransferable(TransferableDescriptor d) Add a TransferableDescriptor to the MTransferable Registry.
static void	clearClipboard() Clears the clipboard by creating an empty Transferable and placing it on the clipboard.
static void	clearClipboardConditionally() Clears the clipboard, if isClearClipboardBeforeExport() is true.
static boolean	convert(chemaxon.marvin.modules.datatransfer.TransferDataImporter converter) Convert transfer data available on clipboard in one of the requested flavors.
static java.awt.datatransfer.Clipboard	getClipboard() Returns the default Toolkit's system clipboard if available, otherwise returns a new singleton clipboard instance.
static java.awt.datatransfer.Transferable	getClipboardContents() Inits and return the transferable of the Clipboard for later import.
static java.util.List<java.lang.String>	getCopyAsTransferableNames() Returns the format's names that are available in the current environment as transfer types for the Copy As dialog.
static java.lang.Object	getObjectFromClipboard() Returns the current content of the clipboard if the data can be imported in any of data formats supported by MolImporter.
static java.lang.Object	getObjectFromClipboard(java.lang.String imageImportServiceURL) Returns the current content of the clipboard if the data can be imported in any of data formats supported by MolImporter.
static java.lang.Object	getObjectFromTransferable(java.awt.datatransfer.Transferable transfer) Returns the content of Transferable if the data can be imported in any of data formats supported by MolImporter.
static java.lang.Object	getObjectFromTransferable(java.awt.datatransfer.Transferable transfer, java.lang.String imageImportServiceURL) Returns the content of Transferable if the data can be imported in any of data formats supported by MolImporter.
static java.lang.String	getStringFromClipboard() Returns the String data from the clipboard contents, if the clipboard contains a Transferable that provides support to DataFlavor.stringFlavor
static java.awt.datatransfer.Transferable	getTransferableFor(Molecule mol, java.util.Properties props) Creates a MTransferable object to the given Molecule with the given properties.
static java.awt.datatransfer.Transferable	getTransferableFor(Molecule mol, java.util.Properties props, java.lang.String fmt) Creates a MTransferable to the given Molecule with the given properties in the given format.
static boolean	getWorkOnBackGround() Returns whether the subsystem works on the current thread or on a background thread.
static boolean	isClearClipboardBeforeExport() Returns whether the subsystem clears the clipboard before a copy operation.
static boolean	isSupportedTransferFormat(java.lang.String fmtId) Checks whether the given format is available in the current environment or not.
static void	putFormattedTextToClipboard(javax.swing.text.Document doc, int start, int end) Deprecated.
static void	putImageToClipboard(java.awt.Image img) Places the given Image to the clipboard.
static void	putMoleculeToClipboard(Molecule mol, java.util.Properties props) Places a Molecule object to the clipboard which is represented as a Transferable being configured to support all the default Transfer types of Marvin.
static void	putMoleculeToClipboard(Molecule mol, java.util.Properties props, java.lang.String fmt) Places a Molecule object to the clipboard which is represented as a Transferable configured to support the transfer types of the specified format identifier.
static void	putOLEToClipboard(Molecule mol, java.util.Properties props)
static void	putStringToClipboard(java.lang.String str) Places the given String to the clipboard as a StringSelection.
static void	putTransferableToClipboard(java.awt.datatransfer.Transferable t) A generic way to put content to clipboard.
static void	releasePermanentResources() Releases all clipboard related native libraries and resources.
static void	removeOLESupport() Removing the support of OLE transfer format.
static TransferableDescriptor	removeTransferable(java.lang.String name) Removes a TransferableDescriptor to the MTransferable Registry by name.
static TransferableDescriptor	removeTransferable(TransferableDescriptor d) Removes a TransferableDescriptor to the MTransferable Registry.
static void	setClearClipboardBeforeExport(boolean b) Sets whether the subsystem should clear the clipboard before a copy operation.
static void	setWorkOnBackground(boolean b) Starts or stops the background worker thread and ensures the required state for the type of work.
static void	startPermanentResources() Starts all the permanent native resources that have to be started to do fast and reliable copy in Marvin.

Methods inherited from class java.lang.Object

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

Method Detail

setWorkOnBackground

public static void setWorkOnBackground(boolean b)

Starts or stops the background worker thread and ensures the required state for the type of work. If it previously worked in the background then waits for the previously submitted tasks to finish.
It defaults to false.

Parameters:

b - true means working in the background, false means working on the current thread.

getWorkOnBackGround

public static boolean getWorkOnBackGround()

Returns whether the subsystem works on the current thread or on a background thread.

Returns:

true if it works on the current thread false otherwise.

setClearClipboardBeforeExport

public static void setClearClipboardBeforeExport(boolean b)

Sets whether the subsystem should clear the clipboard before a copy operation. The default value is true.

Parameters:

b - true or false

isClearClipboardBeforeExport

public static boolean isClearClipboardBeforeExport()

Returns whether the subsystem clears the clipboard before a copy operation.

Returns:

true if the clipboard is cleared before a copy operation false otherwise.

putStringToClipboard

public static void putStringToClipboard(java.lang.String str)

Places the given String to the clipboard as a StringSelection. When processing on a background thread, this method will continuously try to put the String to the clipboard until the operation has succeeded.

Parameters:

str - the String to be placed to the clipboard

Throws:

java.lang.IllegalStateException - if the clipboard is currently unavailable, and running on the current thread.

putFormattedTextToClipboard

@Deprecated
public static void putFormattedTextToClipboard(javax.swing.text.Document doc,
                                                           int start,
                                                           int end)

Deprecated.

Method to place HTMLDocument on clipboard. Use putTransferableToClipboard() instead.

Parameters:

doc -

start -

end -

putImageToClipboard

public static void putImageToClipboard(java.awt.Image img)

Places the given Image to the clipboard. When processing on a background thread, this method will continuously try to put the String to the clipboard until the operation has succeeded.

Parameters:

img - the Image to be placed to the clipboard

Throws:

java.lang.IllegalStateException - if the clipboard is currently unavailable, and running on the current thread.

putMoleculeToClipboard

public static void putMoleculeToClipboard(Molecule mol,
                                          java.util.Properties props)

Places a Molecule object to the clipboard which is represented as a Transferable being configured to support all the default Transfer types of Marvin. When processing on a background thread, this method will continuously try to put the String to the clipboard until the operation has succeeded.

Parameters:

mol - the Molecule to be placed to the clipboard

props - display properties of the Molecule, this parameter will be used when transferring Molecule images to clipboard, and can be one of, or the union of properties stored in UserSettings, and in the result of MDocument.getGUIPropertyContainer()

Throws:

java.lang.IllegalStateException - if the clipboard is currently unavailable, and running on the current thread.

See Also:

ImageExportUtil

putMoleculeToClipboard

public static void putMoleculeToClipboard(Molecule mol,
                                          java.util.Properties props,
                                          java.lang.String fmt)

Places a Molecule object to the clipboard which is represented as a Transferable configured to support the transfer types of the specified format identifier. When processing on a background thread, this method will continuously try to put the String to the clipboard until the operation has succeeded.

Parameters:

mol - the Molecule to be placed to the clipboard

props - display properties of the Molecule, this parameter is useful when transferring Molecule images to clipboard, and can be one of, or the union of properties stored in UserSettings, and in the result of MDocument.getGUIPropertyContainer()

fmt - format identifier in which the data will be represented on the clipboard. It can be null in which case the Molecule will be transferred in the default formats.

Throws:

java.lang.IllegalStateException - if the clipboard is currently unavailable, and running on the current thread.

See Also:

ImageExportUtil

putOLEToClipboard

public static void putOLEToClipboard(Molecule mol,
                                     java.util.Properties props)

putTransferableToClipboard

public static void putTransferableToClipboard(java.awt.datatransfer.Transferable t)

A generic way to put content to clipboard.

Parameters:

t -

convert

public static boolean convert(chemaxon.marvin.modules.datatransfer.TransferDataImporter converter)

Convert transfer data available on clipboard in one of the requested flavors. Converter defines what flavors it supports, steps through that list and tries to find one that is available on the clipboard.

Parameters:

converter -

Returns:

removeOLESupport

public static void removeOLESupport()

Removing the support of OLE transfer format.

getStringFromClipboard

public static java.lang.String getStringFromClipboard()

Returns the String data from the clipboard contents, if the clipboard contains a Transferable that provides support to DataFlavor.stringFlavor

Returns:

the String from the clipboard.

getObjectFromClipboard

public static java.lang.Object getObjectFromClipboard()
                                               throws java.io.IOException

Returns the current content of the clipboard if the data can be imported in any of data formats supported by MolImporter. If the clipboard represents a Molecule, the returned object will be an instance of Molecule, if the clipboard represents a MacroMolecule used by MarvinSpace, then the returned object will be an instance of MacroMolecule, otherwise the function returns null.

Returns:

the molecule represented on the clipboard, null if molecule representation cannot be found

Throws:

java.io.IOException

getObjectFromClipboard

public static java.lang.Object getObjectFromClipboard(java.lang.String imageImportServiceURL)
                                               throws java.io.IOException

Returns the current content of the clipboard if the data can be imported in any of data formats supported by MolImporter. If the clipboard represents a Molecule, the returned object will be an instance of Molecule, if the clipboard represents a MacroMolecule used by MarvinSpace, then the returned object will be an instance of MacroMolecule, otherwise the function returns null.

Parameters:

imageImportServiceURL - if it points to a working http based image import service url the importer will use that service when importing images from clipboard.

Returns:

the molecule represented on the clipboard, null if molecule representation cannot be found

Throws:

java.io.IOException

getClipboardContents

public static java.awt.datatransfer.Transferable getClipboardContents()

Inits and return the transferable of the Clipboard for later import.

Returns:

the contents of the clipboard as a Transferable object.

getObjectFromTransferable

public static java.lang.Object getObjectFromTransferable(java.awt.datatransfer.Transferable transfer)
                                                  throws java.io.IOException

Returns the content of Transferable if the data can be imported in any of data formats supported by MolImporter. If the clipboard represents a Molecule, the returned object will be an instanceof Molecule, if the clipboard represents a MacroMolecule used by MarvinSpace, then the returned object will be an instanceof MacroMolecule, otherwise the function returns null.

Parameters:

transfer - the Transferable which represents the data

Returns:

the molecule represented in the Transferable, null if molecule representation cannot be found

Throws:

java.io.IOException

getObjectFromTransferable

public static java.lang.Object getObjectFromTransferable(java.awt.datatransfer.Transferable transfer,
                                                         java.lang.String imageImportServiceURL)
                                                  throws java.io.IOException

Returns the content of Transferable if the data can be imported in any of data formats supported by MolImporter. If the clipboard represents a Molecule, the returned object will be an instanceof Molecule, if the clipboard represents a MacroMolecule used by MarvinSpace, then the returned object will be an instanceof MacroMolecule, otherwise the function returns null.

Parameters:

transfer - the Transferable which represents the data

imageImportServiceURL - if it points to a working http based image import service url the importer will use that service when importing images from clipboard.

Returns:

the molecule represented in the Transferable, null if molecule representation cannot be found

Throws:

java.io.IOException

getTransferableFor

public static java.awt.datatransfer.Transferable getTransferableFor(Molecule mol,
                                                                    java.util.Properties props)

Creates a MTransferable object to the given Molecule with the given properties.

Parameters:

mol - the Molecule which has to be represented by the Transferable

props - display properties of the Molecule, this parameter will be used when transferring Molecule images to clipboard, and can be one of, or the union of properties stored in UserSettings, and in the result of MDocument.getGUIPropertyContainer()

Returns:

the Transferable created from the given data.

See Also:

ImageExportUtil

getTransferableFor

public static java.awt.datatransfer.Transferable getTransferableFor(Molecule mol,
                                                                    java.util.Properties props,
                                                                    java.lang.String fmt)

Creates a MTransferable to the given Molecule with the given properties in the given format.

Parameters:

mol - the Molecule which has to be represented by the Transferable

props - display properties of the Molecule, this parameter will be used when transferring Molecule images to clipboard, and can be one of, or the union of properties stored in UserSettings, and in the result of MDocument.getGUIPropertyContainer()

fmt - format identifier in which the data will be represented on the clipboard. It can be null in which case the Molecule will be transferred in the default formats. If null is given, the default will be used.

Returns:

the Transferable created from the given data.

See Also:

ImageExportUtil

isSupportedTransferFormat

public static boolean isSupportedTransferFormat(java.lang.String fmtId)

Checks whether the given format is available in the current environment or not.

Parameters:

fmtId - the format identifier

Returns:

true if the format is available

getCopyAsTransferableNames

public static java.util.List<java.lang.String> getCopyAsTransferableNames()

Returns the format's names that are available in the current environment as transfer types for the Copy As dialog.

Returns:

List list of the the copy as dialog format's names

clearClipboard

public static void clearClipboard()

Clears the clipboard by creating an empty Transferable and placing it on the clipboard.

clearClipboardConditionally

public static void clearClipboardConditionally()

Clears the clipboard, if isClearClipboardBeforeExport() is true.

getClipboard

public static java.awt.datatransfer.Clipboard getClipboard()

Returns the default Toolkit's system clipboard if available, otherwise returns a new singleton clipboard instance.

Returns:

the system clipboard or a local clipboard instance.

See Also:

Toolkit.getSystemClipboard()

removeTransferable

public static TransferableDescriptor removeTransferable(TransferableDescriptor d)

Removes a TransferableDescriptor to the MTransferable Registry.

Parameters:

d - the descriptor.

Returns:

the descriptor which has been removed.

removeTransferable

public static TransferableDescriptor removeTransferable(java.lang.String name)

Removes a TransferableDescriptor to the MTransferable Registry by name.

Parameters:

name - the name of the MTransferable

Returns:

the descriptor which has been removed.

addTransferable

public static void addTransferable(TransferableDescriptor d)

Add a TransferableDescriptor to the MTransferable Registry.

Parameters:

d - the descriptor.

addTransferable

@Deprecated
public static void addTransferable(java.lang.String name,
                                               java.lang.String className,
                                               java.lang.Integer priority,
                                               java.lang.Integer inputPriority,
                                               boolean isdefault,
                                               boolean copyAsTransferable)

Deprecated. use addTransferable(String, String, Integer, Integer, boolean, boolean, boolean) instead.

Add a TransferableDescriptor to the registry, and constructing it by the given parameters.

addTransferable

public static void addTransferable(java.lang.String name,
                                   java.lang.String className,
                                   java.lang.Integer priority,
                                   java.lang.Integer inputPriority,
                                   boolean isdefault,
                                   boolean copyAsTransferable,
                                   boolean dndTransferable)

Add a TransferableDescriptor to the registry, and constructing it by the given parameters.

Parameters:

name - of the MTransferable represented by the descriptor.

className - The representing class name of the MTransferable represented by the descriptor.

priority - priority on the Copy as dialog of the MTransferable represented by the descriptor.

inputPriority - priority used when importing with the help of the MTransferable represented by the descriptor.

isdefault - decides whether the MTransferable should be used in default copy.

copyAsTransferable - decides whether the MTrasnferable should be displayed in the copy as dialog.

dndTransferable - flag to indicate whether the transferable is used when importing data from a dropped object

releasePermanentResources

public static void releasePermanentResources()

Releases all clipboard related native libraries and resources. Waits background workers to finish before releasing.

startPermanentResources

public static void startPermanentResources()

Starts all the permanent native resources that have to be started to do fast and reliable copy in Marvin.