Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Field Details

• NONE

  public static final int NONE

  Anint representing no transfer action.

  See Also:

  • Constant Field Values

• COPY

  public static final int COPY

  Anint 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

  Anint 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

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

  See Also:

  • Constant Field Values

• LINK

  public static final int LINK

  Anint 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:

  • DnDConstants.ACTION_LINK
  • Constant Field Values

Constructor Details

• 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 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

  public static Action 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:

  anAction for performing cuts to the clipboard

• getCopyAction

  public static Action 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:

  anAction for performing copies to the clipboard

• getPasteAction

  public static Action 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:

  anAction for performing pastes from the clipboard

• setDragImage

  public void setDragImage(Image img)

  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

  public Image getDragImage()

  Returns the drag image. If there is no image to drag, the returned value isnull.

  Returns:

  the reference to the drag image

• setDragImageOffset

  public void setDragImageOffset(Point p)

  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

  public Point getDragImageOffset()

  Returns an anchor offset for the image to drag.

  Returns:

  aPoint 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

  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 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 transferwill 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 thejava.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 ofTransferHandlers

  e - the event that triggered the transfer

  action - 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) throwsIllegalStateException

  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 thejava.awt.datatransfer mechanism, requiring no further effort from the developer. Any data transferwill 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 ofTransferHandlers

  clip - the clipboard to transfer the data into

  action - 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:

  • Clipboard.setContents(Transferable, ClipboardOwner)

• importData

  public boolean importData(TransferHandler.TransferSupport support)

  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 callscanImport 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: TheTransferSupport 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:

  • canImport(TransferHandler.TransferSupport)

• importData

  public boolean importData(JComponent comp,Transferable t)

  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 ofimportData 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 ofTransferHandlers

  t - the data to import

  Returns:

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

  See Also:

  • importData(TransferHandler.TransferSupport)

• canImport

  public 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.

  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 callingsetShowDropLocation 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 callingsetDropAction on theTransferSupport.

  On every call tocanImport, 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 ofimportData explicitly call this method for such cases and that this method be prepared to return the suitability of paste operations as well.

  Note: TheTransferSupport 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:

  • importData(TransferHandler.TransferSupport)
  • TransferHandler.TransferSupport.setShowDropLocation(boolean)
  • TransferHandler.TransferSupport.setDropAction(int)

• canImport

  public 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.

  Note: Swing now calls the newer version ofcanImport 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 ofTransferHandlers

  transferFlavors - the data formats available

  Returns:

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

  See Also:

  • canImport(TransferHandler.TransferSupport)

• getSourceActions

  public int getSourceActions(JComponent c)

  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 ofMOVE 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 ofTransferHandlers

  Returns:

  COPY if the transfer property can be found, otherwise returnsNONE

• 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 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 isnull.

  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

  protected Transferable createTransferable(JComponent c)

  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 ofTransferHandlers

  Returns:

  the representation of the data to be transferred, ornull if the property associated withc isnull

• 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 wasMOVE.

  This method is implemented to do nothing sinceMOVE is not a supported action of this implementation (getSourceActions does not includeMOVE).

  Parameters:

  source - the component that was the source of the data

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

  action - the actual action that was performed