javax.swing

クラスTransferHandler

java.lang.Object

javax.swing.TransferHandler

すべての実装されたインタフェース:

Serializable

public class TransferHandler
extends Object
implements Serializable

このクラスは、Swingコンポーネントに対するTransferableの転送処理に使用します。Transferableは、カット、コピー、ペーストなどを通じてクリップボードに送るデータまたはクリップボードから受け取るデータを表すために使用します。また、ドラッグ&ドロップ操作で、コンポーネントからのドラッグおよびコンポーネントへのドロップを表すために使用します。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 ドロップされたデータを挿入する位置を表します。
static class	TransferHandler.TransferSupport このクラスには、クリップボードによる転送またはドラッグ&ドロップによる転送に関連する詳細情報をすべてカプセル化する機能と、ドラッグ&ドロップ操作をカスタマイズする機能があります。

フィールドのサマリー

フィールド

修飾子と型	フィールドと説明
static int	COPY 「copy」の転送アクションを表すintです。
static int	COPY_OR_MOVE 「copy」または「move」のソース・アクション機能を表すintです。
static int	LINK 「link」の転送アクションを表すintです。
static int	MOVE 「move」の転送アクションを表すintです。
static int	NONE 転送アクションがないことを表すintです。

コンストラクタのサマリー

コンストラクタ

修飾子	コンストラクタと説明
protected	TransferHandler() サブクラスに便利なコンストラクタです。
	TransferHandler(String property) クリップボードまたはドラッグ&ドロップ操作によってコンポーネント間のJava Beanプロパティを転送できる転送ハンドラを構築します。

メソッドのサマリー

修飾子と型	メソッドと説明
boolean	canImport(JComponent comp, DataFlavor[] transferFlavors) コンポーネントが実際に一連のデータ・フレーバのインポートを試みる前に、データ・フレーバのインポートを受け入れるかどうかを示します。
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を返します。
Image	getDragImage() ドラッグ・イメージを返します。
Point	getDragImageOffset() ドラッグするイメージのアンカー・オフセットを返します。
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) クリップボードまたはドラッグ&ドロップ操作から転送します。
void	setDragImage(Image img) ドラッグ・イメージ・パラメータを設定します。
void	setDragImageOffset(Point p) ドラッグするイメージのアンカー・オフセットを設定します。

クラス 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

「copy」の転送アクションを表すintです。データがクリップボードにコピーされたとき、またはドラッグ&ドロップ操作で別の場所へコピーされたときに使用されます。

関連項目:

定数フィールド値

MOVE

public static final int MOVE

「move」の転送アクションを表すintです。データがクリップボードに移動(カット)されたとき、またはドラッグ&ドロップ操作で別の場所へ移動されたときに使用されます。

関連項目:

定数フィールド値

COPY_OR_MOVE

public static final int COPY_OR_MOVE

「copy」または「move」のソース・アクション機能を表すintです。

関連項目:

定数フィールド値

LINK

public static final int LINK

「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

setDragImage

public void setDragImage(Image img)

ドラッグ・イメージ・パラメータを設定します。呼び出しまでに描画するイメージを準備する必要があります。パフォーマンス上の理由から、イメージは参照によって格納されます。

パラメータ:

img - ドラッグするイメージ

getDragImage

public Image getDragImage()

ドラッグ・イメージを返します。ドラッグするイメージが存在しない場合、戻り値はnullです。

戻り値:

ドラッグ・イメージへの参照

setDragImageOffset

public void setDragImageOffset(Point p)

ドラッグするイメージのアンカー・オフセットを設定します。nullであってはならない。

パラメータ:

p - イメージの左上隅を基準にしたイメージのアンカー・オフセットの座標に対応するPointオブジェクト

getDragImageOffset

public Point getDragImageOffset()

ドラッグするイメージのアンカー・オフセットを返します。

戻り値:

イメージの左上隅を基準にしたイメージのアンカー・オフセットの座標に対応するPointオブジェクト。デフォルトではポイント(0,0)が返されます。

exportAsDrag

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

Swingドラッグ・サポートを開始します。コンポーネントでdragEnabledプロパティが設定されている場合、javax.swing.plaf.basicパッケージのさまざまなUIの実装から、このメソッドが呼び出されます。UIのカスタム実装から呼び出して、Swingドラッグ・サポートを使用できます。また、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がこのメソッドを介して伝播されます。ただし、一貫性を保つためにexportDoneはまずNONEというアクションで呼び出されます。

パラメータ:

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は、TransferSupportを実行する新しいバージョンのimportDataを呼び出し、次にそれがこのメソッドを呼び出します(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が1回だけ呼び出されます。この最後の呼出し中に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)

コンポーネントが実際に一連のデータ・フレーバのインポートを試みる前に、データ・フレーバのインポートを受け入れるかどうかを示します。

注: Swingは、TransferSupportを実行する新しいバージョンのcanImportを呼び出し、次にそれがこのメソッドを呼び出します(TransferSupport内のコンポーネントがJComponentの場合のみ)。新しいバージョンは、より多くの情報を提供します。また、JFrameやその他のJComponent以外のコンポーネントにTransferHandlerを直接設定して使用できる唯一のバージョンでもあります。このため、開発者には、新しいバージョンを呼び出し、オーバーライドすることを奨励します。

パラメータ:

comp - 転送を受け取るコンポーネント。TransferHandlerの共有を可能にするために提供される

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インタフェースの実装では、グラフィック・クリップまたはアルファ・レベルを変更しないでください。アイコンの実装は矩形である必要はなく、境界の矩形をすべてペイントする必要もありません。また、アイコンのペイント・メソッドを呼び出すロジックでは、すべてのビットがペイントされていることを想定してはいけません。このメソッドの戻り値としてはnullも許され、ビジュアル表現が設定されていないことを示します。その場合、呼出しロジックではTransferableを自由に表すことができます。

nullが返された場合、デフォルトのSwingロジックではアルファ合成されたドラッグ・アニメーションは実行されません。

パラメータ:

t - 転送されるデータ。createTransferableメソッドによって作成されたものと想定される

戻り値:

デフォルトのビジュアル表現がないことを示すnull

createTransferable

protected Transferable createTransferable(JComponent c)

データ転送のソースとして使用するTransferableを作成します。転送するデータの表現を返します。コンポーネントのプロパティがnullの場合はnullを返します

パラメータ:

c - 転送されるデータを保持するコンポーネント。TransferHandlerの共有を可能にするために提供される

戻り値:

転送するデータの表現。cに関連付けられたプロパティがnullの場合はnull

exportDone

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

データのエクスポート後に呼び出されます。このメソッドは、アクションがMOVEの場合に転送されたデータを削除します。

MOVEはこの実装にサポートされるアクションでないため、このメソッドの実装では何も行われません。getSourceActionsにはMOVEが含まれません。

パラメータ:

source - データのソースであったコンポーネント

data - 転送されたデータ。アクションがNONEである場合はnull。

action - 実際に実行されたアクション