javax.swing
類別 TransferHandler

java.lang.Object
  javax.swing.TransferHandler

所有已實作的介面：

Serializable

public class TransferHandler
extends Object
implements Serializable

此類別用於處理往返於 Swing 元件的 Transferable 的傳輸。該 Transferable 用於表示通過往/返於剪貼板的剪切、複製或粘貼操作進行交換的資料。它還在拖放操作中使用，以表示對元件進行拖動和放置元件。Swing 提供自動支持剪切、複製和粘貼的鍵盤綁定的功能，該鍵盤綁定使用由此類別的實作提供的功能。Swing 還提供自動支持拖放操作的功能，該拖放操作使用由此類別的實作提供的功能。Swing 開發人員可以主要通過在 Swing 元件上設置 transferHandler 屬性專門指定傳輸語義。

只通過指定建構子中的屬性名稱即可實作此類別，以提供傳輸某個元件屬性的預設行為。例如，要通過剪貼板或拖放操作將前景色從一個元件傳輸到另一個元件，可以使用字元串 "foreground" 建構一個 TransferHandler。內置支持將把由 getForeground 返回的顏色用作該傳輸的源，把由 setForeground 返回的顏色用作傳輸的目標。

有關更多資訊，請參閱 The Java Tutorial 中的 How to Use Drag and Drop and Data Transfer 一節。

從以下版本開始：

1.4

巢狀類別摘要

static class	TransferHandler.DropLocation 表示放置的資料 (dropped data) 應該插入的位置。
static class	TransferHandler.TransferSupport 此類別封裝剪貼板或拖放傳輸的所有相關詳細資訊，並且還允許自定義拖放過程的各方面。

欄位摘要

static int	COPY 表示“複製”傳輸動作的 int 值。
static int	COPY_OR_MOVE 表示“複製”或“移動”的源操作功能的 int 值。
static int	LINK 表示「連接」傳輸動作的 int 值。
static int	MOVE 表示“移動”傳輸動作的 int 值。
static int	NONE 表示無傳輸動作的 int 值。

建構子摘要

protected	TransferHandler() 子類別的便捷建構子。
	TransferHandler(String property) 建構一個通過剪貼板或拖放操作可以將 Java Bean 屬性從一個元件傳輸到另一個元件的傳輸處理程序。

方法摘要

boolean	canImport(JComponent comp, DataFlavor[] transferFlavors) 指示一個元件在實際嘗試導入給定資料 flavor 的集合之前是否接受其導入。
boolean	canImport(TransferHandler.TransferSupport support) 在拖放操作期間重複調用此方法，以允許開發人員配置傳輸的可接受性屬性，並返回傳輸的可接受性；返回 true 值指示給定 TransferSupport（它包含該傳輸的所有細節）所表示的傳輸在當前是可以接受的，false 值指示拒絕該傳輸。
protected Transferable	createTransferable(JComponent c) 創建一個要用作資料傳輸源的 Transferable。
void	exportAsDrag(JComponent comp, InputEvent e, int action) 導致 Swing 拖動支持的啟用。
protected void	exportDone(JComponent source, Transferable data, int action) 在導出資料之後調用。
void	exportToClipboard(JComponent comp, Clipboard clip, int action) 導致從給定元件到給定剪貼板的傳輸。
static Action	getCopyAction() 返回一個執行複製到剪貼板操作的 Action。
static Action	getCutAction() 返回一個執行剪切到剪貼板操作的 Action。
static Action	getPasteAction() 返回一個從剪貼板執行粘貼操作的 Action。
int	getSourceActions(JComponent c) 返回源支持的傳輸動作的型別；COPY、MOVE 和 LINK 的任意按位或組合。
Icon	getVisualRepresentation(Transferable t) 返回一個建立傳輸外觀的物件。
boolean	importData(JComponent comp, Transferable t) 導致從剪貼板或 DND 放置操作向元件的傳輸。
boolean	importData(TransferHandler.TransferSupport support) 導致從剪貼板或拖放操作的傳輸。

從類別 java.lang.Object 繼承的方法

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

欄位詳細資訊

NONE

public static final int NONE

表示無傳輸動作的 int 值。

另請參見：

常數欄位值

COPY

public static final int COPY

表示“複製”傳輸動作的 int 值。將資料複製到剪貼板或複製到拖放操作中其他位置時使用此值。

另請參見：

常數欄位值

MOVE

public static final int MOVE

表示“移動”傳輸動作的 int 值。將資料移動到剪貼板（即剪切）或移動到拖放操作中的其他位置時使用此值。

另請參見：

常數欄位值

COPY_OR_MOVE

public static final int COPY_OR_MOVE

表示“複製”或“移動”的源操作功能的 int 值。

另請參見：

常數欄位值

LINK

public static final int LINK

表示「連接」傳輸動作的 int 值。此值用於指定應該以拖放操作連接資料。

從以下版本開始：

1.6

另請參見：

DnDConstants.ACTION_LINK, 常數欄位值

建構子詳細資訊

TransferHandler

public TransferHandler(String property)

建構一個通過剪貼板或拖放操作可以將 Java Bean 屬性從一個元件傳輸到另一個元件的傳輸處理程序。

參數：

property - 要傳輸的屬性的名稱；如果沒有與該傳輸處理程序相關的屬性（例如，執行其他某種傳輸的子類別），則可以為 null

TransferHandler

protected TransferHandler()

子類別的便捷建構子。

方法詳細資訊

getCutAction

public static Action getCutAction()

返回一個執行剪切到剪貼板操作的 Action。在執行時，此動作通過對元件的 TransferHandler 調用帶 MOVE 動作的 exportToClipboard，在 ActionEvent 的 JComponent 源上進行操作。

返回：

一個執行剪切到剪貼板的 Action

getCopyAction

public static Action getCopyAction()

返回一個執行複製到剪貼板操作的 Action。在執行時，此動作通過對元件的 TransferHandler 調用帶 COPY 動作的 exportToClipboard，在 ActionEvent 的 JComponent 源上進行操作。

返回：

一個執行複製到剪貼板的 Action

getPasteAction

public static Action getPasteAction()

返回一個從剪貼板執行粘貼操作的 Action。在執行時，此動作通過對元件的 TransferHandler 調用帶有剪貼板內容的 importData，在 ActionEvent 的 JComponent 源上進行操作。

返回：

一個從剪貼板執行粘貼的 Action

exportAsDrag

public void exportAsDrag(JComponent comp,
                         InputEvent e,
                         int action)

導致 Swing 拖動支持的啟用。如果在元件上設置 dragEnabled 屬性，則由 javax.swing.plaf.basic 套件中的各種 UI 實作調用此方法。可由使用 Swing 拖動支持的自定義 UI 實作調用此方法。也可由作為 JComponent 的子類別寫入的 Swing 擴展調用此方法，以利用 Swing 拖動支持。

傳輸不必 在返回此調用時完成（即該調用不會在等待放置時阻塞）。該傳輸將通過 java.awt.dnd 機制的 Swing 實作進行，無需開發人員投入更大精力。完成該傳輸時將調用 exportDone 方法。

參數：

comp - 存儲要傳輸的資料的元件；提供此參數以啟用 TransferHandler 的共享

e - 觸發該傳輸的事件

action - 最初請求的傳輸動作；為 COPY、MOVE 或 LINK；DnD 系統可以在執行拖動操作的過程中更改所使用的動作

exportToClipboard

public void exportToClipboard(JComponent comp,
                              Clipboard clip,
                              int action)
                       throws IllegalStateException

導致從給定元件到給定剪貼板的傳輸。可以由在元件的操作映射中註冊的預設剪切和複製操作調用該方法。

該傳輸將使用 java.awt.datatransfer 機制進行，無需開發人員投入更大精力。任何資料傳輸都將 在此 exportDone 方法返回之前完成，並使用發生的操作調用該方法。如果嘗試在其上放置資料時剪貼板不可用，則由 Clipboard.setContents(Transferable, ClipboardOwner) 拋出的 IllegalStateException 將通過此方法傳播。但是，出於一致性考慮，首先要使用 NONE 操作調用 exportDone。

參數：

comp - 存儲要傳輸的資料的元件；提供此參數以啟用 TransferHandler 的共享

clip - 要向其傳輸資料的剪貼板

action - 請求的傳輸動作；這應該是 COPY 或 MOVE 二者的其中一個值；執行的操作是由 getSourceActions 和請求的操作給定的傳輸功能的交集；如果不支持請求的操作，則該交集可能會導致 NONE 操作

拋出：

IllegalStateException - 如果該剪貼板當前不可用

另請參見：

Clipboard.setContents(Transferable, ClipboardOwner)

importData

public boolean importData(TransferHandler.TransferSupport support)

導致從剪貼板或拖放操作的傳輸。要導入的 Transferable 和要傳輸到的元件包含在 TransferSupport 中。

拖放實作在調用此方法前調用 canImport 確定是否適合傳輸，但粘貼的實作不會這樣做。因此，調用此方法進行粘貼時不能假定傳輸一定是可接受的。這種情況下，建議顯式調用 canImport。

註：傳遞給此方法的 TransferSupport 物件只在該方法的調用期間才有效。此方法返回後它可以包含的值是不確定的。

參數：

support - 套件含該傳輸細節的物件，不為 null。

返回：

如果資料被插入該元件，則返回 true；否則返回 false

拋出：

NullPointerException - 如果 support 為 null

從以下版本開始：

1.6

另請參見：

canImport(TransferHandler.TransferSupport)

importData

public boolean importData(JComponent comp,
                          Transferable t)

導致從剪貼板或 DND 放置操作向元件的傳輸。Transferable 表示要導入元件的資料。

註：Swing 現在調用新的 importData，它帶有 TransferSupport，而 TransferSupport 調用此方法（如果 TransferSupport 中的元件是 JComponent）。鼓勵開發人員調用並覆寫新的版本，因為它提供了更多資訊（它也是唯一支持與直接在 JFrame 或其他非 JComponent 上設置的 TransferHandler 一起使用的版本）。

參數：

comp - 要接收傳輸的元件；提供此參數以啟用 TransferHandler 的共享

t - 要導入的資料

返回：

如果該資料已插入到元件，則返回 true，否則返回 false

另請參見：

importData(TransferHandler.TransferSupport)

canImport

public boolean canImport(TransferHandler.TransferSupport support)

在拖放操作期間重複調用此方法，以允許開發人員配置傳輸的可接受性屬性，並返回傳輸的可接受性；返回 true 值指示給定 TransferSupport（它包含該傳輸的所有細節）所表示的傳輸在當前是可以接受的，false 值指示拒絕該傳輸。

對於在拖放期間自動顯示放置位置的那些元件（接受傳輸），預設情況下，告知它們顯示放置位置。這可通過在 TransferSupport 上調用 setShowDropLocation 更改。

預設情況下，當接受傳輸時，選擇的放置動作是使用者通過其拖動動作挑出的動作。通過在 TransferSupport 上調用 setDropAction，開發人員可以覆寫此方法並從受支持的源動作中選擇一個不同的動作。

每次調用 canImport 時，TransferSupport 都包含新狀態。因此，每次調用時都必須設置在其上設置的所有屬性。對於放置操作，調用 importData 之前最後再調用一次 canImport。最後一次調用期間在 TransferSupport 上設置的任何狀態在 importData 中都是可用的。

不會內部調用此方法來回應粘貼操作。因此，對於這種情況，建議 importData 的實作顯式調用此方法，並建議此方法還要準備好返回是否適合粘貼操作。

註：傳遞給此方法的 TransferSupport 物件只在該方法的調用期間才有效。此方法返回後可以包含的值是不確定的。

參數：

support - 套件含該傳輸的細節的物件，不為 null。

返回：

如果導入可能發生，則返回 true；否則返回 false

拋出：

NullPointerException - 如果 support 為 null

從以下版本開始：

1.6

另請參見：

importData(TransferHandler.TransferSupport), TransferHandler.TransferSupport.setShowDropLocation(boolean), TransferHandler.TransferSupport.setDropAction(int)

canImport

public boolean canImport(JComponent comp,
                         DataFlavor[] transferFlavors)

指示一個元件在實際嘗試導入給定資料 flavor 的集合之前是否接受其導入。

註：Swing 現在調用新的 importData，它帶有 TransferSupport，而 TransferSupport 調用此方法（當且僅當 TransferSupport 中的元件是 JComponent 時）。鼓勵開發人員調用並覆寫新的版本，因為它提供了更多資訊（它也是唯一支持與直接在 JFrame 或其他非 JComponent 上設置的 TransferHandler 一起使用的版本）。

參數：

comp - 要接收傳輸的元件；提供此參數以啟用 TransferHandlers 的共享

transferFlavors - 可用的資料格式

返回：

如果可以將該資料插入到元件，則返回 true，否則返回 false

另請參見：

canImport(TransferHandler.TransferSupport)

getSourceActions

public int getSourceActions(JComponent c)

返回源支持的傳輸動作的型別；COPY、MOVE 和 LINK 的任意按位或組合。

有些模型是不可變的，因此 MOVE 的傳輸動作不應該在這種情況下公開。返回 NONE 禁用該元件的傳輸。

參數：

c - 存儲要傳輸的資料的元件；提供此參數以啟用 TransferHandler 的共享

返回：

如果可以找到該傳輸屬性，則返回 COPY；否則返回 NONE

getVisualRepresentation

public Icon getVisualRepresentation(Transferable t)

返回一個建立傳輸外觀的物件。此方法適用於在執行拖動操作時提供反饋和在具有可視化外觀的剪貼板實作中表示傳輸。該 Icon 介面的實作不應更改圖形剪貼或 alpha 級別。該圖標實作不必是矩形，也不必繪製所有邊界矩形，並且調用該圖標繪製方法的邏輯不應假定繪製了所有位。null 是此方法的一個有效返回值，指示沒有提供任何可視化表示形式。在這種情況下，該調用邏輯完全可以隨意表示該 transferable。

如果返回值為 null，則該預設 Swing 邏輯將不執行 alpha 混合拖動動畫。

參數：

t - 要傳輸的資料；此值希望已由 createTransferable 方法創建

返回：

null，指示沒有任何預設可視化表示形式

createTransferable

protected Transferable createTransferable(JComponent c)

創建一個要用作資料傳輸源的 Transferable。返回要傳輸的資料表示形式，或者返回 null 如果元件的屬性為 null

參數：

c - 存儲要傳輸的資料的元件；提供此參數以啟用 TransferHandler 的共享

返回：

要傳輸的資料表示形式，或返回 null 如果與 c 相關的屬性為 null

exportDone

protected void exportDone(JComponent source,
                          Transferable data,
                          int action)

在導出資料之後調用。如果該操作為 MOVE，則此方法應該移除已傳輸的資料。

因為 MOVE 不是此實作支持的操作，所以實作此方法不執行任何操作（getSourceActions 不包括 MOVE）。

參數：

source - 以前作為資料源的元件

data - 已傳輸的資料，如果該操作為 NONE，則可能為 null。

action - 已執行的實際操作