JavaTM 2 Platform
Standard Ed. 5.0

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

字段摘要
static int COPY
          表示“复制”传输操作的 int 值。
static int COPY_OR_MOVE
          表示“复制”或“移动”的源操作功能的 int 值。
static int MOVE
          表示“移动”传输操作的 int 值。
static int NONE
          表示无传输操作的 int 值。
 
构造方法摘要
protected TransferHandler()
          子类的便捷构造方法。
  TransferHandler(String property)
          构造一个通过剪贴板或拖放操作可以将 Java Bean 属性从一个组件传输到另一个组件的传输处理程序。
 
方法摘要
 boolean canImport(JComponent comp, DataFlavor[] transferFlavors)
          指示一个组件在实际尝试导入给定数据 flavor 的集合之前是否接受导入。
protected  Transferable createTransferable(JComponent c)
          创建一个要用作数据传输源的 Transferable
 void exportAsDrag(JComponent comp, InputEvent e, int action)
          导致 Swing 拖动支持的启用。
protected  void exportDone(JComponent source, Transferable data, int action)
          在导出数据之后调用。
 void exportToClipboard(JComponent comp, Clipboard clip, int action)
          导致从给定组件到给定剪贴板的传输。
static Action getCopyAction()
          返回一个其行为类似“复制”操作的 Action
static Action getCutAction()
          返回一个其行为类似“剪切”操作的 Action
static Action getPasteAction()
          返回一个其行为类似“粘贴”操作的 Action
 int getSourceActions(JComponent c)
          返回源支持的传输操作的类型。
 Icon getVisualRepresentation(Transferable t)
          返回一个建立传输外观的对象。
 boolean importData(JComponent comp, Transferable t)
          导致从剪贴板或 DND 放置操作向组件的传输。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

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。也就是说,将在与作为该 ActionEvent 的源 JComponent 相关的 TransferHandler 上调用具有 MOVE 参数的 exportToClipboard

返回:
剪切操作

getCopyAction

public static Action getCopyAction()
返回一个其行为类似“复制”操作的 Action。也就是说,将在与作为该 ActionEvent 的源 JComponent 相关的 TransferHandler 上调用具有 COPY 参数的 exportToClipboard

返回:
剪切操作

getPasteAction

public static Action getPasteAction()
返回一个其行为类似“粘贴”操作的 Action。也就是说,将在与作为该 ActionEvent 的源 JComponent 相关的 TransferHandler 上调用 importData

返回:
剪切操作

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 - 最初请求的传输操作;这应该是 COPYMOVE 值;该值可以在执行拖动操作的过程中更改

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 - 请求的传输操作;这应该是 COPYMOVE 二者的其中一个值;执行的操作是由 getSourceActions 和请求的操作给定的传输功能的交集;如果不支持请求的操作,则该交集可能会导致 NONE 操作
抛出:
IllegalStateException - 如果该剪贴板当前不可用
另请参见:
Clipboard.setContents(Transferable, ClipboardOwner)

importData

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

参数:
comp - 要接收传输的组件;提供此参数以启用由多个组件使用的 TransferHandler 共享
t - 要导入的数据
返回:
如果该数据已插入到组件,则返回 true,否则返回 false

canImport

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

参数:
comp - 要接收传输的组件;提供此参数以启用由多个组件使用的 TransferHandlers 共享
transferFlavors - 可用的数据格式
返回:
如果可以将该数据插入到组件,则返回 true,否则返回 false

getSourceActions

public int getSourceActions(JComponent c)
返回源支持的传输操作的类型。有些模型是不可变的,因此 COPY 的传输操作只应该在这种情况下公开。

参数:
c - 存储要传输的数据的组件;提供此参数以启用由多个组件使用的 TransferHandler 共享。
返回:
如果可以找到该传输属性,则返回 COPY,否则返回 NONENONE 的返回值禁用该组件传出的所有传输

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 - 已执行的实际操作

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策