模块 java.desktop
包 java.awt.dnd

类 DragSource

java.lang.Object
java.awt.dnd.DragSource
所有已实现的接口：
Serializable
public class DragSource extends Object implements Serializable
DragSource 是负责启动拖放操作的实体，可用于多种场景：
  • 在 JVM 的生命周期内，每个 JVM 有 1 个默认实例。
  • 每个类的潜在拖动启动器对象（例如 TextField）1 个实例。 [取决于实现]
  • 每个特定 Component 的实例或与 GUI 中的 Component 实例关联的应用程序特定对象 1 个。 [取决于实施]
  • 其他一些任意关联。 [取决于实现]
获得 DragSource 后，还应获得 DragGestureRecognizer 以将 DragSource 与特定的 Component 相关联。

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

当出现拖动手势时，应调用 DragSource 的 startDrag() 方法，以便处理用户的导航手势并传递拖放协议通知。 DragSource 应只允许单个拖放操作在任何时候是当前的，并且应通过抛出 IllegalDnDOperationException 来拒绝任何进一步的 startDrag() 请求，直到现有操作完成。

startDrag() 方法调用 createDragSourceContext() 方法来实例化适当的 DragSourceContext 并将 DragSourceContextPeer 与其相关联。

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

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

自从：
1.2
参见：

  • 字段详细信息

    • DefaultCopyDrop

      public static final Cursor  DefaultCopyDrop
      默认 Cursor 与复制操作一起使用，指示当前允许放置。 null 如果 GraphicsEnvironment.isHeadless() 返回 true。
      参见：

    • DefaultMoveDrop

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

    • DefaultLinkDrop

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

    • DefaultCopyNoDrop

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

    • DefaultMoveNoDrop

      public static final Cursor  DefaultMoveNoDrop
      默认 Cursor 与移动操作一起使用，指示当前不允许放置。 null 如果 GraphicsEnvironment.isHeadless() 返回 true。
      参见：

    • DefaultLinkNoDrop

      public static final Cursor  DefaultLinkNoDrop
      默认 Cursor 与链接操作一起使用，指示当前不允许丢弃。 null 如果 GraphicsEnvironment.isHeadless() 返回 true。
      参见：

  • 构造方法详细信息

  • 方法详情

    • getDefaultDragSource

      public static DragSource  getDefaultDragSource()
      获取与底层平台关联的 DragSource 对象。
      返回：
      平台 DragSource
      抛出：
      HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true
      参见：

    • 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 热点的偏移量
      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 注册拖动源监听器，但不会抛出 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()
      此方法返回此 DragSource 的 FlavorMap。
      返回：
      这个DragSource的FlavorMap

    • createDragGestureRecognizer

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

    • createDefaultDragGestureRecognizer

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

    • addDragSourceListener

      public void addDragSourceListener(DragSourceListener  dsl)
      将指定的 DragSourceListener 添加到此 DragSource 以在使用此 DragSource 启动的拖动操作期间接收拖动源事件。如果指定了 null 监听器，则不会采取任何操作，也不会抛出异常。
      参数：
      dsl - 要添加的 DragSourceListener
      自从：
      1.4
      参见：

    • removeDragSourceListener

      public void removeDragSourceListener(DragSourceListener  dsl)
      从此 DragSource 中删除指定的 DragSourceListener。如果指定了 null 监听器，则不会采取任何操作，也不会抛出异常。如果参数指定的监听器之前未添加到此 DragSource ，则不采取任何操作并且不抛出异常。
      参数：
      dsl - 要删除的 DragSourceListener
      自从：
      1.4
      参见：

    • getDragSourceListeners

      public DragSourceListener [] getDragSourceListeners()
      获取使用此 DragSource 注册的所有 DragSourceListener 。
      返回：
      所有这些 DragSource 的 DragSourceListener 或空数组（如果当前没有注册此类监听器）
      自从：
      1.4
      参见：

    • addDragSourceMotionListener

      public void addDragSourceMotionListener(DragSourceMotionListener  dsml)
      将指定的 DragSourceMotionListener 添加到此 DragSource 以在使用此 DragSource 启动的拖动操作期间接收拖动运动事件。如果指定了 null 监听器，则不会采取任何操作，也不会抛出异常。
      参数：
      dsml - 要添加的 DragSourceMotionListener
      自从：
      1.4
      参见：

    • removeDragSourceMotionListener

      public void removeDragSourceMotionListener(DragSourceMotionListener  dsml)
      从此 DragSource 中删除指定的 DragSourceMotionListener。如果指定了 null 监听器，则不会采取任何操作，也不会抛出异常。如果参数指定的监听器之前未添加到此 DragSource ，则不采取任何操作并且不抛出异常。
      参数：
      dsml - 要删除的 DragSourceMotionListener
      自从：
      1.4
      参见：

    • getDragSourceMotionListeners

      public DragSourceMotionListener [] getDragSourceMotionListeners()
      获取使用此 DragSource 注册的所有 DragSourceMotionListener 。
      返回：
      所有这些 DragSource 的 DragSourceMotionListener 或空数组（如果当前没有注册此类监听器）
      自从：
      1.4
      参见：

    • getListeners

      public <T extends EventListener > T[] getListeners(Class <T> listenerType)
      获取当前在此 DragSource 上注册为 FooListener 的所有对象。 FooListener 是使用 addFooListener 方法注册的。
      类型参数：
      T - 监听器对象的类型
      参数：
      listenerType - 请求的监听器类型；此参数应指定从 java.util.EventListener 派生的接口
      返回：
      在此 DragSource 上注册为 FooListener 的所有对象的数组，如果没有添加此类监听器，则为空数组
      抛出：
      ClassCastException - 如果 listenerType 没有指定实现 java.util.EventListener 的类或接口
      自从：
      1.4
      参见：

    • getDragThreshold

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

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

      返回：
      拖动手势运动阈值
      自从：
      1.5
      参见：