Win32 API 日本語リファレンス
ホーム › System.Ole › IDropTarget

IDropTarget

COM
📘 Microsoft Learn (日本語) · English
IID00000122-0000-0000-c000-000000000046継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IDropTarget インターフェイスは、アプリケーションでドラッグ アンド ドロップ操作を提供するために実装するインターフェイスの 1 つです。

メソッド 4

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT DragEnter(IDataObject* pDataObj, MODIFIERKEYS_FLAGS grfKeyState, POINTL pt, DROPEFFECT* pdwEffect)

ドロップを受け入れられるかどうか、および受け入れられる場合はドロップの効果を示します。

pDataObjIDataObject*inデータ オブジェクトの IDataObject インターフェイスへのポインターです。このデータ オブジェクトには、ドラッグ アンド ドロップ操作で転送されるデータが含まれます。ドロップが発生すると、このデータ オブジェクトはターゲットに取り込まれます。
grfKeyStateMODIFIERKEYS_FLAGSinキーボードの修飾キーの現在の状態です。指定できる値は、MK_CONTROL、MK_SHIFT、MK_ALT、MK_BUTTON、MK_LBUTTON、MK_MBUTTON、MK_RBUTTON の各フラグの組み合わせです。
ptPOINTLin現在のカーソル座標をスクリーン座標で格納する POINTL 構造体です。
pdwEffectDROPEFFECT*inout入力時は、DoDragDrop 関数の pdwEffect パラメーターの値へのポインターです。戻り時には、ドロップ操作の結果を示す DROPEFFECT フラグのいずれかを格納する必要があります。

戻り値

このメソッドは成功時に S_OK を返します。その他の値には次のものがあります。

戻り値 説明
E_UNEXPECTED
 予期しないエラーが発生しました。
E_INVALIDARG
 入力時に pdwEffect パラメーターが NULL です。
E_OUTOFMEMORY
 この操作に使用できるメモリが不足していました。

解説(Remarks)

DragEnter を直接呼び出すことはありません。代わりに、DoDragDrop 関数が、ユーザーが最初にドロップ ターゲットの登録済みウィンドウ内へマウスをドラッグしたときに、ドロップの効果を判断するためにこのメソッドを呼び出します。

DragEnter を実装するには、次の 3 つの点を確認して、ターゲットがソース データ オブジェクト内のデータを使用できるかどうかを判断する必要があります。

形式とメディアを確認するには、pDataObject パラメーターで渡された IDataObject ポインターを使用して IDataObject::EnumFormatEtc を呼び出し、ソース データ オブジェクトがサポートする FORMATETC 構造体を列挙します。次に IDataObject::QueryGetData を呼び出し、データ オブジェクトに指定された形式とメディアを調べて、データ オブジェクトがターゲット上でデータをレンダリングできるかどうかを判断します。

IDropTarget::DragEnter への入力時には、pdwEffect パラメーターに DoDragDrop 関数の pdwOkEffect パラメーターに指定された効果が設定されています。IDropTarget::DragEnter メソッドは、これらの効果のいずれかを選択するか、ドロップを無効にする必要があります。

次の修飾キーはドロップの結果に影響します。

キーの組み合わせ ユーザーに表示されるフィードバック ドロップ効果
CTRL + SHIFT = DROPEFFECT_LINK
CTRL + DROPEFFECT_COPY
キーなし、または SHIFT なし DROPEFFECT_MOVE

戻り時には、このメソッドは効果、すなわち DROPEFFECT フラグのいずれかを pdwEffect パラメーターに書き込む必要があります。DoDragDrop はこのパラメーターを受け取り、自身の pdwEffect パラメーターに書き込みます。ドロップの効果は、pdwEffect パラメーターを通じて DoDragDrop からソースに伝達されます。その後、DoDragDrop 関数は IDropSource::GiveFeedback を呼び出し、ソース アプリケーションがターゲット ウィンドウを通じて適切な視覚的フィードバックをユーザーに表示できるようにします。

vtbl 4 HRESULT DragOver(MODIFIERKEYS_FLAGS grfKeyState, POINTL pt, DROPEFFECT* pdwEffect)

ユーザーにターゲットのフィードバックを提供し、DoDragDrop 関数にドロップの効果を伝えることで、DoDragDrop 関数がドロップの効果をソースに伝達できるようにします。

grfKeyStateMODIFIERKEYS_FLAGSinキーボードの修飾キーの現在の状態です。有効な値は、MK_CONTROL、MK_SHIFT、MK_ALT、MK_BUTTON、MK_LBUTTON、MK_MBUTTON、MK_RBUTTON の各フラグの組み合わせです。
ptPOINTLin現在のカーソル座標をスクリーン座標で格納する POINTL 構造体です。
pdwEffectDROPEFFECT*inout入力時は、DoDragDrop 関数の pdwEffect パラメーターの値へのポインターです。戻り時には、ドロップ操作の結果を示す DROPEFFECT フラグのいずれかを格納する必要があります。

戻り値

このメソッドは成功時に S_OK を返します。その他の値には次のものがあります。

戻り値 説明
E_UNEXPECTED
 予期しないエラーが発生しました。
E_INVALIDARG
 pdwEffect の値が無効です。
E_OUTOFMEMORY
 この操作に使用できるメモリが不足していました。

解説(Remarks)

DragOver を直接呼び出すことはありません。DoDragDrop 関数は、ユーザーが特定のターゲット ウィンドウ上でマウスを移動するたびにこのメソッドを呼び出します。DoDragDrop は、ドラッグ アンド ドロップ操作がキャンセルされた場合、ユーザーがターゲット ウィンドウの外へマウスをドラッグした場合、またはドロップが完了した場合にループを終了します。

IDropTarget::DragOver の実装では、IDropTarget::DragEnter と同様の機能を提供する必要があります。データ オブジェクトの形式とメディアを定義する FORMATETC と、修飾キーの状態を調べて、データをターゲットにドロップする効果を判断する必要があります。マウスの位置もドロップの効果の判断に関与する場合があります。次の修飾キーはドロップの結果に影響します。

キーの組み合わせ ユーザーに表示されるフィードバック ドロップ効果
CTRL + SHIFT = DROPEFFECT_LINK
CTRL + DROPEFFECT_COPY
キーなし、または SHIFT なし DROPEFFECT_MOVE

ドロップの効果は、pdwEffect を通じて DoDragDrop からソースに伝達されます。その後、DoDragDrop 関数は IDropSource::GiveFeedback を呼び出し、ソース アプリケーションが適切な視覚的フィードバックをユーザーに表示できるようにします。

IDropTarget::DragOver への入力時には、pdwEffect パラメーターに DoDragDrop 関数の pdwOkEffect パラメーターに渡された許可される効果が設定されている必要があります。IDropTarget::DragOver メソッドは、これらの効果のいずれかを選択するか、ドロップを無効にできる必要があります。

戻り時には、pdwEffect に DROPEFFECT フラグのいずれかが設定されます。この値はその後 DoDragDrop の pdwEffect パラメーターに渡されます。妥当な値は、ドラッグされたデータをターゲットにコピーする DROPEFFECT_COPY、ソース データへのリンクを作成する DROPEFFECT_LINK、またはドラッグされたデータをソース アプリケーションからターゲットへ完全に移動できるようにする DROPEFFECT_MOVE です。

ターゲット ウィンドウに適切な視覚的フィードバックを提供することも望ましいでしょう。前回の IDropTarget::DragOver の呼び出し、または最初の IDropTarget::DragEnter から、すでに何らかのターゲット フィードバックが表示されている場合があります。このフィードバックがもはや適切でない場合は、削除する必要があります。

効率上の理由から、データ オブジェクトは IDropTarget::DragOver に渡されません。直前の IDropTarget::DragEnter の呼び出しで渡されたデータ オブジェクトが利用可能であり、それを使用できます。

IDropTarget::DragOver が処理を完了すると、DoDragDrop 関数は IDropSource::GiveFeedback を呼び出し、ソース アプリケーションが適切な視覚的フィードバックをユーザーに表示できるようにします。

実装者への注意

この関数は DoDragDrop ループ中に頻繁に呼び出されるため、DragOver メソッドの実装は可能な限り最適化することが理にかなっています。
vtbl 5 HRESULT DragLeave()

ターゲットのフィードバックを削除し、データ オブジェクトを解放します。

戻り値

このメソッドは成功時に S_OK を返します。その他の値には次のものがあります。

戻り値 説明
E_OUTOFMEMORY
 この操作に使用できるメモリが不足しています。

解説(Remarks)

このメソッドを直接呼び出すことはありません。DoDragDrop 関数は、次のいずれかの場合にこのメソッドを呼び出します。

IDropTarget::DragLeave を実装するには、現在表示されているターゲット フィードバックをすべて削除する必要があります。また、データ転送オブジェクトに対して保持しているすべての参照を解放する必要もあります。
vtbl 6 HRESULT Drop(IDataObject* pDataObj, MODIFIERKEYS_FLAGS grfKeyState, POINTL pt, DROPEFFECT* pdwEffect)

ソース データをターゲット ウィンドウに取り込み、ターゲットのフィードバックを削除し、データ オブジェクトを解放します。

pDataObjIDataObject*inドラッグ アンド ドロップ操作で転送されるデータ オブジェクトの IDataObject インターフェイスへのポインターです。
grfKeyStateMODIFIERKEYS_FLAGSinキーボードの修飾キーの現在の状態です。指定できる値は、MK_CONTROL、MK_SHIFT、MK_ALT、MK_BUTTON、MK_LBUTTON、MK_MBUTTON、MK_RBUTTON の各フラグの組み合わせです。
ptPOINTLin現在のカーソル座標をスクリーン座標で格納する POINTL 構造体です。
pdwEffectDROPEFFECT*inout入力時は、DoDragDrop 関数の pdwEffect パラメーターの値へのポインターです。戻り時には、ドロップ操作の結果を示す DROPEFFECT フラグのいずれかを格納する必要があります。

戻り値

このメソッドは成功時に S_OK を返します。その他の値には次のものがあります。

戻り値 説明
DRAGDROP_S_CANCEL
 OLE ドラッグ アンド ドロップ操作がキャンセルされました。
E_UNEXPECTED
 予期しないエラーが発生しました。
E_INVALIDARG
 pdwEffect パラメーターが無効です。
E_OUTOFMEMORY
 この操作に使用できるメモリが不足しています。

解説(Remarks)

このメソッドを直接呼び出すことはありません。DoDragDrop 関数は、ユーザーがドラッグ アンド ドロップ操作を完了したときにこのメソッドを呼び出します。

Drop を実装するには、データ オブジェクトをターゲットに取り込む必要があります。pDataObj を通じて利用できる IDataObject で利用可能な形式と、修飾キーの現在の状態を使用して、リンクや埋め込みなど、データをどのように取り込むかを判断します。

データの取り込みに加えて、IDropTarget::DragLeave メソッドと同様に、クリーンアップも行う必要があります。

また、この操作の効果を DoDragDrop を通じてソース アプリケーションに返すことで、ドラッグ アンド ドロップ操作の完了後にソース アプリケーションがクリーンアップできるようにします。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IDropTarget "{00000122-0000-0000-C000-000000000046}"
#usecom global IDropTarget IID_IDropTarget "{}"
#comfunc global IDropTarget_DragEnter  3 sptr,int,int,var
#comfunc global IDropTarget_DragOver   4 int,int,var
#comfunc global IDropTarget_DragLeave  5
#comfunc global IDropTarget_Drop       6 sptr,int,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。