Module  java.desktop
软件包  java.awt.dnd

Class DragSource

  • All Implemented Interfaces:
    Serializable 

    public class DragSource
extends Object
implements Serializable
    DragSource是负责启动拖放操作的实体，可用于多种情况：
    • 该JVM的生命周期为每个JVM 1个默认实例。
    • 每个潜在的Drag Initiator对象（例如TextField）的实例为1个实例。 [实施依赖]
    • 特定Component每个实例1，或与GUI中的Component实例相关联的应用程序特定对象。 [实施依赖]
    • 一些其他任意关联。 [实施依赖]
    一旦DragSource获得，一个DragGestureRecognizer也应获得的关联DragSource与特定Component 。

    用户手势的初步解释以及随后的拖动操作开始是实施Component的责任，通常由DragGestureRecognizer实现。

    当拖动手势发生时，将DragSource的startDrag（）方法，以便处理用户的导航手势和传递拖放协议通知。 A DragSource只允许在任何一个时间进行单次拖放操作，并且通过抛出一个IllegalDnDOperationException直到现在的操作完成之前拒绝任何进一步的startDrag（）请求。

    startDrag（）方法调用createDragSourceContext（）方法来实例化一个合适的DragSourceContext ，并将DragSourceContextPeer与之相关联。

    如果拖放系统由于某种原因无法启动拖动操作，则startDrag（）方法将引发一个java.awt.dnd.InvalidDnDOperationException来表示这种情况。 通常，当底层平台系统不处于启动拖动状态或指定的参数无效时，会抛出此异常。

    请注意，在拖动期间，在拖动操作开始时由源公开的操作集可能不会更改，直到操作完成。 在DragSource的操作期间，操作是DragSource 。

    从以下版本开始：
    1.2
    另请参见：
    Serialized Form

    • 字段详细信息

      • DefaultCopyDrop

        public static final Cursor DefaultCopyDrop
        使用默认值Cursor进行复制操作，指示当前允许丢弃。 null如果GraphicsEnvironment.isHeadless()返回true 。
        另请参见：
        GraphicsEnvironment.isHeadless()

      • DefaultMoveDrop

        public static final Cursor DefaultMoveDrop
        默认的Cursor与移动操作一起使用，指示当前允许丢弃。 null如果GraphicsEnvironment.isHeadless()返回true 。
        另请参见：
        GraphicsEnvironment.isHeadless()

      • DefaultLinkDrop

        public static final Cursor DefaultLinkDrop
        默认Cursor ，用于指示当前允许丢弃的链接操作。 null如果GraphicsEnvironment.isHeadless()返回true 。
        另请参见：
        GraphicsEnvironment.isHeadless()

      • DefaultCopyNoDrop

        public static final Cursor DefaultCopyNoDrop
        使用默认值Cursor进行复制操作，指示当前不允许放置。 null如果GraphicsEnvironment.isHeadless()返回true 。
        另请参见：
        GraphicsEnvironment.isHeadless()

      • DefaultMoveNoDrop

        public static final Cursor DefaultMoveNoDrop
        使用默认值Cursor进行移动操作，指示当前不允许丢弃。 null如果GraphicsEnvironment.isHeadless()返回true 。
        另请参见：
        GraphicsEnvironment.isHeadless()

      • DefaultLinkNoDrop

        public static final Cursor DefaultLinkNoDrop
        缺省Cursor ，用于指示当前不允许下拉列表的链接操作。 null如果GraphicsEnvironment.isHeadless()返回true 。
        另请参见：
        GraphicsEnvironment.isHeadless()

    • 方法详细信息

      • isDragImageSupported

        public static boolean isDragImageSupported​()
        报告是否在底层平台上提供拖动 Image支持。
        结果
        如果在此平台上提供拖动图像支持

      • startDrag

        public void startDrag​(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Image dragImage,
                      Point imageOffset,
                      Transferable transferable,
                      DragSourceListener dsl,
                      FlavorMap flavorMap)
               throws InvalidDnDOperationException
        开始一拖，鉴于 DragGestureEvent启动拖动，初步 Cursor用， Image给拖累，抵消的 Image从的热点起源 Cursor在扳机的瞬间， Transferable拖动的目标数据， DragSourceListener和 FlavorMap 。
        参数
        trigger - 发起拖动的 DragGestureEvent
        dragCursor - 这个拖动操作的初始Cursor或默认光标处理的null ; 有关拖放时光标处理机制的详细信息，请参阅DragSourceContext
        dragImage - 要拖动的图像或 null
        imageOffset - Image起点与触发瞬间 Cursor热点的偏移
        transferable - 拖动的主题数据
        dsl - DragSourceListener
        flavorMap - 要使用的 FlavorMap ，或 null
        异常
        InvalidDnDOperationException - 如果拖放系统无法启动拖动操作，或者如果用户尝试在现有拖动操作仍在执行时启动拖动

      • startDrag

        public void startDrag​(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Transferable transferable,
                      DragSourceListener dsl,
                      FlavorMap flavorMap)
               throws InvalidDnDOperationException
        开始一拖，鉴于 DragGestureEvent启动拖动，初步 Cursor用， Transferable拖动的目标数据，该 DragSourceListener和 FlavorMap 。
        参数
        trigger - 发起拖动的 DragGestureEvent
        dragCursor - 这个拖动操作的初始Cursor或默认光标处理的null ; 有关拖放时光标处理机制的详细信息，请参阅DragSourceContext
        transferable - 拖动的主题数据
        dsl - DragSourceListener
        flavorMap - 要使用的 FlavorMap或 null
        异常
        InvalidDnDOperationException - 如果拖放系统无法启动拖动操作，或者如果用户尝试在现有拖动操作仍在执行时启动拖动

      • startDrag

        public void startDrag​(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Image dragImage,
                      Point dragOffset,
                      Transferable transferable,
                      DragSourceListener dsl)
               throws InvalidDnDOperationException
        开始一拖，鉴于 DragGestureEvent启动拖动，初步 Cursor用， Image给拖累，抵消的 Image从的热点起源 Cursor在触发，拖动的目标数据的瞬间，和 DragSourceListener 。
        参数
        trigger - 发起拖动的 DragGestureEvent
        dragCursor - 这个拖动操作的初始Cursor或默认光标处理的null ; 有关拖放时光标处理机制的详细信息，请参阅DragSourceContext
        dragImage - Image拖动或 null
        dragOffset - Image起始 Cursor触发瞬间 Cursor热点的偏移
        transferable - 拖动的主题数据
        dsl - DragSourceListener
        异常
        InvalidDnDOperationException - 如果拖放系统无法启动拖动操作，或者如果用户尝试在现有拖动操作仍在执行时启动拖动

      • startDrag

        public void startDrag​(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Transferable transferable,
                      DragSourceListener dsl)
               throws InvalidDnDOperationException
        开始一拖，鉴于 DragGestureEvent启动拖动，初步 Cursor用， Transferable拖动的目标数据和 DragSourceListener 。
        参数
        trigger - 发起拖动的 DragGestureEvent
        dragCursor - 这个拖动操作的初始Cursor或默认光标处理的null ; 有关拖放时光标处理机制的详细信息，请参阅DragSourceContext类
        transferable - 拖动的主题数据
        dsl - DragSourceListener
        异常
        InvalidDnDOperationException - 如果拖放系统无法启动拖动操作，或者如果用户尝试在现有拖动操作仍在执行时启动拖动

      • createDragSourceContext

        protected DragSourceContext createDragSourceContext​(DragGestureEvent dgl,
                                                    Cursor dragCursor,
                                                    Image dragImage,
                                                    Point imageOffset,
                                                    Transferable t,
                                                    DragSourceListener dsl)
        创建DragSourceContext来处理当前的拖动操作。

        要结合一个新的DragSourceContext子类，子类DragSource并覆盖此方法。

        如果dragImage为null ，则不会使用任何图像表示对此拖动操作的反馈拖动，但不会抛出NullPointerException 。

        如果dsl为null ，则不会在创建的DragSourceContext注册拖动源侦听DragSourceContext ，但不会抛出NullPointerException 。

        参数
        dgl - 触发了拖动的 DragGestureEvent
        dragCursor - 用于此拖动操作的初始Cursor或默认光标处理的null ; 有关拖放时光标处理机制的详细信息，请参阅DragSourceContext类
        dragImage - Image拖动或 null
        imageOffset - Image起始点在触发时刻光标热点的偏移量
        t - 拖动的主题数据
        dsl - DragSourceListener
        结果
        DragSourceContext
        异常
        NullPointerException - 如果 dscp是 null
        NullPointerException - 如果 dgl是 null
        NullPointerException - 如果 dragImage不是 null和 imageOffset是 null
        NullPointerException - 如果 t是 null
        IllegalArgumentException - 如果与触发事件相关联的 Component是 null 。
        IllegalArgumentException -如果 DragSource触发事件为 null 。
        IllegalArgumentException - 如果触发事件的拖动操作是 DnDConstants.ACTION_NONE 。
        IllegalArgumentException - 如果与触发事件相关联的 DragGestureRecognizer的源操作等于 DnDConstants.ACTION_NONE 。

      • getFlavorMap

        public FlavorMap getFlavorMap​()
        此方法为该 FlavorMap返回 DragSource 。
        结果
        该 FlavorMap为这 DragSource

      • createDragGestureRecognizer

        public <T extends DragGestureRecognizer> T createDragGestureRecognizer​(Class<T> recognizerAbstractClass,
                                                                       Component c,
                                                                       int actions,
                                                                       DragGestureListener dgl)
        创建一个新的 DragGestureRecognizer ，实现指定的抽象子类为 DragGestureRecognizer ，并在新创建的对象上设置指定的 Component和 DragGestureListener 。
        参数类型
        T - 要创建的类型 DragGestureRecognizer
        参数
        recognizerAbstractClass - 请求的抽象类型
        actions - 允许的源拖动操作
        c - Component目标
        dgl - 要通知的 DragGestureListener
        结果
        新的 DragGestureRecognizer或 null如果 Toolkit.createDragGestureRecognizer方法没有实现可用于请求的 DragGestureRecognizer子类并返回 null

      • createDefaultDragGestureRecognizer

        public DragGestureRecognizer createDefaultDragGestureRecognizer​(Component c,
                                                                int actions,
                                                                DragGestureListener dgl)
        创建一个新的DragGestureRecognizer实现的默认抽象子类DragGestureRecognizer这个DragSource ，并设置指定Component和DragGestureListener新创建的对象上。 对于这个DragSource ，默认值是MouseDragGestureRecognizer 。
        参数
        c - 识别器的 Component目标
        actions - 允许的源操作
        dgl - 要通知的 DragGestureListener
        结果
        新的 DragGestureRecognizer或 null如果 Toolkit.createDragGestureRecognizer方法没有实现可用于请求的 DragGestureRecognizer子类，并返回 null

      • removeDragSourceListener

        public void removeDragSourceListener​(DragSourceListener dsl)
        删除指定DragSourceListener从这个DragSource 。 如果指定了一个null监听器，则不会采取任何操作，也不会抛出任何异常。 如果参数指定的侦听器以前未添加到此DragSource ，则不会采取任何操作，也不会抛出任何异常。
        参数
        dsl - 要删除的 DragSourceListener
        从以下版本开始：
        1.4
        另请参见：
        addDragSourceListener(java.awt.dnd.DragSourceListener) ， getDragSourceListeners()

      • getListeners

        public <T extends EventListener> T[] getListeners​(Class<T> listenerType)
        获取当前注册的所有对象为FooListener s在此DragSource 。 FooListener是使用addFooListener方法注册的。
        参数类型
        T - 侦听器对象的类型
        参数
        listenerType - 所请求的听众的类型; 此参数应指定从java.util.EventListener下降的接口
        结果
        在这个 DragSource上注册为 FooListener的所有对象的数组，如果没有添加这样的侦听器，则是一个空数组
        异常
        ClassCastException - 如果 listenerType没有指定实现 java.util.EventListener的类或接口
        从以下版本开始：
        1.4
        另请参见：
        getDragSourceListeners() ， getDragSourceMotionListeners()

      • getDragThreshold

        public static int getDragThreshold​()
        返回拖动手势运动阈值。 拖动手势运动阈值定义了MouseDragGestureRecognizer的推荐行为。

        如果系统属性awt.dnd.drag.threshold设置为正整数，则此方法返回系统属性的值; 否则如果相关的桌面属性可用并且由Java平台的实现支持，则此方法返回该属性的值; 否则此方法返回一些默认值。 相关的桌面属性可以使用java.awt.Toolkit.getDesktopProperty("DnD.gestureMotionThreshold")进行查询。

        结果
        拖动手势运动阈值
        从以下版本开始：
        1.5
        另请参见：
        MouseDragGestureRecognizer