| |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
JComponent c = …;
TransferHandler handler = c.getTransferHandler();
Based on 30 examples
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.
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 |
Represents a location where dropped data should be inserted. |
static 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 | |
---|---|
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 |
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. |
Constructor Summary | |
---|---|
protected |
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 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 of indicating that the transfer represented by the given (which contains all of the details of the transfer) is acceptable at the current time, and a value of rejecting the transfer. |
protected Transferable |
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 |
Returns an that performs copy operations to the clipboard. |
static Action |
Returns an that performs cut operations to the clipboard. |
static Action |
Returns an that performs paste operations from the clipboard. |
int |
Returns the type of transfer actions supported by the source; any bitwise-OR combination of , and . |
Icon |
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. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
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 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 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 NONE
int
representing no transfer action.
Constructor Detail |
---|
protected TransferHandler()
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)Method Detail |
---|
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 {@code TransferSupport} is a
{@code 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 {@code TransferHandler} set directly
on a {@code JFrame} or other non-{@code JComponent}).
comp
- the component to receive the transfer;
provided to enable sharing of TransferHandler
stransferFlavors
- the data formats availablepublic boolean canImport(TransferHandler.TransferSupport support)
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 {@code setShowDropLocation} on the {@code 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 {@code setDropAction} on the {@code TransferSupport}.
On every call to {@code canImport}, the {@code TransferSupport} contains fresh state. As such, any properties set on it must be set on every call. Upon a drop, {@code canImport} is called one final time before calling into {@code importData}. Any state set on the {@code TransferSupport} during that last call will be available in {@code importData}.
This method is not called internally in response to paste operations. As such, it is recommended that implementations of {@code 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
otherwiseprotected 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
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 {@code COPY}, {@code MOVE} or {@code LINK};
the DnD system may change the action used during the
course of the drag operationprotected 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 performedpublic 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
{@link Clipboard#setContents(Transferable, ClipboardOwner)} will
be propogated 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 static Action getCopyAction()
public static Action getCutAction()
public static Action getPasteAction()
public int getSourceActions(JComponent c)
Some models are not mutable, so a transfer operation of {@code MOVE} should not be advertised in that case. Returning {@code NONE} disables transfers from the component.
c
- the component holding the data to be transferred;
provided to enable sharing of TransferHandler
sNONE
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 representationpublic 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 {@code TransferSupport} is a
{@code 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 {@code TransferHandler} set directly
on a {@code JFrame} or other non-{@code JComponent}).
comp
- the component to receive the transfer;
provided to enable sharing of TransferHandler
st
- the data to importpublic 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 {@code 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 {@code 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
.
| |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |