javax.swing
Class TransferHandler

java.lang.Object
  javax.swing.TransferHandler

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

BasicColorChooserUI.ColorTransferHandler, BasicFileChooserUI.FileTransferHandler, BasicListUI.ListTransferHandler, BasicTableUI.TableTransferHandler, BasicTextUI.TextTransferHandler, BasicTreeUI.TreeTransferHandler, JTextComponent.DefaultTransferHandler

public class TransferHandler

extends Object

implements Serializable

This class is used to handle the transfer of a Transferable to and from Swing components. The Transferable is used to represent data that is exchanged via a cut, copy, or paste to/from a clipboard. It is also used in drag-and-drop operations to represent a drag from a component, and a drop to a component. Swing provides functionality that automatically supports cut, copy, and paste keyboard bindings that use the functionality provided by an implementation of this class. Swing also provides functionality that automatically supports drag and drop that uses the functionality provided by an implementation of this class. The Swing developer can concentrate on specifying the semantics of a transfer primarily by setting the transferHandler property on a Swing component.

This class is implemented to provide a default behavior of transferring a component property simply by specifying the name of the property in the constructor. For example, to transfer the foreground color from one component to another either via the clipboard or a drag and drop operation a TransferHandler can be constructed with the string "foreground". The built in support will use the color returned by getForeground as the source of the transfer, and setForeground for the target of a transfer.

Author:

Timothy Prinzing

See Also:

Serialized Form

Nested Class Summary

private static class	TransferHandler.DragHandler This is the default drag handler for drag and drop operations that use the TransferHandler.
private static class	TransferHandler.DropHandler
(package private) static class	TransferHandler.PropertyTransferable
private static class	TransferHandler.SwingDragGestureRecognizer
(package private) static class	TransferHandler.SwingDropTarget This is the default drop target for drag and drop operations if one isn't provided by the developer.
(package private) static class	TransferHandler.TransferAction

Field Summary

static int	COPY An int representing a "copy" transfer action.
static int	COPY_OR_MOVE An int representing a source action capability of either "copy" or "move".
(package private) static Action	copyAction
(package private) static Action	cutAction
private static DropTargetListener	dropLinkage
private static int	LINK An int representing a "link" transfer action.
static int	MOVE An int representing a "move" transfer action.
static int	NONE An int representing no transfer action.
(package private) static Action	pasteAction
private String	propertyName
private static TransferHandler.SwingDragGestureRecognizer	recognizer

Constructor Summary

protected	TransferHandler() Convenience constructor for subclasses.
	TransferHandler(String property) Constructs a transfer handler that can transfer a Java Bean property from one component to another via the clipboard or a drag and drop operation.

Method Summary

boolean	canImport(JComponent comp, DataFlavor[] transferFlavors) Indicates whether a component would accept an import of the given set of data flavors prior to actually attempting to import it.
protected Transferable	createTransferable(JComponent c) Creates a Transferable to use as the source for a data transfer.
void	exportAsDrag(JComponent comp, InputEvent e, int action) Causes the Swing drag support to be initiated.
protected void	exportDone(JComponent source, Transferable data, int action) Invoked after data has been exported.
void	exportToClipboard(JComponent comp, Clipboard clip, int action) Causes a transfer from the given component to the given clipboard.
static Action	getCopyAction() Returns an Action that behaves like a 'copy' operation.
static Action	getCutAction() Returns an Action that behaves like a 'cut' operation.
private static DropTargetListener	getDropTargetListener()
static Action	getPasteAction() Returns an Action that behaves like a 'paste' operation.
private DataFlavor	getPropertyDataFlavor(Class k, DataFlavor[] flavors) Fetches the data flavor from the array of possible flavors that has data of the type represented by property type.
private java.beans.PropertyDescriptor	getPropertyDescriptor(JComponent comp) Fetches the property descriptor for the property assigned to this transfer handler on the given component (transfer handler may be shared).
int	getSourceActions(JComponent c) Returns the type of transfer actions supported by the source.
Icon	getVisualRepresentation(Transferable t) Returns an object that establishes the look of a transfer.
boolean	importData(JComponent comp, Transferable t) Causes a transfer to a component from a clipboard or a DND drop operation.

Methods inherited from class java.lang.Object

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

Field Detail

NONE

public static final int NONE

An int representing no transfer action.

See Also:

Constant Field Values

COPY

public static final int COPY

An int representing a "copy" transfer action. This value is used when data is copied to a clipboard or copied elsewhere in a drag and drop operation.

See Also:

Constant Field Values

MOVE

public static final int MOVE

An int representing a "move" transfer action. This value is used when data is moved to a clipboard (i.e. a cut) or moved elsewhere in a drag and drop operation.

See Also:

Constant Field Values

COPY_OR_MOVE

public static final int COPY_OR_MOVE

An int representing a source action capability of either "copy" or "move".

See Also:

Constant Field Values

LINK

private static final int LINK

An int representing a "link" transfer action. This value is used to specify that data should be linked in a drag and drop operation.

See Also:

Constant Field Values

propertyName

private String propertyName

recognizer

private static TransferHandler.SwingDragGestureRecognizer recognizer

dropLinkage

private static DropTargetListener dropLinkage

cutAction

static final Action cutAction

copyAction

static final Action copyAction

pasteAction

static final Action pasteAction

Constructor Detail

TransferHandler

public TransferHandler(String property)

Constructs a transfer handler that can transfer a Java Bean property from one component to another via the clipboard or a drag and drop operation.

Parameters:

property - the name of the property to transfer; this can be null if there is no property associated with the transfer handler (a subclass that performs some other kind of transfer, for example)

TransferHandler

protected TransferHandler()

Convenience constructor for subclasses.

Method Detail

getCutAction

public static Action getCutAction()

Returns an Action that behaves like a 'cut' operation. That is, this will invoke exportToClipboard with a MOVE argument on the TransferHandler associated with the JComponent that is the source of the ActionEvent.

Returns:

cut Action

getCopyAction

public static Action getCopyAction()

Returns an Action that behaves like a 'copy' operation. That is, this will invoke exportToClipboard with a COPY argument on the TransferHandler associated with the JComponent that is the source of the ActionEvent.

Returns:

cut Action

getPasteAction

public static Action getPasteAction()

Returns an Action that behaves like a 'paste' operation. That is, this will invoke importData on the TransferHandler associated with the JComponent that is the source of the ActionEvent.

Returns:

cut Action

exportAsDrag

public void exportAsDrag(JComponent comp,
                         InputEvent e,
                         int action)

Causes the Swing drag support to be initiated. This is called by the various UI implementations in the javax.swing.plaf.basic package if the dragEnabled property is set on the component. This can be called by custom UI implementations to use the Swing drag support. This method can also be called by a Swing extension written as a subclass of JComponent to take advantage of the Swing drag support.

The transfer will not necessarily have been completed at the return of this call (i.e. the call does not block waiting for the drop). The transfer will take place through the Swing implementation of the java.awt.dnd mechanism, requiring no further effort from the developer. The exportDone method will be called when the transfer has completed.

Parameters:

comp - the component holding the data to be transferred; this argument is provided to enable sharing of TransferHandlers by multiple components

e - the event that triggered the transfer

action - the transfer action initially requested; this should be a value of either COPY or MOVE; the value may be changed during the course of the drag operation

exportToClipboard

public void exportToClipboard(JComponent comp,
                              Clipboard clip,
                              int action)

Causes a transfer from the given component to the given clipboard. This method is called by the default cut and copy actions registered in a component's action map.

The transfer will have been completed at the return of this call. The transfer will take place using the java.awt.datatransfer mechanism, requiring no further effort from the developer. The exportDone method will be called when the transfer has completed.

Parameters:

comp - the component holding the data to be transferred; this argument is provided to enable sharing of TransferHandlers by multiple components

clip - the clipboard to transfer the data into

action - the transfer action requested; this should be a value of either COPY or MOVE; the operation performed is the intersection of the transfer capabilities given by getSourceActions and the requested action; the intersection may result in an action of NONE if the requested action isn't supported

importData

public boolean importData(JComponent comp,
                          Transferable t)

Causes a transfer to a component from a clipboard or a DND drop operation. The Transferable represents the data to be imported into the component.

Parameters:

comp - the component to receive the transfer; this argument is provided to enable sharing of TransferHandlers by multiple components

t - the data to import

Returns:

true if the data was inserted into the component, false otherwise

canImport

public boolean canImport(JComponent comp,
                         DataFlavor[] transferFlavors)

Indicates whether a component would accept an import of the given set of data flavors prior to actually attempting to import it.

Parameters:

comp - the component to receive the transfer; this argument is provided to enable sharing of TransferHandlers by multiple components

transferFlavors - the data formats available

Returns:

true if the data can be inserted into the component, false otherwise

getSourceActions

public int getSourceActions(JComponent c)

Returns the type of transfer actions supported by the source. Some models are not mutable, so a transfer operation of COPY only should be advertised in that case.

Parameters:

c - the component holding the data to be transferred; this argument is provided to enable sharing of TransferHandlers by multiple components.

Returns:

COPY if the transfer property can be found, otherwise returns NONE; a return value of of NONE disables any transfers out of the component

getVisualRepresentation

public Icon getVisualRepresentation(Transferable t)

Returns an object that establishes the look of a transfer. This is useful for both providing feedback while performing a drag operation and for representing the transfer in a clipboard implementation that has a visual appearance. The implementation of the Icon interface should not alter the graphics clip or alpha level. The icon implementation need not be rectangular or paint all of the bounding rectangle and logic that calls the icons paint method should not assume the all bits are painted. null is a valid return value for this method and indicates there is no visual representation provided. In that case, the calling logic is free to represent the transferable however it wants.

The default Swing logic will not do an alpha blended drag animation if the return is null.

Parameters:

t - the data to be transferred; this value is expected to have been created by the createTransferable method

Returns:

null, indicating there is no default visual representation

createTransferable

protected Transferable createTransferable(JComponent c)

Creates a Transferable to use as the source for a data transfer. Returns the representation of the data to be transferred, or null if the component's property is null

Parameters:

c - the component holding the data to be transferred; this argument is provided to enable sharing of TransferHandlers by multiple components

Returns:

the representation of the data to be transferred, or null if the property associated with c is null

exportDone

protected void exportDone(JComponent source,
                          Transferable data,
                          int action)

Invoked after data has been exported. This method should remove the data that was transferred if the action was MOVE.

This method is implemented to do nothing since MOVE is not a supported action of this implementation (getSourceActions does not include MOVE).

Parameters:

source - the component that was the source of the data

data - The data that was transferred or possibly null if the action is NONE.

action - the actual action that was performed

getPropertyDescriptor

private java.beans.PropertyDescriptor getPropertyDescriptor(JComponent comp)

Fetches the property descriptor for the property assigned to this transfer handler on the given component (transfer handler may be shared). This returns null if the property descriptor can't be found or there is an error attempting to fetch the property descriptor.

getPropertyDataFlavor

private DataFlavor getPropertyDataFlavor(Class k,
                                         DataFlavor[] flavors)

Fetches the data flavor from the array of possible flavors that has data of the type represented by property type. Null is returned if there is no match.

getDropTargetListener

private static DropTargetListener getDropTargetListener()