JavaTM 2 Platform
Standard Ed. 5.0

java.awt.dnd
类 DragSource

java.lang.Object
  继承者 java.awt.dnd.DragSource
所有已实现的接口:
Serializable

public class DragSource
extends Object
implements Serializable

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

一旦获得 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 的默认抽象子类并在新创建的对象上设置指定的 ComponentDragGestureListener
<T extends DragGestureRecognizer>
T
createDragGestureRecognizer(Class<T> recognizerAbstractClass, Component c, int actions, DragGestureListener dgl)
          创建一个新的 DragGestureRecognizer,实现 DragGestureRecognizer 的指定抽象子类并在新创建的对象上设置指定的 ComponentDragGestureListener
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()
          此方法返回此 DragSourceFlavorMap
<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、要拖动的 ImageImage 原点距离触发时 Cursor 热点的偏移量、拖动的目标数据和 DragSourceListener 的情况下开始拖动。
 void startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap)
          在给定发起拖动的 DragGestureEvent、使用的初始 Cursor、要拖动的 ImageImage 原点距离触发时 Cursor 热点的偏移量、拖动的 Transferable 目标数据、DragSourceListenerFlavorMap 的情况下开始拖动。
 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 目标数据、DragSourceListenerFlavorMap 的情况下开始拖动。
 
从类 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、要拖动的 ImageImage 原点距离触发时 Cursor 热点的偏移量、拖动的 Transferable 目标数据、DragSourceListenerFlavorMap 的情况下开始拖动。

参数:
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 目标数据、DragSourceListenerFlavorMap 的情况下开始拖动。

参数:
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、要拖动的 ImageImage 原点距离触发时 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 并重写此方法。

如果 dragImagenull,则没有用于表示此拖动操作拖动完成的反馈图像,但不抛出 NullPointerException

如果 dslnull,则没有向已创建的 DragSourceContext 注册的拖动源侦听器,但不抛出 NullPointerException

如果 dragCursornull,则此拖动操作使用默认的拖动光标。不抛出 NullPointerException

参数:
dscp - 此拖动的 DragSourceContextPeer
dgl - 触发拖动的 DragGestureEvent
dragCursor - 要显示的初始 Cursor
dragImage - 要拖动的 Image,或者为 null
imageOffset - Image 原点距离触发开始时 cursor 热点的偏移量
t - 拖动的目标数据
dsl - DragSourceListener
返回:
DragSourceContext
抛出:
NullPointerException - 如果 dscpnull
NullPointerException - 如果 dglnull
NullPointerException - 如果 dragImage 不为 null,并且 imageOffsetnull
NullPointerException - 如果 tnull
IllegalArgumentException - 如果与触发事件关联的 Componentnull
IllegalArgumentException - 如果触发事件的 DragSourcenull
IllegalArgumentException - 如果触发事件的拖动操作是 DnDConstants.ACTION_NONE
IllegalArgumentException - 如果与触发事件关联的 DragGestureRecognizer 的拖动源操作是 DnDConstants.ACTION_NONE

getFlavorMap

public FlavorMap getFlavorMap()
此方法返回此 DragSourceFlavorMap

返回:
DragSourceFlavorMap

createDragGestureRecognizer

public <T extends DragGestureRecognizer> T createDragGestureRecognizer(Class<T> recognizerAbstractClass,
                                                                       Component c,
                                                                       int actions,
                                                                       DragGestureListener dgl)
创建一个新的 DragGestureRecognizer,实现 DragGestureRecognizer 的指定抽象子类并在新创建的对象上设置指定的 ComponentDragGestureListener

参数:
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 的默认抽象子类并在新创建的对象上设置指定的 ComponentDragGestureListener。 对于此 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

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策