Module java.desktop
Package java.awt.dnd

Class DragSource

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

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

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

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

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

请注意，在拖动过程中，源在拖动操作开始时暴露的操作集可能在操作完成之前不会更改。操作在操作期间相对于DragSource是恒定的。

自从:
1.2
参见:

  • Field Details

    • DefaultCopyDrop

      public static final Cursor DefaultCopyDrop
      用于指示当前允许放置的拷贝操作的默认Cursor。如果GraphicsEnvironment.isHeadless()返回true，则为null。
      参见:

    • DefaultMoveDrop

      public static final Cursor DefaultMoveDrop
      用于指示当前允许放置的移动操作的默认Cursor。如果GraphicsEnvironment.isHeadless()返回true，则为null。
      参见:

    • DefaultLinkDrop

      public static final Cursor DefaultLinkDrop
      用于指示当前允许放置的链接操作的默认Cursor。如果GraphicsEnvironment.isHeadless()返回true，则为null。
      参见:

    • DefaultCopyNoDrop

      public static final Cursor DefaultCopyNoDrop
      用于指示当前不允许放置的拷贝操作的默认Cursor。如果GraphicsEnvironment.isHeadless()返回true，则为null。
      参见:

    • DefaultMoveNoDrop

      public static final Cursor DefaultMoveNoDrop
      用于指示当前不允许放置的移动操作的默认Cursor。如果GraphicsEnvironment.isHeadless()返回true，则为null。
      参见:

    • DefaultLinkNoDrop

      public static final Cursor DefaultLinkNoDrop
      用于指示当前不允许放置的链接操作的默认Cursor。如果GraphicsEnvironment.isHeadless()返回true，则为null。
      参见:

  • Constructor Details

  • Method Details

    • getDefaultDragSource

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

    • isDragImageSupported

      public static boolean isDragImageSupported()
      报告底层平台是否支持拖动Image。
      返回:
      如果此平台支持拖动图像，则为true

    • 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，如果Toolkit.createDragGestureRecognizer方法对于请求的DragGestureRecognizer子类没有可用的实现并返回null，则返回null

    • createDefaultDragGestureRecognizer

      public DragGestureRecognizer createDefaultDragGestureRecognizer(Component c, int actions, DragGestureListener dgl)
      创建一个新的DragGestureRecognizer，实现此DragSource的默认DragGestureRecognizer抽象子类，并在新创建的对象上设置指定的Component和DragGestureListener。对于此DragSource，默认值为MouseDragGestureRecognizer。
      参数:
      c - 识别器的目标Component
      actions - 允许的源操作
      dgl - 要通知的DragGestureListener
      返回:
      新的DragGestureRecognizer，如果Toolkit.createDragGestureRecognizer方法对于请求的DragGestureRecognizer子类没有可用的实现并返回null，则返回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)
      向此DragSource添加指定的DragSourceMotionListener，以在使用此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的所有对象。使用addFooListener方法注册FooListener。
      类型参数:
      T - 监听器对象的类型
      参数:
      listenerType - 请求的监听器类型；此参数应指定一个从java.util.EventListener继承的接口
      返回:
      在此DragSource上注册为FooListener的所有对象的数组，如果尚未添加任何此类监听器，则返回一个空数组
      抛出:
      ClassCastException - 如果listenerType未指定实现java.util.EventListener的类或接口
      自版本:
      1.4
      另请参阅:

    • getDragThreshold

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

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

      返回:
      拖动手势运动阈值
      自版本:
      1.5
      另请参阅: