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 - 実際に実行されたアクション