模块  java.desktop
软件包  javax.swing

Class TransferHandler

  • 实现的所有接口
    Serializable

    public class TransferHandler
    extends Object
    implements Serializable
    该类用于处理Transferable与Swing组件的转移。 Transferable用于表示通过剪切,复制或粘贴到剪贴板或从剪贴板粘贴的数据。 它还用于拖放操作,以表示组件的拖动和组件的拖放。 Swing提供了自动支持剪切,复制和粘贴键盘绑定的功能,这些键盘绑定使用此类实现提供的功能。 Swing还提供了自动支持拖放的功能,该功能使用此类实现提供的功能。 Swing开发人员可以主要通过在Swing组件上设置transferHandler属性来专注于指定传输的语义。

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

    有关详细信息,请参阅“Java教程” How to Use Drag and Drop and Data Transfer部分。

    从以下版本开始:
    1.4
    另请参见:
    Serialized Form
    • 字段详细信息

      • 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上调用exportToClipboardMOVE操作)对ActionEventJComponent源进行操作。
        结果
        用于执行剪贴板切割的 Action
      • getCopyAction

        public static Action getCopyAction()
        返回一个ActionAction剪贴板执行复制操作。 当执行时,这个动作在操作JComponent所述的源ActionEvent通过调用exportToClipboard ,具有COPY动作,对组件的TransferHandler
        结果
        用于执行副本到剪贴板的 Action
      • getPasteAction

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

        转移不一定在该呼叫返回时完成(即呼叫不阻止等待丢弃)。 转移将通过java.awt.dnd机制的Swing实现进行,无需开发人员的进一步努力。 传输完成后将调用exportDone方法。

        参数
        comp - 保存要传输数据的组件; 提供以便共享TransferHandler
        e - 触发转移的事件
        action - 最初请求的转移行动; 任一COPYMOVELINK ; DnD系统可以改变拖动操作过程中使用的动作
      • exportToClipboard

        public void exportToClipboard​(JComponent comp,
                                      Clipboard clip,
                                      int action)
                               throws IllegalStateException
        导致从给定组件转移到给定剪贴板。 通过在组件的操作映射中注册的默认剪切和复制操作来调用此方法。

        转移将使用java.awt.datatransfer机制进行,无需开发人员的进一步努力。 任何数据传输将完成,并且在此方法返回之前将使用发生的操作调用exportDone方法。 如果剪贴板在尝试将数据放入其中时不可用,则IllegalStateException抛出的IllegalStateException将通过此方法传播。 但是, exportDone将使用NONE的操作调用NONE以保持一致性。

        参数
        comp - 保存要传输的数据的组件; 提供共享TransferHandler s
        clip - 将数据传输到的剪贴板
        action - 要求的转移行动; 这应该是COPYMOVE的值; 执行的操作是getSourceActions给出的传输功能与请求的操作的交集; 如果不支持请求的操作,则交集可能会导致NONE的操作
        异常
        IllegalStateException - 如果剪贴板当前不可用
        另请参见:
        Clipboard.setContents(Transferable, ClipboardOwner)
      • importData

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

        虽然拖放实现在调用此方法之前调用canImport来确定传输的适用性,但粘贴的实现却没有。 因此,不能假设在调用该方法进行粘贴时转移是可接受的。 建议明确调用canImport来涵盖此案例。

        注意:传递给此方法的TransferSupport对象仅在方法调用的持续时间内有效。 未定义此方法返回后可能包含的值。

        参数
        support - 包含传输详细信息的对象,而不是 null
        结果
        如果数据已插入组件,则为true,否则为false
        异常
        NullPointerException - 如果 supportnull
        从以下版本开始:
        1.6
        另请参见:
        canImport(TransferHandler.TransferSupport)
      • importData

        public boolean importData​(JComponent comp,
                                  Transferable t)
        导致从剪贴板或DND删除操作转移到组件。 Transferable表示要导入组件的数据。

        注意:Swing现在调用较新版本的importData ,它需要TransferSupport ,后者又调用此方法(如果TransferSupport的组件是JComponent )。 鼓励开发人员调用和覆盖较新版本,因为它提供了更多信息(并且是唯一支持与TransferHandler直接设置在JFrame或其他非JComponent )。

        参数
        comp - 接收转移的组件; 提供共享TransferHandler s
        t - 要导入的数据
        结果
        如果数据已插入组件,则为true,否则为false
        另请参见:
        importData(TransferHandler.TransferSupport)
      • canImport

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

        对于在拖放过程中自动显示放置位置的组件,默认情况下接受转移会告诉他们显示放置位置。 这可以通过拨打setShowDropLocation上的TransferSupport进行更改。

        默认情况下,当接受传输时,所选择的拖放操作是用户通过其拖动手势拾取的操作。 开发人员可以重写此选择不同的动作,从支持的源动作,通过调用setDropActionTransferSupport

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

        响应粘贴操作,不会在内部调用此方法。 因此,建议importData实现明确地为这种情况调用此方法,并且此方法也准备好返回粘贴操作的适用性。

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

        参数
        support - 包含传输详细信息的对象,而不是 null
        结果
        true如果导入可能发生,否则为 false
        异常
        NullPointerException - 如果 supportnull
        从以下版本开始:
        1.6
        另请参见:
        importData(TransferHandler.TransferSupport)TransferHandler.TransferSupport.setShowDropLocation(boolean)TransferHandler.TransferSupport.setDropAction(int)
      • canImport

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

        注意:Swing现在调用较新版本的canImport ,需要TransferSupport ,后者又调用此方法(仅当TransferSupport的组件为JComponent )。 鼓励开发人员调用和覆盖较新版本,因为它提供了更多信息(并且是唯一支持与TransferHandler直接设置在JFrame或其他非JComponent )。

        参数
        comp - 接收转移的组件; 提供以便共享TransferHandler
        transferFlavors - 可用的数据格式
        结果
        如果数据可以插入组件,则为true,否则为false
        另请参见:
        canImport(TransferHandler.TransferSupport)
      • getSourceActions

        public int getSourceActions​(JComponent c)
        返回源支持的传输操作的类型; 任何按位或组合COPYMOVELINK

        某些型号不可变,因此在这种情况下不应公布MOVE的转移操作。 返回NONE将禁用组件的传输。

        参数
        c - 保存要传输的数据的组件; 提供以便共享TransferHandler
        结果
        COPY如果可以找到transfer属性,否则返回 NONE
      • getVisualRepresentation

        public Icon getVisualRepresentation​(Transferable t)
        返回一个建立传输外观的对象。 这对于在执行拖动操作时提供反馈以及在具有视觉外观的剪贴板实现中表示传输都是有用的。 Icon接口的实现不应改变图形剪辑或alpha级别。 图标实现不需要是矩形或绘制所有边界矩形和调用图标paint方法的逻辑不应该假设所有位都被绘制。 null是此方法的有效返回值,表示未提供可视表示形式。 在这种情况下,调用逻辑可以自由地表示它想要的transferable。

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

        参数
        t - 要传输的数据; 预计此值将由createTransferable方法创建
        结果
        null ,表示没有默认的可视化表示
      • createTransferable

        protected Transferable createTransferable​(JComponent c)
        创建Transferable以用作数据传输的源。 返回到要传送的数据的表示,或null如果组件的属性是null
        参数
        c - 保存要传输的数据的组件; 提供以便共享TransferHandler
        结果
        数据的表示要传送,或者 null如果与相关联的属性 cnull
      • exportDone

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

        实现此方法不执行任何操作,因为MOVE不是此实现的受支持操作( getSourceActions不包括MOVE )。

        参数
        source - 作为数据源的组件
        data - 已传输的数据,如果操作为 NONE ,则可能为null。
        action - the actual action that was performed