Serializable
public class TransferHandler extends Object implements 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.
Modifier and Type | Class | Description |
---|---|---|
static class |
TransferHandler.DropLocation |
Represents a location where dropped data should be inserted. |
static final class |
TransferHandler.TransferSupport |
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. |
Modifier and Type | Field | Description |
---|---|---|
static final int |
COPY |
An int representing a "copy" transfer action. |
static final int |
COPY_OR_MOVE |
An int representing a source action capability of either "copy" or "move". |
static final int |
LINK |
An int representing a "link" transfer action. |
static final int |
MOVE |
An int representing a "move" transfer action. |
static final int |
NONE |
An int representing no transfer action. |
Modifier | Constructor | Description |
---|---|---|
protected |
Convenience constructor for subclasses. |
|
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. |
Modifier and Type | Method | Description |
---|---|---|
boolean |
canImport |
Indicates whether a component will accept an import of the given set of data flavors prior to actually attempting to import it. |
boolean |
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 of true indicating that the transfer represented by the given TransferSupport (which contains all of the details of the transfer) is acceptable at the current time, and a value of false rejecting the transfer. |
protected Transferable |
createTransferable |
Creates a Transferable to use as the source for a data transfer. |
void |
exportAsDrag |
Causes the Swing drag support to be initiated. |
protected void |
exportDone |
Invoked after data has been exported. |
void |
exportToClipboard |
Causes a transfer from the given component to the given clipboard. |
static Action |
getCopyAction() |
Returns an Action that performs copy operations to the clipboard. |
static Action |
getCutAction() |
Returns an Action that performs cut operations to the clipboard. |
Image |
getDragImage() |
Returns the drag image. |
Point |
getDragImageOffset() |
Returns an anchor offset for the image to drag. |
static Action |
getPasteAction() |
Returns an Action that performs paste operations from the clipboard. |
int |
getSourceActions |
Returns the type of transfer actions supported by the source; any bitwise-OR combination of COPY , MOVE and LINK . |
Icon |
getVisualRepresentation |
Returns an object that establishes the look of a transfer. |
boolean |
importData |
Causes a transfer to a component from a clipboard or a DND drop operation. |
boolean |
importData |
Causes a transfer to occur from a clipboard or a drag and drop operation. |
void |
setDragImage |
Sets the drag image parameter. |
void |
setDragImageOffset |
Sets an anchor offset for the image to drag. |
public static final int NONE
int
representing no transfer action.public static final int COPY
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.public static final int MOVE
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.public static final int COPY_OR_MOVE
int
representing a source action capability of either "copy" or "move".public static final int LINK
int
representing a "link" transfer action. This value is used to specify that data should be linked in a drag and drop operation.public TransferHandler(String property)
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)protected TransferHandler()
public static Action getCutAction()
Action
that performs cut operations to the clipboard. When performed, this action operates on the JComponent
source of the ActionEvent
by invoking exportToClipboard
, with a MOVE
action, on the component's TransferHandler
.Action
for performing cuts to the clipboardpublic static Action getCopyAction()
Action
that performs copy operations to the clipboard. When performed, this action operates on the JComponent
source of the ActionEvent
by invoking exportToClipboard
, with a COPY
action, on the component's TransferHandler
.Action
for performing copies to the clipboardpublic static Action getPasteAction()
Action
that performs paste operations from the clipboard. When performed, this action operates on the JComponent
source of the ActionEvent
by invoking importData
, with the clipboard contents, on the component's TransferHandler
.Action
for performing pastes from the clipboardpublic void setDragImage(Image img)
img
- an image to dragpublic Image getDragImage()
null
.public void setDragImageOffset(Point p)
null
.p
- a Point
object that corresponds to coordinates of an anchor offset of the image relative to the upper left corner of the imagepublic Point getDragImageOffset()
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.public void exportAsDrag(JComponent comp, InputEvent e, int action)
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.
comp
- the component holding the data to be transferred; provided to enable sharing of TransferHandler
se
- the event that triggered the transferaction
- the transfer action initially requested; either COPY
, MOVE
or LINK
; the DnD system may change the action used during the course of the drag operationpublic 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 propagated through this method. However, exportDone
will first be called with an action of NONE
for consistency.
comp
- the component holding the data to be transferred; provided to enable sharing of TransferHandler
sclip
- the clipboard to transfer the data intoaction
- 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 supportedIllegalStateException
- if the clipboard is currently unavailablepublic boolean importData(TransferHandler.TransferSupport support)
Transferable
to be imported and the component to transfer to are contained within the TransferSupport
. 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 that canImport
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.
support
- the object containing the details of the transfer, not null
.NullPointerException
- if support
is null
public boolean importData(JComponent comp, Transferable t)
Transferable
represents the data to be imported into the component. Note: Swing now calls the newer version of importData
that takes a TransferSupport
, which in turn calls this method (if the component in the TransferSupport
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
).
comp
- the component to receive the transfer; provided to enable sharing of TransferHandler
st
- the data to importpublic boolean canImport(TransferHandler.TransferSupport support)
true
indicating that the transfer represented by the given TransferSupport
(which contains all of the details of the transfer) is acceptable at the current time, and a value of false
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 the TransferSupport
.
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 the TransferSupport
.
On every call to canImport
, the TransferSupport
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 into importData
. Any state set on the TransferSupport
during that last call will be available in importData
.
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.
support
- the object containing the details of the transfer, not null
.true
if the import can happen, false
otherwiseNullPointerException
- if support
is null
public boolean canImport(JComponent comp, DataFlavor[] transferFlavors)
Note: Swing now calls the newer version of canImport
that takes a TransferSupport
, which in turn calls this method (only if the component in the TransferSupport
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
).
comp
- the component to receive the transfer; provided to enable sharing of TransferHandler
stransferFlavors
- the data formats availablepublic int getSourceActions(JComponent c)
COPY
, MOVE
and LINK
. Some models are not mutable, so a transfer operation of MOVE
should not be advertised in that case. Returning NONE
disables transfers from the component.
c
- the component holding the data to be transferred; provided to enable sharing of TransferHandler
sCOPY
if the transfer property can be found, otherwise returns NONE
public Icon getVisualRepresentation(Transferable t)
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
.
t
- the data to be transferred; this value is expected to have been created by the createTransferable
methodnull
, indicating there is no default visual representationprotected Transferable createTransferable(JComponent c)
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
c
- the component holding the data to be transferred; provided to enable sharing of TransferHandler
snull
if the property associated with c
is null
protected void exportDone(JComponent source, Transferable data, int action)
MOVE
. This method is implemented to do nothing since MOVE
is not a supported action of this implementation (getSourceActions
does not include MOVE
).
source
- the component that was the source of the datadata
- The data that was transferred or possibly null if the action is NONE
.action
- the actual action that was performed
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/swing/TransferHandler.html