javax.swing
类 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 中的 How to Use Drag and Drop and Data Transfer 一节。

从以下版本开始：

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 值。

另请参见：

常量字段值

LINK

public static final int LINK

表示“链接”传输动作的 int 值。此值用于指定应该以拖放操作链接数据。

从以下版本开始：

1.6

另请参见：

DnDConstants.ACTION_LINK, 常量字段值

TransferHandler

public TransferHandler(String property)

构造一个通过剪贴板或拖放操作可以将 Java Bean 属性从一个组件传输到另一个组件的传输处理程序。

参数：

property - 要传输的属性的名称；如果没有与该传输处理程序相关的属性（例如，执行其他某种传输的子类），则可以为 null

TransferHandler

protected TransferHandler()

子类的便捷构造方法。

getCutAction

public static Action getCutAction()

返回一个执行剪切到剪贴板操作的 Action。在执行时，此动作通过对组件的 TransferHandler 调用带 MOVE 动作的 exportToClipboard，在 ActionEvent 的 JComponent 源上进行操作。

返回：

一个执行剪切到剪贴板的 Action

getCopyAction

public static Action getCopyAction()

返回一个执行复制到剪贴板操作的 Action。在执行时，此动作通过对组件的 TransferHandler 调用带 COPY 动作的 exportToClipboard，在 ActionEvent 的 JComponent 源上进行操作。

返回：

一个执行复制到剪贴板的 Action

getPasteAction

public static Action getPasteAction()

返回一个从剪贴板执行粘贴操作的 Action。在执行时，此动作通过对组件的 TransferHandler 调用带有剪贴板内容的 importData，在 ActionEvent 的 JComponent 源上进行操作。

返回：

一个从剪贴板执行粘贴的 Action

exportAsDrag

public void exportAsDrag(JComponent comp,
                         InputEvent e,
                         int action)

导致 Swing 拖动支持的启用。如果在组件上设置 dragEnabled 属性，则由 javax.swing.plaf.basic 包中的各种 UI 实现调用此方法。可由使用 Swing 拖动支持的自定义 UI 实现调用此方法。也可由作为 JComponent 的子类写入的 Swing 扩展调用此方法，以利用 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 - 如果该剪贴板当前不可用

另请参见：

Clipboard.setContents(Transferable, ClipboardOwner)

importData

public boolean importData(TransferHandler.TransferSupport support)

导致从剪贴板或拖放操作的传输。要导入的 Transferable 和要传输到的组件包含在 TransferSupport 中。

拖放实现在调用此方法前调用 canImport 确定是否适合传输，但粘贴的实现不会这样做。因此，调用此方法进行粘贴时不能假定传输一定是可接受的。这种情况下，建议显式调用 canImport。

注：传递给此方法的 TransferSupport 对象只在该方法的调用期间才有效。此方法返回后它可以包含的值是不确定的。

参数：

support - 包含该传输细节的对象，不为 null。

返回：

如果数据被插入该组件，则返回 true；否则返回 false

抛出：

NullPointerException - 如果 support 为 null

从以下版本开始：

1.6

另请参见：

canImport(TransferHandler.TransferSupport)

importData

public boolean importData(JComponent comp,
                          Transferable t)

导致从剪贴板或 DND 放置操作向组件的传输。 Transferable 表示要导入组件的数据。

注：Swing 现在调用新的 importData，它带有 TransferSupport，而 TransferSupport 调用此方法（如果 TransferSupport 中的组件是 JComponent）。鼓励开发人员调用并重写新的版本，因为它提供了更多信息（它也是唯一支持与直接在 JFrame 或其他非 JComponent 上设置的 TransferHandler 一起使用的版本）。

参数：

comp - 要接收传输的组件；提供此参数以启用 TransferHandler 的共享

t - 要导入的数据

返回：

如果该数据已插入到组件，则返回 true，否则返回 false

另请参见：

importData(TransferHandler.TransferSupport)

canImport

public boolean canImport(TransferHandler.TransferSupport support)

在拖放操作期间重复调用此方法，以允许开发人员配置传输的可接受性属性，并返回传输的可接受性；返回 true 值指示给定 TransferSupport（它包含该传输的所有细节）所表示的传输在当前是可以接受的， false 值指示拒绝该传输。

对于在拖放期间自动显示放置位置的那些组件（接受传输），默认情况下，告知它们显示放置位置。这可通过在 TransferSupport 上调用 setShowDropLocation 更改。

默认情况下，当接受传输时，选择的放置动作是用户通过其拖动动作挑出的动作。通过在 TransferSupport 上调用 setDropAction，开发人员可以重写此方法并从受支持的源动作中选择一个不同的动作。

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

不会内部调用此方法来响应粘贴操作。因此，对于这种情况，建议 importData 的实现显式调用此方法，并建议此方法还要准备好返回是否适合粘贴操作。

注：传递给此方法的 TransferSupport 对象只在该方法的调用期间才有效。此方法返回后可以包含的值是不确定的。

参数：

support - 包含该传输的细节的对象，不为 null。

返回：

如果导入可能发生，则返回 true；否则返回 false

抛出：

NullPointerException - 如果 support 为 null

从以下版本开始：

1.6

另请参见：

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

canImport

public boolean canImport(JComponent comp,
                         DataFlavor[] transferFlavors)

指示一个组件在实际尝试导入给定数据 flavor 的集合之前是否接受其导入。

注：Swing 现在调用新的 importData，它带有 TransferSupport，而 TransferSupport 调用此方法（当且仅当 TransferSupport 中的组件是 JComponent 时）。鼓励开发人员调用并重写新的版本，因为它提供了更多信息（它也是唯一支持与直接在 JFrame 或其他非 JComponent 上设置的 TransferHandler 一起使用的版本）。

参数：

comp - 要接收传输的组件；提供此参数以启用 TransferHandlers 的共享

transferFlavors - 可用的数据格式

返回：

如果可以将该数据插入到组件，则返回 true，否则返回 false

另请参见：

canImport(TransferHandler.TransferSupport)

getSourceActions

public int getSourceActions(JComponent c)

返回源支持的传输动作的类型； COPY、 MOVE 和 LINK 的任意按位或组合。

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

参数：

c - 存储要传输的数据的组件；提供此参数以启用 TransferHandler 的共享

返回：

如果可以找到该传输属性，则返回 COPY；否则返回 NONE

getVisualRepresentation

public Icon getVisualRepresentation(Transferable t)

返回一个建立传输外观的对象。此方法适用于在执行拖动操作时提供反馈和在具有可视化外观的剪贴板实现中表示传输。该 Icon 接口的实现不应更改图形剪贴或 alpha 级别。该图标实现不必是矩形，也不必绘制所有边界矩形，并且调用该图标绘制方法的逻辑不应假定绘制了所有位。 null 是此方法的一个有效返回值，指示没有提供任何可视化表示形式。在这种情况下，该调用逻辑完全可以随意表示该 transferable。

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

参数：

t - 要传输的数据；此值希望已由 createTransferable 方法创建

返回：

null，指示没有任何默认可视化表示形式

createTransferable

protected Transferable createTransferable(JComponent c)

创建一个要用作数据传输源的 Transferable。返回要传输的数据表示形式，或者返回 null 如果组件的属性为 null

参数：

c - 存储要传输的数据的组件；提供此参数以启用 TransferHandler 的共享

返回：

要传输的数据表示形式，或返回 null 如果与 c 相关的属性为 null

exportDone

protected void exportDone(JComponent source,
                          Transferable data,
                          int action)

在导出数据之后调用。如果该操作为 MOVE，则此方法应该移除已传输的数据。

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

参数：

source - 以前作为数据源的组件

data - 已传输的数据，如果该操作为 NONE，则可能为 null。

action - 已执行的实际操作