- All Implemented Interfaces:
Serializable
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.
- Since:
- 1.4
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Represents a location where dropped data should be inserted.static final class
This class encapsulates all relevant details of a clipboard or drag and drop transfer, and also allows for customizing aspects of the drag and drop experience. -
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Anint
representing a "copy" transfer action.static final int
Anint
representing a source action capability of either "copy" or "move".static final int
Anint
representing a "link" transfer action.static final int
Anint
representing a "move" transfer action.static final int
Anint
representing no transfer action. -
Constructor Summary
ModifierConstructorDescriptionprotected
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
Modifier and TypeMethodDescriptionboolean
canImport
(JComponent comp, DataFlavor[] transferFlavors) Indicates whether a component will accept an import of the given set of data flavors prior to actually attempting to import it.boolean
canImport
(TransferHandler.TransferSupport support) This method is called repeatedly during a drag and drop operation to allow the developer to configure properties of, and to return the acceptability of transfers; with a return value oftrue
indicating that the transfer represented by the givenTransferSupport
(which contains all of the details of the transfer) is acceptable at the current time, and a value offalse
rejecting the transfer.protected Transferable
Creates aTransferable
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
Returns anAction
that performs copy operations to the clipboard.static Action
Returns anAction
that performs cut operations to the clipboard.Returns the drag image.Returns an anchor offset for the image to drag.static Action
Returns anAction
that performs paste operations from the clipboard.int
Returns the type of transfer actions supported by the source; any bitwise-OR combination ofCOPY
,MOVE
andLINK
.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
Causes a transfer to occur from a clipboard or a drag and drop operation.void
setDragImage
(Image img) Sets the drag image parameter.void
Sets an anchor offset for the image to drag.
-
Field Details
-
NONE
public static final int NONEAnint
representing no transfer action.- See Also:
-
COPY
public static final int COPYAnint
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:
-
MOVE
public static final int MOVEAnint
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:
-
COPY_OR_MOVE
public static final int COPY_OR_MOVEAnint
representing a source action capability of either "copy" or "move".- See Also:
-
LINK
public static final int LINKAnint
representing a "link" transfer action. This value is used to specify that data should be linked in a drag and drop operation.- Since:
- 1.6
- See Also:
-
-
Constructor Details
-
TransferHandler
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 benull
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 Details
-
getCutAction
Returns anAction
that performs cut operations to the clipboard. When performed, this action operates on theJComponent
source of theActionEvent
by invokingexportToClipboard
, with aMOVE
action, on the component'sTransferHandler
.- Returns:
- an
Action
for performing cuts to the clipboard
-
getCopyAction
Returns anAction
that performs copy operations to the clipboard. When performed, this action operates on theJComponent
source of theActionEvent
by invokingexportToClipboard
, with aCOPY
action, on the component'sTransferHandler
.- Returns:
- an
Action
for performing copies to the clipboard
-
getPasteAction
Returns anAction
that performs paste operations from the clipboard. When performed, this action operates on theJComponent
source of theActionEvent
by invokingimportData
, with the clipboard contents, on the component'sTransferHandler
.- Returns:
- an
Action
for performing pastes from the clipboard
-
setDragImage
Sets the drag image parameter. The image has to be prepared for rendering by the moment of the call. The image is stored by reference because of some performance reasons.- Parameters:
img
- an image to drag
-
getDragImage
Returns the drag image. If there is no image to drag, the returned value isnull
.- Returns:
- the reference to the drag image
-
setDragImageOffset
Sets an anchor offset for the image to drag. It can not benull
.- Parameters:
p
- aPoint
object that corresponds to coordinates of an anchor offset of the image relative to the upper left corner of the image
-
getDragImageOffset
Returns an anchor offset for the image to drag.- Returns:
- a
Point
object that corresponds to coordinates of an anchor offset of the image relative to the upper left corner of the image. The point(0,0)
returns by default.
-
exportAsDrag
Causes the Swing drag support to be initiated. This is called by the various UI implementations in thejavax.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 ofJComponent
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. TheexportDone
method will be called when the transfer has completed.- Parameters:
comp
- the component holding the data to be transferred; provided to enable sharing ofTransferHandler
se
- the event that triggered the transferaction
- the transfer action initially requested; eitherCOPY
,MOVE
orLINK
; the DnD system may change the action used during the course of the drag operation
-
exportToClipboard
public void exportToClipboard(JComponent comp, Clipboard clip, int action) throws IllegalStateException 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 take place using the
java.awt.datatransfer
mechanism, requiring no further effort from the developer. Any data transfer will be complete and theexportDone
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, theIllegalStateException
thrown byClipboard.setContents(Transferable, ClipboardOwner)
will be propagated through this method. However,exportDone
will first be called with an action ofNONE
for consistency.- Parameters:
comp
- the component holding the data to be transferred; provided to enable sharing ofTransferHandler
sclip
- the clipboard to transfer the data intoaction
- the transfer action requested; this should be a value of eitherCOPY
orMOVE
; the operation performed is the intersection of the transfer capabilities given by getSourceActions and the requested action; the intersection may result in an action ofNONE
if the requested action isn't supported- Throws:
IllegalStateException
- if the clipboard is currently unavailable- See Also:
-
importData
Causes a transfer to occur from a clipboard or a drag and drop operation. TheTransferable
to be imported and the component to transfer to are contained within theTransferSupport
.While the drag and drop implementation calls
canImport
to determine the suitability of a transfer before calling this method, the implementation of paste does not. As such, it cannot be assumed that the transfer is acceptable upon a call to this method for paste. It is recommended thatcanImport
be explicitly called to cover this case.Note: The
TransferSupport
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.- Parameters:
support
- the object containing the details of the transfer, notnull
.- Returns:
- true if the data was inserted into the component, false otherwise
- Throws:
NullPointerException
- ifsupport
isnull
- Since:
- 1.6
- See Also:
-
importData
Causes a transfer to a component from a clipboard or a DND drop operation. TheTransferable
represents the data to be imported into the component.Note: Swing now calls the newer version of
importData
that takes aTransferSupport
, which in turn calls this method (if the component in theTransferSupport
is aJComponent
). Developers are encouraged to call and override the newer version as it provides more information (and is the only version that supports use with aTransferHandler
set directly on aJFrame
or other non-JComponent
).- Parameters:
comp
- the component to receive the transfer; provided to enable sharing ofTransferHandler
st
- the data to import- Returns:
- true if the data was inserted into the component, false otherwise
- See Also:
-
canImport
This method is called repeatedly during a drag and drop operation to allow the developer to configure properties of, and to return the acceptability of transfers; with a return value oftrue
indicating that the transfer represented by the givenTransferSupport
(which contains all of the details of the transfer) is acceptable at the current time, and a value offalse
rejecting the transfer.For those components that automatically display a drop location during drag and drop, accepting the transfer, by default, tells them to show the drop location. This can be changed by calling
setShowDropLocation
on theTransferSupport
.By default, when the transfer is accepted, the chosen drop action is that picked by the user via their drag gesture. The developer can override this and choose a different action, from the supported source actions, by calling
setDropAction
on theTransferSupport
.On every call to
canImport
, theTransferSupport
contains fresh state. As such, any properties set on it must be set on every call. Upon a drop,canImport
is called one final time before calling intoimportData
. Any state set on theTransferSupport
during that last call will be available inimportData
.This method is not called internally in response to paste operations. As such, it is recommended that implementations of
importData
explicitly call this method for such cases and that this method be prepared to return the suitability of paste operations as well.Note: The
TransferSupport
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.- Parameters:
support
- the object containing the details of the transfer, notnull
.- Returns:
true
if the import can happen,false
otherwise- Throws:
NullPointerException
- ifsupport
isnull
- Since:
- 1.6
- See Also:
-
canImport
Indicates whether a component will accept an import of the given set of data flavors prior to actually attempting to import it.Note: Swing now calls the newer version of
canImport
that takes aTransferSupport
, which in turn calls this method (only if the component in theTransferSupport
is aJComponent
). Developers are encouraged to call and override the newer version as it provides more information (and is the only version that supports use with aTransferHandler
set directly on aJFrame
or other non-JComponent
).- Parameters:
comp
- the component to receive the transfer; provided to enable sharing ofTransferHandler
stransferFlavors
- the data formats available- Returns:
- true if the data can be inserted into the component, false otherwise
- See Also:
-
getSourceActions
Returns the type of transfer actions supported by the source; any bitwise-OR combination ofCOPY
,MOVE
andLINK
.Some models are not mutable, so a transfer operation of
MOVE
should not be advertised in that case. ReturningNONE
disables transfers from the component.- Parameters:
c
- the component holding the data to be transferred; provided to enable sharing ofTransferHandler
s- Returns:
COPY
if the transfer property can be found, otherwise returnsNONE
-
getVisualRepresentation
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 theIcon
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 thecreateTransferable
method- Returns:
null
, indicating there is no default visual representation
-
createTransferable
Creates aTransferable
to use as the source for a data transfer. Returns the representation of the data to be transferred, ornull
if the component's property isnull
- Parameters:
c
- the component holding the data to be transferred; provided to enable sharing ofTransferHandler
s- Returns:
- the representation of the data to be transferred, or
null
if the property associated withc
isnull
-
exportDone
Invoked after data has been exported. This method should remove the data that was transferred if the action wasMOVE
.This method is implemented to do nothing since
MOVE
is not a supported action of this implementation (getSourceActions
does not includeMOVE
).- Parameters:
source
- the component that was the source of the datadata
- The data that was transferred or possibly null if the action isNONE
.action
- the actual action that was performed
-