DragSource (Java 2 Platform SE 6)

概觀

軟體套件

類別

使用

階層樹

已過時

索引

說明

Java^TM 2 Platform
Standard Ed. 6

上一個類別 下一個類別

框架 無框架

摘要：巢狀 | 欄位 | 建構子 | 方法

詳細資訊：欄位 | 建構子 | 方法

java.awt.dnd
類別 DragSource

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

所有已實作的介面：: Serializable

public class DragSource
extends Object
implements Serializable
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