Module java.desktop
Package java.awt.dnd

Class DragSourceContext

java.lang.Object
java.awt.dnd.DragSourceContext
所有已实现的接口:
DragSourceListener, DragSourceMotionListener, Serializable, EventListener
public class DragSourceContext extends Object implements DragSourceListener, DragSourceMotionListener, Serializable
DragSourceContext类负责管理拖放协议的发起方。特别是，它负责向DragSourceListeners和DragSourceMotionListeners管理拖动事件通知，并提供代表拖动操作源数据的Transferable。

请注意，DragSourceContext本身实现了DragSourceListener和DragSourceMotionListener接口。这是为了允许由DragSource创建的平台对等体（DragSourceContextPeer实例）通知正在进行的操作中的状态更改给DragSourceContext。这使得DragSourceContext对象能够介入平台和拖动操作发起方提供的侦听器之间。

默认情况下，DragSourceContext根据拖放操作的当前状态设置光标。例如，如果用户选择了移动操作，并且指针位于接受移动操作的目标上方，则显示默认的移动光标。当指针位于不接受传输的区域上方时，则显示默认的“不可放置”光标。

当通过setCursor(java.awt.Cursor)方法设置自定义光标时，将禁用此默认处理机制。当禁用默认处理时，开发人员有责任通过监听DragSource事件并调用setCursor()方法来保持光标最新。或者，您可以通过提供DragSource和DragSourceContext类的自定义实现来提供自定义光标行为。

自 JDK 版本:
1.2
参见:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final int
    CHANGED
    由updateCurrentCursor()使用的int，指示用户操作已更改。
    protected static final int
    DEFAULT
    由updateCurrentCursor()使用的int，指示Cursor应更改为默认（不可放置）Cursor。
    protected static final int
    ENTER
    由updateCurrentCursor()使用的int，指示Cursor已进入DropTarget。
    protected static final int
    OVER
    由updateCurrentCursor()使用的int，指示Cursor位于DropTarget上方。

  • Constructor Summary

    Constructors
    Constructor
    Description
    DragSourceContext(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point offset, Transferable t, DragSourceListener dsl)
    从DragSource调用，此构造函数根据此拖动的DragSourceContextPeer、触发拖动的DragGestureEvent、用于拖动的初始Cursor、（可选的）在进行拖动时显示的Image、Image原点与触发事件热点的偏移量、主题数据的Transferable和在拖放操作期间使用的DragSourceListener创建一个新的DragSourceContext。

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addDragSourceListener(DragSourceListener dsl)
    如果尚未添加DragSourceListener，则向此DragSourceContext添加一个。
    void
    dragDropEnd(DragSourceDropEvent dsde)
    在此DragSourceContext注册的DragSourceListener和相关DragSource上调用dragDropEnd，并传递指定的DragSourceDropEvent。
    void
    dragEnter(DragSourceDragEvent dsde)
    在此DragSourceContext注册的DragSourceListener和相关DragSource上调用dragEnter，并传递指定的DragSourceDragEvent。
    void
    dragExit(DragSourceEvent dse)
    在此DragSourceContext注册的DragSourceListener和相关DragSource上调用dragExit，并传递指定的DragSourceEvent。
    void
    dragMouseMoved(DragSourceDragEvent dsde)
    在与此DragSourceContext关联的DragSource上注册的DragSourceMotionListener上调用dragMouseMoved，并传递指定的DragSourceDragEvent。
    void
    dragOver(DragSourceDragEvent dsde)
    在此DragSourceContext注册的DragSourceListener和相关DragSource上调用dragOver，并传递指定的DragSourceDragEvent。
    void
    dropActionChanged(DragSourceDragEvent dsde)
    在此DragSourceContext注册的DragSourceListener和相关DragSource上调用dropActionChanged，并传递指定的DragSourceDragEvent。
    Component
    getComponent()
    返回与此DragSourceContext关联的Component。
    Cursor
    getCursor()
    返回当前自定义拖动Cursor。
    DragSource
    getDragSource()
    返回实例化此DragSourceContext的DragSource。
    int
    getSourceActions()
    返回由此DragSourceContext关联的拖动源支持的拖放操作的DnDConstants的位掩码。
    Transferable
    getTransferable()
    返回与此DragSourceContext关联的Transferable。
    DragGestureEvent
    getTrigger()
    返回最初触发拖动的DragGestureEvent。
    void
    removeDragSourceListener(DragSourceListener dsl)
    从此DragSourceContext中删除指定的DragSourceListener。
    void
    setCursor(Cursor c)
    将此拖动操作的自定义光标设置为指定的Cursor。
    void
    transferablesFlavorsChanged()
    通知对等体Transferable的DataFlavor已更改。
    protected void
    updateCurrentCursor(int sourceAct, int targetAct, int status)
    如果默认拖动光标行为处于活动状态，则此方法为拖动源支持的指定操作、放置目标操作和状态设置默认拖动光标，否则此方法不执行任何操作。

    Methods declared in class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT

      protected static final int DEFAULT
      由updateCurrentCursor()使用的int，指示Cursor应更改为默认（不可放置）Cursor。
      参见:

    • ENTER

      protected static final int ENTER
      由updateCurrentCursor()使用的int，指示Cursor已进入DropTarget。
      参见:

    • OVER

      protected static final int OVER
      由updateCurrentCursor()使用的int，指示Cursor位于DropTarget上方。
      参见:

    • CHANGED

      protected static final int CHANGED
      由updateCurrentCursor()使用的int，指示用户操作已更改。
      参见:

  • Constructor Details

    • DragSourceContext

      public DragSourceContext(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point offset, Transferable t, DragSourceListener dsl)
      从DragSource调用，此构造函数根据此拖动的DragSourceContextPeer、触发拖动的DragGestureEvent、用于拖动的初始Cursor、（可选的）在进行拖动时显示的Image、Image原点与触发事件热点的偏移量、主题数据的Transferable和在拖放操作期间使用的DragSourceListener创建一个新的DragSourceContext。
      如果DragSourceContextPeer为null，则抛出NullPointerException。
      如果DragGestureEvent为null，则抛出NullPointerException。
      如果Cursor为null，则不会抛出异常，并且为此拖动操作激活默认拖动光标行为。
      如果Image为null，则不会抛出异常。
      如果Image不为null且偏移量为null NullPointerException，则抛出异常。
      如果Transferable为null，则抛出NullPointerException。
      如果DragSourceListener为null，则不会抛出异常。
      参数:
      trigger - 触发事件
      dragCursor - 此拖动操作的初始Cursor，或null表示默认的光标处理；有关拖放期间光标处理机制的更多详细信息，请参见类级文档
      dragImage - 要拖动的Image（或null）
      offset - 图像原点与触发事件热点的偏移量
      t - Transferable
      dsl - DragSourceListener
      抛出:
      IllegalArgumentException - 如果与触发事件关联的Component为null。
      IllegalArgumentException - 如果触发事件的DragSource为null。
      IllegalArgumentException - 如果触发事件的拖动操作为DnDConstants.ACTION_NONE。
      IllegalArgumentException - 如果与触发事件关联的DragGestureRecognizer的源操作等于DnDConstants.ACTION_NONE。
      NullPointerException - 如果dscp、trigger或t为null，或者如果dragImage为非null且offset为null

  • Method Details

    • getDragSource

      public DragSource getDragSource()
      返回实例化此DragSourceContext的DragSource。
      返回:
      实例化此DragSourceContext的DragSource

    • getComponent

      public Component getComponent()
      返回与此DragSourceContext关联的Component。
      返回:
      启动拖动的Component

    • getTrigger

      public DragGestureEvent getTrigger()
      返回最初触发拖动的DragGestureEvent。
      返回:
      触发拖动的事件

    • getSourceActions

      public int getSourceActions()
      返回DragSourceContext关联的拖动源支持的一组放置操作的位掩码DnDConstants。
      返回:
      拖动源支持的放置操作

    • setCursor

      public void setCursor(Cursor c)
      将此拖动操作的自定义光标设置为指定的Cursor。如果指定的Cursor为null，则为此拖动操作激活默认拖动光标行为，否则将其停用。
      参数:
      c - 此拖动操作的初始Cursor，或null表示默认的光标处理；有关拖放期间光标处理的更多详细信息，请参见类级文档

    • getCursor

      public Cursor getCursor()
      返回当前自定义拖动Cursor。
      返回:
      当前自定义拖动Cursor，如果已设置则返回null。
      另请参阅:

    • addDragSourceListener

      public void addDragSourceListener(DragSourceListener dsl) throws TooManyListenersException
      如果尚未添加DragSourceListener，则向此DragSourceContext添加一个。如果已存在DragSourceListener，则此方法会抛出TooManyListenersException。
      参数:
      dsl - 要添加的DragSourceListener。请注意，虽然null不被禁止，但不可接受作为参数。
      抛出:
      TooManyListenersException - 如果已添加DragSourceListener

    • removeDragSourceListener

      public void removeDragSourceListener(DragSourceListener dsl)
      从此DragSourceContext中删除指定的DragSourceListener。
      参数:
      dsl - 要删除的DragSourceListener；请注意，虽然null不被禁止，但不可接受作为参数

    • transferablesFlavorsChanged

      public void transferablesFlavorsChanged()
      通知对等体Transferable的DataFlavor已更改。

    • dragEnter

      public void dragEnter(DragSourceDragEvent dsde)
      在此DragSourceContext注册的DragSourceListener和关联的DragSource上调用dragEnter，并传递指定的DragSourceDragEvent。
      指定者:
      dragEnter 在接口 DragSourceListener中
      参数:
      dsde - DragSourceDragEvent

    • dragOver

      public void dragOver(DragSourceDragEvent dsde)
      在此DragSourceContext注册的DragSourceListener和关联的DragSource上调用dragOver，并传递指定的DragSourceDragEvent。
      指定者:
      dragOver 在接口 DragSourceListener中
      参数:
      dsde - DragSourceDragEvent

    • dragExit

      public void dragExit(DragSourceEvent dse)
      在此DragSourceContext注册的DragSourceListener和关联的DragSource上调用dragExit，并传递指定的DragSourceEvent。
      指定者:
      dragExit 在接口 DragSourceListener中
      参数:
      dse - DragSourceEvent

    • dropActionChanged

      public void dropActionChanged(DragSourceDragEvent dsde)
      在此DragSourceContext注册的DragSourceListener和关联的DragSource上调用dropActionChanged，并传递指定的DragSourceDragEvent。
      指定者:
      dropActionChanged 在接口 DragSourceListener中
      参数:
      dsde - DragSourceDragEvent

    • dragDropEnd

      public void dragDropEnd(DragSourceDropEvent dsde)
      在此DragSourceContext注册的DragSourceListener和关联的DragSource上调用dragDropEnd，并传递指定的DragSourceDropEvent。
      指定者:
      dragDropEnd 在接口 DragSourceListener中
      参数:
      dsde - DragSourceDropEvent

    • dragMouseMoved

      public void dragMouseMoved(DragSourceDragEvent dsde)
      在与此DragSourceContext关联的DragSource上注册的DragSourceMotionListener上调用dragMouseMoved，并传递指定的DragSourceDragEvent。
      指定者:
      dragMouseMoved 在接口 DragSourceMotionListener中
      参数:
      dsde - DragSourceDragEvent
      自1.4起:
      1.4

    • getTransferable

      public Transferable getTransferable()
      返回与此DragSourceContext关联的Transferable。
      返回:
      Transferable

    • updateCurrentCursor

      protected void updateCurrentCursor(int sourceAct, int targetAct, int status)
      如果默认拖动光标行为处于活动状态，则此方法为拖动源支持的指定操作设置默认拖动光标，否则此方法不执行任何操作。
      参数:
      sourceAct - 拖动源支持的操作
      targetAct - 丢放目标操作
      status - 字段之一DEFAULT、ENTER、OVER、CHANGED