java.awt.dnd
类 DragSource

java.lang.Object
  java.awt.dnd.DragSource

所有已实现的接口：

Serializable

public class DragSource
extends Object
implements Serializable

DragSource 是负责开始 Drag 和 Drop 操作的实体，可以用在如下场景中：

• JVM 生命周期中每个 JVM 的一个默认实例。
• 每个潜在 Drag 初始程序对象（例如 TextField）类的一个实例。[与实现相关]
• 每个特定 Component 一个实例，或者每个与 GUI 中 Component 实例相关联的特定应用程序对象一个实例。[与实现相关]
• 其他一些任意的关联。[与实现相关]

一旦获得 DragSource，还应获得一个 DragGestureRecognizer，以便将该 DragSource 与特定的 Component 关联。

通常是由 DragGestureRecognizer 来实现一个 implementing Component，而这个 implementing component 负责用户操作的初始解释和随后开始的拖动操作。

出现一个拖动操作时，应调用 DragSource 的 startDrag() 方法，以处理用户的浏览操作并传递 Drag 和 Drop 协议通知。DragSource 只允许在任一时刻执行一个 Drag 和 Drop 操作，并且在现存的操作完成前，通过抛出 IllegalDnDOperationException 来拒绝所有其他的 startDrag() 请求。

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

如果 Drag 和 Drop 系统由于某些原因而无法开始拖动操作，则 startDrag() 方法抛出 java.awt.dnd.InvalidDnDOperationException 来通知该状况。通常在基础平台系统未处于可初始拖动的状态或者指定的参数无效时抛出此异常。

注意，在拖动期间，操作完成前不能改变拖动源在拖动操作开始时所公开的操作集合。操作持续期间该操作对于 DragSource 而言是持续的。

从以下版本开始：

1.2

另请参见：

序列化表格

字段摘要

static Cursor	DefaultCopyDrop 用于复制操作的默认 Cursor，指示当前允许放置。
static Cursor	DefaultCopyNoDrop 用于复制操作的默认 Cursor，指示当前不允许放置。
static Cursor	DefaultLinkDrop 用于链接操作的默认 Cursor，指示当前允许放置。
static Cursor	DefaultLinkNoDrop 用于链接操作的默认 Cursor，指示当前不允许放置。
static Cursor	DefaultMoveDrop 用于移动操作的默认 Cursor，指示当前允许放置。
static Cursor	DefaultMoveNoDrop 用于移动操作的默认 Cursor，指示当前不允许放置。

构造方法摘要

DragSource()
创建一个新的 DragSource。

方法摘要

void	addDragSourceListener(DragSourceListener dsl) 将指定的 DragSourceListener 添加到此 DragSource，以接收在使用此 DragSource 所发起的拖动操作期间出现的拖动源事件。
void	addDragSourceMotionListener(DragSourceMotionListener dsml) 将指定的 DragSourceMotionListener 添加到此 DragSource，以接收在使用此 DragSource 所发起的拖动操作期间出现的拖动移动事件。
DragGestureRecognizer	createDefaultDragGestureRecognizer(Component c, int actions, DragGestureListener dgl) 创建一个新的 DragGestureRecognizer，为此 DragSource 实现 DragGestureRecognizer 的默认抽象子类并在新创建的对象上设置指定的 Component 和 DragGestureListener。
<T extends DragGestureRecognizer> T	createDragGestureRecognizer(Class<T> recognizerAbstractClass, Component c, int actions, DragGestureListener dgl) 创建一个新的 DragGestureRecognizer，实现 DragGestureRecognizer 的指定抽象子类并在新创建的对象上设置指定的 Component 和 DragGestureListener。
protected DragSourceContext	createDragSourceContext(java.awt.dnd.peer.DragSourceContextPeer dscp, DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable t, DragSourceListener dsl) 创建处理此拖动的 DragSourceContext。
static DragSource	getDefaultDragSource() 获得与基础平台关联的 DragSource 对象。
DragSourceListener[]	getDragSourceListeners() 获得向此 DragSource 注册的所有 DragSourceListener。
DragSourceMotionListener[]	getDragSourceMotionListeners() 获得向此 DragSource 注册的所有 DragSourceMotionListener。
static int	getDragThreshold() 返回拖动操作移动阈值。
FlavorMap	getFlavorMap() 此方法返回此 DragSource 的 FlavorMap。
<T extends EventListener> T[]	getListeners(Class<T> listenerType) 获得目前已在此 DragSource 上注册为 FooListener 的所有对象。
static boolean	isDragImageSupported() 报告基础平台是否提供对拖动 Image 的支持。
void	removeDragSourceListener(DragSourceListener dsl) 从此 DragSource 移除指定的 DragSourceListener。
void	removeDragSourceMotionListener(DragSourceMotionListener dsml) 从此 DragSource 移除指定的 DragSourceMotionListener。
void	startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point dragOffset, Transferable transferable, DragSourceListener dsl) 在给定发起拖动的 DragGestureEvent、使用的初始 Cursor、要拖动的 Image、Image 原点距离触发时 Cursor 热点的偏移量、拖动的目标数据和 DragSourceListener 的情况下开始拖动。
void	startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap) 在给定发起拖动的 DragGestureEvent、使用的初始 Cursor、要拖动的 Image、Image 原点距离触发时 Cursor 热点的偏移量、拖动的 Transferable 目标数据、DragSourceListener 和 FlavorMap 的情况下开始拖动。
void	startDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl) 在给定发起拖动的 DragGestureEvent、使用的初始 Cursor、拖动的 Transferable 目标数据和 DragSourceListener 的情况下开始拖动。
void	startDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap) 在给定发起拖动的 DragGestureEvent、使用的初始 Cursor、拖动的 Transferable 目标数据、DragSourceListener 和 FlavorMap 的情况下开始拖动。

从类 java.lang.Object 继承的方法

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

字段详细信息

DefaultCopyDrop

public static final Cursor DefaultCopyDrop

用于复制操作的默认 Cursor，指示当前允许放置。如果 GraphicsEnvironment.isHeadless() 返回 true，则为 null。

另请参见：

GraphicsEnvironment.isHeadless()

DefaultMoveDrop

public static final Cursor DefaultMoveDrop

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

另请参见：

GraphicsEnvironment.isHeadless()

DefaultLinkDrop

public static final Cursor DefaultLinkDrop

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

另请参见：

GraphicsEnvironment.isHeadless()

DefaultCopyNoDrop

public static final Cursor DefaultCopyNoDrop

用于复制操作的默认 Cursor，指示当前不允许放置。如果 GraphicsEnvironment.isHeadless() 返回 true，则为 null。

另请参见：

GraphicsEnvironment.isHeadless()

DefaultMoveNoDrop

public static final Cursor DefaultMoveNoDrop

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

另请参见：

GraphicsEnvironment.isHeadless()

DefaultLinkNoDrop

public static final Cursor DefaultLinkNoDrop

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

另请参见：

GraphicsEnvironment.isHeadless()

构造方法详细信息

DragSource

public DragSource()
           throws HeadlessException

创建一个新的 DragSource。

抛出：

HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true

另请参见：

GraphicsEnvironment.isHeadless()

方法详细信息

getDefaultDragSource

public static DragSource getDefaultDragSource()

获得与基础平台关联的 DragSource 对象。

返回：

平台 DragSource

抛出：

HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true

另请参见：

GraphicsEnvironment.isHeadless()

isDragImageSupported

public static boolean isDragImageSupported()

报告基础平台是否提供对拖动 Image 的支持。

返回：

此平台是否提供对拖动 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

dragImage - 要拖动的图像，或者为 null。

imageOffset - Image 原点距离触发时 Cursor 热点的偏移量

transferable - 该拖动的目标数据

dsl - DragSourceListener

flavorMap - 使用的 FlavorMap，或者为 null

抛出：

java.awt.dnd.InvalidDnDOperationException - 如果 Drag 和 Drop 系统不能发起拖动操作，或者用户试图在现有拖动操作仍在进行时开始拖动。

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

transferable - 拖动的目标数据

dsl - DragSourceListener

flavorMap - 使用的 FlavorMap，或者为 null

抛出：

java.awt.dnd.InvalidDnDOperationException - 如果 Drag 和 Drop 系统不能发起拖动操作，或者用户试图在现有拖动操作仍在进行时开始拖动。

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

dragImage - 要拖动的 Image，或者为 null

dragOffset - Image 原点距离触发开始时 Cursor 热点的偏移量

transferable - 拖动的目标数据

dsl - DragSourceListener

抛出：

java.awt.dnd.InvalidDnDOperationException - 如果 Drag 和 Drop 系统不能发起拖动操作，或者用户试图在现有拖动操作仍在进行时开始拖动。

InvalidDnDOperationException

startDrag

public void startDrag(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Transferable transferable,
                      DragSourceListener dsl)
               throws InvalidDnDOperationException

在给定发起拖动的 DragGestureEvent、使用的初始 Cursor、拖动的 Transferable 目标数据和 DragSourceListener 的情况下开始拖动。

参数：

trigger - 发起拖动的 DragGestureEvent

dragCursor - 初始 Cursor，或默认为 null

transferable - 拖动的目标数据

dsl - DragSourceListener

抛出：

java.awt.dnd.InvalidDnDOperationException - 如果 Drag 和 Drop 系统不能发起拖动操作，或者用户试图在现有拖动操作仍在进行时开始拖动。

InvalidDnDOperationException

createDragSourceContext

protected DragSourceContext createDragSourceContext(java.awt.dnd.peer.DragSourceContextPeer dscp,
                                                    DragGestureEvent dgl,
                                                    Cursor dragCursor,
                                                    Image dragImage,
                                                    Point imageOffset,
                                                    Transferable t,
                                                    DragSourceListener dsl)

创建处理此拖动的 DragSourceContext。

要合并一个新的 DragSourceContext 子类，可子类化 DragSource 并重写此方法。

如果 dragImage 为 null，则没有用于表示此拖动操作拖动完成的反馈图像，但不抛出 NullPointerException。

如果 dsl 为 null，则没有向已创建的 DragSourceContext 注册的拖动源侦听器，但不抛出 NullPointerException。

如果 dragCursor 为 null，则此拖动操作使用默认的拖动光标。不抛出 NullPointerException。

参数：

dscp - 此拖动的 DragSourceContextPeer

dgl - 触发拖动的 DragGestureEvent

dragCursor - 要显示的初始 Cursor

dragImage - 要拖动的 Image，或者为 null

imageOffset - Image 原点距离触发开始时 cursor 热点的偏移量

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。

参数：

recognizerAbstractClass - 所请求的抽象类型

actions - 允许的源拖动操作

c - Component 目标

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(java.awt.dnd.DragSourceListener), getDragSourceListeners()

removeDragSourceListener

public void removeDragSourceListener(DragSourceListener dsl)

从此 DragSource 移除指定的 DragSourceListener。如果指定的侦听器为 null，则不采取操作并且不抛出异常。如果该参数所指定的侦听器不是以前添加到此 DragSource 的侦听器，则不采取任何操作并且不抛出任何异常。

参数：

dsl - 要移除的 DragSourceListener

从以下版本开始：

1.4

另请参见：

addDragSourceListener(java.awt.dnd.DragSourceListener), getDragSourceListeners()

getDragSourceListeners

public DragSourceListener[] getDragSourceListeners()

获得向此 DragSource 注册的所有 DragSourceListener。

返回：

此 DragSource 的所有 DragSourceListener，如果当前没有注册这样的侦听器，则返回一个空数组

从以下版本开始：

1.4

另请参见：

addDragSourceListener(java.awt.dnd.DragSourceListener), removeDragSourceListener(java.awt.dnd.DragSourceListener)

addDragSourceMotionListener

public void addDragSourceMotionListener(DragSourceMotionListener dsml)

将指定的 DragSourceMotionListener 添加到此 DragSource，以接收在使用此 DragSource 所发起的拖动操作期间出现的拖动移动事件。如果指定的侦听器为 null，则不采取任何操作并且不抛出任何异常。

参数：

dsml - 要添加的 DragSourceMotionListener

从以下版本开始：

1.4

另请参见：

removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener), getDragSourceMotionListeners()

removeDragSourceMotionListener

public void removeDragSourceMotionListener(DragSourceMotionListener dsml)

从此 DragSource 移除指定的 DragSourceMotionListener。如果指定的侦听器为 null，则不采取任何操作并且不抛出任何异常。如果该参数所指定的侦听器不是以前添加到此 DragSource 的侦听器，则不采取任何操作并且不抛出任何异常。

参数：

dsml - 要移除的 DragSourceMotionListener

从以下版本开始：

1.4

另请参见：

addDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener), getDragSourceMotionListeners()

getDragSourceMotionListeners

public DragSourceMotionListener[] getDragSourceMotionListeners()

获得向此 DragSource 注册的所有 DragSourceMotionListener。

返回：

此 DragSource 的所有 DragSourceMotionListener，如果当前没有注册这样的侦听器，则返回一个空数组

从以下版本开始：

1.4

另请参见：

addDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener), removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)

获得目前已在此 DragSource 上注册为 FooListener 的所有对象。FooListener 是用 addFooListener 方法注册的。

参数：

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