java.lang.Object javax.swing.TransferHandler
public class TransferHandler
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.
Please see How to Use Drag and Drop and Data Transfer , a section in The Java Tutorial, for more information.
Nested Class Summary | |
---|---|
static class |
TransferHandler.DropLocation
Represents a location where dropped data should be inserted. |
static class |
TransferHandler.TransferInfo
This class tracks and provides the information needed to decide whether or not and how to import data. |
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". |
static int |
MOVE
An int representing a "move" transfer action. |
static int |
NONE
An int representing no transfer action. |
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
Indicates whether a component will |
boolean |
canImport
(
TransferHandler.TransferInfo
Indicates whether the import represented by the given TransferInfo will be accepted, prior to actually attempting to execute the import. |
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. |
static Action |
getPasteAction
() Returns an Action that behaves like a 'paste' operation. |
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. |
boolean |
importData
(
TransferHandler.TransferInfo
Causes a transfer to occur from a clipboard or a DnD drop operation. |
boolean |
shouldIndicate
(
TransferHandler.TransferInfo
Returns whether or not the drop location should be indicated for the given transfer. |
Methods inherited from class java.lang. Object |
---|
clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait |
Field Detail |
---|
public static final int NONE
public static final int COPY
public static final int MOVE
public static final int COPY_OR_MOVE
Constructor Detail |
---|
public TransferHandler(String property)
protected TransferHandler()
Method Detail |
---|
public static Action getCutAction()
public static Action getCopyAction()
public static Action getPasteAction()
public void exportAsDrag(JComponent comp, InputEvent e, int action)
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.
public void exportToClipboard(JComponent comp, Clipboard clip, int action) throws IllegalStateException
The transfer will take place using the java.awt.datatransfer mechanism, requiring no further effort from the developer. Any data transfer will be complete and the exportDone method will be called with the action that occurred, before this method returns. Should the clipboard be unavailable when attempting to place data on it, the IllegalStateException thrown by Clipboard.setContents(Transferable, ClipboardOwner) will be propogated through this method. However, exportDone will first be called with an action of NONE for consistency.
public boolean importData ( TransferHandler.TransferInfo info)
Note: The TransferInfo object passed to this method is only valid for the duration of the method call. It is undefined what values it may contain after this method returns.
public boolean importData(JComponent comp, Transferable t)
Note: Swing now calls the newer version of importData that takes a TransferInfo, which in turn calls this method (if the component in the TransferInfo is a JComponent). Developers are encouraged to call and override the newer version as it provides more information (and is the only version that supports use with a TransferHandler set directly on a JFrame or other non-JComponent).
public boolean shouldIndicate ( TransferHandler.TransferInfo info, boolean canImport)
Note: The TransferInfo object passed to this method is only valid for the duration of the method call. It is undefined what values it may contain after this method returns.
public boolean canImport ( TransferHandler.TransferInfo info)
Note: The TransferInfo object passed to this method is only valid for the duration of the method call. It is undefined what values it may contain after this method returns.
public boolean canImport(JComponent comp, DataFlavor[] transferFlavors)
Note: Swing now calls the newer version of canImport that takes a TransferInfo, which in turn calls this method (only if the component in the TransferInfo is a JComponent). Developers are encouraged to call and override the newer version as it provides more information (and is the only version that supports use with a TransferHandler set directly on a JFrame or other non-JComponent).
public int getSourceActions(JComponent c)
public Icon getVisualRepresentation(Transferable t)
The default Swing logic will not do an alpha blended drag animation if the return is null.
protected Transferable createTransferable(JComponent c)
protected void exportDone(JComponent source, Transferable data, int action)
This method is implemented to do nothing since MOVE is not a supported action of this implementation (getSourceActions does not include MOVE).