模块 java.desktop
包 javax.swing

类 TransferHandler

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

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

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

自从：
1.4

  • 字段详细信息

    • 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 表示“复制”或“移动”的源操作功能。
      参见：

  • 构造方法详细信息

    • TransferHandler

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

    • TransferHandler

      protected TransferHandler()
      子类的便捷构造方法。

  • 方法详情

    • getCutAction

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

    • getCopyAction

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

    • getPasteAction

      public static Action  getPasteAction()
      返回从剪贴板执行粘贴操作的 Action。执行时，此操作通过在组件的 TransferHandler 上使用剪贴板内容调用 importData 来对 ActionEvent 的 JComponent 源进行操作。
      返回：
      一个 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 拖动支持。如果在组件上设置了 dragEnabled 属性，则由 javax.swing.plaf.basic 包中的各种 UI 实现调用。这可以由自定义 UI 实现调用以使用 Swing 拖动支持。此方法也可以由作为 JComponent 的子类编写的 Swing 扩展调用，以利用 Swing 拖动支持。

      传输 will not necessarily 已在该调用返回时完成（即调用不会阻塞等待删除）。传输将通过 java.awt.dnd 机制的 Swing 实现进行，不需要开发人员做更多的工作。传输完成后将调用 exportDone 方法。

      参数：
      comp - 保存要传输的数据的组件；提供以启用TransferHandlers的共享
      e - 触发转移的事件
      action - 最初请求的转移动作； COPY、MOVE 或 LINK； DnD 系统可能会更改拖动操作过程中使用的操作

    • exportToClipboard

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

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

      参数：
      comp - 保存要传输的数据的组件；提供以启用TransferHandlers的共享
      clip - 将数据传输到的剪贴板
      action - 请求的转移操作；这应该是 COPY 或 MOVE 的值；执行的操作是 getSourceActions 给出的传输能力和请求的动作的交集；如果不支持请求的操作，交集可能会导致 NONE 的操作
      抛出：
      IllegalStateException - 如果剪贴板当前不可用
      参见：

    • importData

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

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

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

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

    • importData

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

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

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

    • canImport

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

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

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

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

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

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

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

    • canImport

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

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

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

    • getSourceActions

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

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

      参数：
      c - 保存要传输的数据的组件；提供以启用TransferHandlers的共享
      返回：
      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 - 保存要传输的数据的组件；提供以启用TransferHandlers的共享
      返回：
      要传输的数据的表示，或者 null 如果与 c 关联的属性是 null

    • exportDone

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

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

      参数：
      source - 作为数据源的组件
      data - 传输的数据或如果操作为 NONE 则可能为空。
      action - 执行的实际操作