Module java.desktop
Package javax.swing

Class TransferHandler

java.lang.Object
javax.swing.TransferHandler
所有实现的接口:
Serializable
public class TransferHandler extends Object implements Serializable
该类用于处理在Swing组件之间传输Transferable的操作。 Transferable用于表示通过剪切、复制或粘贴到/从剪贴板交换的数据。它还用于拖放操作，表示从组件拖动和放置到组件。Swing提供了自动支持使用此类实现提供的功能的剪切、复制和粘贴键绑定的功能。Swing还提供了自动支持使用此类实现提供的功能的拖放操作。Swing开发人员可以通过在Swing组件上设置transferHandler属性来集中精力于主要设置传输的语义。

该类被实现为通过在构造函数中简单指定属性名称来提供组件属性的默认传输行为。例如，要通过剪贴板或拖放操作从一个组件传输前景色到另一个组件，可以使用字符串"foreground"构造一个TransferHandler。内置支持将使用getForeground返回的颜色作为传输的源，以及setForeground作为传输的目标。

更多信息请参阅如何使用拖放和数据传输，这是The Java Tutorial中的一个部分。

自1.4版本起:
1.4

  • Field Details

    • NONE

      public static final int NONE
      代表无传输操作的int。
      参见:

    • COPY

      public static final int COPY
      代表"复制"传输操作的int。当数据被复制到剪贴板或在拖放操作中复制到其他位置时使用此值。
      参见:

    • MOVE

      public static final int MOVE
      代表"移动"传输操作的int。当数据被移动到剪贴板（即剪切）或在拖放操作中移动到其他位置时使用此值。
      参见:

    • COPY_OR_MOVE

      public static final int COPY_OR_MOVE
      代表源操作能力为"复制"或"移动"的int。
      参见:

  • Constructor Details

    • TransferHandler

      public TransferHandler(String property)
      构造一个传输处理程序，可以通过剪贴板或拖放操作从一个组件传输Java Bean属性到另一个组件。
      参数:
      property - 要传输的属性的名称；如果传输处理程序没有关联的属性（例如执行其他类型的传输的子类），则可以为null

    • TransferHandler

      protected TransferHandler()
      用于子类的便利构造函数。

  • Method Details

    • getCutAction

      public static Action getCutAction()
      返回执行剪切操作到剪贴板的Action。执行时，此操作通过在ActionEvent的JComponent源上调用exportToClipboard，使用组件的TransferHandler和MOVE操作。
      返回:
      用于执行剪切到剪贴板的Action

    • getCopyAction

      public static Action getCopyAction()
      返回执行复制操作到剪贴板的Action。执行时，此操作通过在ActionEvent的JComponent源上调用exportToClipboard，使用组件的TransferHandler和COPY操作。
      返回:
      用于执行复制到剪贴板的Action

    • getPasteAction

      public static Action getPasteAction()
      返回执行从剪贴板粘贴操作的Action。执行时，此操作通过在ActionEvent的JComponent源上调用importData，使用组件的TransferHandler和剪贴板内容。
      返回:
      用于执行从剪贴板粘贴的Action

    • setDragImage

      public void setDragImage(Image img)
      设置拖动图像参数。图像必须在调用时准备好进行渲染。由于某些性能原因，图像是通过引用存储的。
      参数:
      img - 要拖动的图像

    • getDragImage

      public Image getDragImage()
      返回拖动图像。如果没有要拖动的图像，则返回值为null。
      返回:
      拖动图像的引用

    • setDragImageOffset

      public void setDragImageOffset(Point p)
      设置要拖动的图像的锚点偏移量。它不能为null。
      参数:
      p - 与图像左上角的锚点偏移量对应的Point对象

    • getDragImageOffset

      public Point getDragImageOffset()
      返回要拖动的图像的锚点偏移量。
      返回:
      一个Point对象，对应于图像左上角的锚点偏移量的坐标。默认返回点为(0,0)。

    • exportAsDrag

      public void exportAsDrag(JComponent comp, InputEvent e, int action)
      导致启动Swing拖动支持。如果在此调用返回时传输尚未完成（即，调用不会阻塞等待放置），则传输将通过java.awt.dnd机制的Swing实现进行，开发人员无需进一步努力。传输完成后将调用exportDone方法。
      参数:
      comp - 持有要传输数据的组件；提供以便共享TransferHandler
      e - 触发传输的事件
      action - 最初请求的传输操作；可以是COPY、MOVE或LINK；DnD系统可能在拖动操作过程中更改使用的操作

    • exportToClipboard

      public void exportToClipboard(JComponent comp, Clipboard clip, int action) throws IllegalStateException
      从给定组件传输到给定剪贴板。此方法由组件动作映射中注册的默认剪切和复制操作调用。

      传输将使用java.awt.datatransfer机制进行，开发人员无需进一步努力。任何数据传输都将完成，并且在此方法返回之前将调用exportDone方法，该方法将使用发生的操作进行调用。如果在尝试将数据放置在剪贴板上时剪贴板不可用，则通过此方法传播由Clipboard.setContents(Transferable, ClipboardOwner)抛出的IllegalStateException。但是，为了保持一致性，首先将使用NONE的操作调用exportDone。

      参数:
      comp - 持有要传输数据的组件；提供以便共享TransferHandler
      clip - 要传输数据的剪贴板
      action - 请求的传输操作；这应该是COPY或MOVE的值；执行的操作是由getSourceActions给出的传输能力和请求的操作的交集；如果不支持请求的操作，则交集可能导致NONE的操作
      抛出:
      IllegalStateException - 如果剪贴板当前不可用
      参见:

    • importData

      public boolean importData(TransferHandler.TransferSupport support)
      导致从剪贴板或拖放操作发生传输。要导入的Transferable和要传输到的组件都包含在TransferSupport中。

      虽然拖放实现在调用此方法之前调用canImport来确定传输的适用性，但粘贴的实现不会这样做。因此，在粘贴时不能假定传输是可接受的。建议显式调用canImport以涵盖此情况。

      注意：传递给此方法的TransferSupport对象仅在方法调用期间有效。在此方法返回后，它可能包含什么值是未定义的。

      参数:
      support - 包含传输详细信息的对象，不能为空。
      返回:
      如果数据已插入组件，则为true，否则为false
      抛出:
      NullPointerException - 如果support为null
      自：
      1.6
      参见:

    • importData

      public boolean importData(JComponent comp, Transferable t)
      导致从剪贴板或DND拖放操作传输到组件。 Transferable表示要导入组件的数据。

      注意：Swing现在调用接受TransferSupport的新版本importData，该版本将调用此方法（如果TransferSupport中的组件是JComponent）。鼓励开发人员调用和覆盖新版本，因为它提供了更多信息（并且是唯一支持直接在JFrame或其他非JComponent上设置TransferHandler的版本）。

      参数:
      comp - 接收传输的组件；提供以便共享TransferHandler
      t - 要导入的数据
      返回:
      如果数据已插入组件，则为true，否则为false
      参见:

    • canImport

      public boolean canImport(TransferHandler.TransferSupport support)
      在拖放操作期间重复调用此方法，以允许开发人员配置传输的属性，并返回传输的可接受性；返回值为true表示给定TransferSupport表示的传输在当前时间是可接受的，false拒绝传输。

      对于自动在拖放期间显示放置位置的组件，默认情况下接受传输会告诉它们显示放置位置。可以通过在TransferSupport上调用setShowDropLocation来更改此设置。

      默认情况下，当接受传输时，所选的放置操作是用户通过拖动手势选择的操作。开发人员可以通过在TransferSupport上调用setDropAction来覆盖此操作并选择不同的操作，从支持的源操作中选择。

      在每次调用canImport时，TransferSupport都包含新的状态。因此，在每次调用时必须在其上设置任何属性。在放置时，在调用importData之前，最后一次调用canImport。在最后一次调用期间在TransferSupport上设置的任何状态将在importData中可用。

      此方法不会在响应粘贴操作时内部调用。因此，建议importData的实现显式调用此方法处理这种情况，并且此方法应准备好返回粘贴操作的适用性。

      注意：传递给此方法的TransferSupport对象仅在方法调用期间有效。在此方法返回后，它可能包含什么值是未定义的。

      参数:
      support - 包含传输详细信息的对象，不能为空。
      返回:
      如果可以进行导入，则为true，否则为false
      抛出:
      NullPointerException - 如果support为null
      自：
      1.6
      参见:

    • canImport

      public boolean canImport(JComponent comp, DataFlavor[] transferFlavors)
      在实际尝试导入给定数据格式集的导入之前指示组件是否将接受导入。

      注意：Swing现在调用接受TransferSupport的新版本canImport，该版本将调用此方法（仅当TransferSupport中的组件是JComponent时）。鼓励开发人员调用和覆盖新版本，因为它提供了更多信息（并且是唯一支持直接在JFrame或其他非JComponent上设置TransferHandler的版本）。

      参数:
      comp - 接收传输的组件；提供以便共享TransferHandler
      transferFlavors - 可用的数据格式
      返回:
      如果数据可以插入组件，则为true，否则为false
      参见:

    • getSourceActions

      public int getSourceActions(JComponent c)
      返回源支持的传输操作类型；任何COPY、MOVE和LINK的按位或组合。

      某些模型是不可变的，因此在这种情况下不应该宣传MOVE的传输操作。返回NONE会禁用从组件的传输。

      参数:
      c - 持有要传输数据的组件；提供以便共享TransferHandler
      返回:
      如果可以找到传输属性，则返回COPY，否则返回NONE

    • getVisualRepresentation

      public Icon getVisualRepresentation(Transferable t)
      返回一个建立传输外观的对象。这对于在执行拖动操作时提供反馈以及在具有视觉外观的剪贴板实现中表示传输很有用。 Icon接口的实现不应更改图形剪辑或alpha级别。图标实现不必是矩形的，也不必绘制所有边界矩形，调用图标的绘制方法的逻辑不应假定所有位都已绘制。对于此方法，null是有效的返回值，表示没有提供视觉表示。在这种情况下，调用逻辑可以自由地表示传输，无论它想要如何表示传输。

      如果返回值为null，默认的Swing逻辑将不执行alpha混合的拖动动画。

      参数:
      t - 要传输的数据；预计此值已由createTransferable方法创建
      返回:
      null，表示没有默认的视觉表示

    • createTransferable

      protected Transferable createTransferable(JComponent c)
      创建一个Transferable用作数据传输的源。返回要传输的数据的表示，如果组件的属性为null则返回null
      参数:
      c - 持有要传输数据的组件；提供以便共享TransferHandler
      返回:
      要传输的数据的表示，如果与c关联的属性为null则返回null

    • exportDone

      protected void exportDone(JComponent source, Transferable data, int action)
      在数据导出后调用。如果操作是MOVE，则此方法应删除传输的数据。

      此方法实现为不执行任何操作，因为此实现不支持MOVE操作（getSourceActions不包括MOVE）。

      参数:
      source - 数据来源的组件
      data - 被传输的数据，如果操作是NONE，可能为null。
      action - 实际执行的操作