ホーム › System.Ole › IPointerInactive

IPointerInactive

COM

📘 Microsoft Learn (日本語) · English

IID55980ba0-35aa-11cf-b671-00aa004cd6d8継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

オブジェクトがほとんどの時間は非アクティブなまま維持されつつ、ドラッグアンドドロップを含むマウスとの対話に参加できるようにします。

メソッド 3

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

vtbl 3 HRESULT GetActivationPolicy(POINTERINACTIVE* pdwPolicy)

オブジェクトの現在のアクティブ化ポリシーを取得します。このメソッドは、非アクティブなオブジェクトがマウスポインターの下にある状態で WM_SETCURSOR または WM_MOUSEMOVE メッセージを受信したときに、コンテナーによって呼び出されます。

pdwPolicy

POINTERINACTIVE*

out

アクティブ化ポリシーを受け取る変数へのポインター。設定される値は POINTERINACTIVE 列挙体に由来します。

戻り値

メソッドが成功した場合、戻り値は S_OK です。それ以外の場合は E_FAIL です。

解説(Remarks)

オブジェクトは、POINTERINACTIVE_ACTIVATEONENTRY 値によって、マウスが入るとすぐにインプレースでアクティブ化されるよう要求できます。単にマウスポインターを設定するだけでなく、より豊富な視覚的フィードバックを提供するオブジェクトはこの値を使用します。たとえば、オブジェクトが特別な視覚的フィードバックをサポートする場合、そのフィードバックを描画するためにアクティブ状態に移行する必要があります。

オブジェクトは、POINTERINACTIVE_ACTIVATEONDRAG によって、ドラッグアンドドロップ操作中にマウスがオブジェクト上をドラッグされたときにアクティブ化を要求するためにも、このメソッドを使用できます。

オブジェクトがこれらの値のいずれかを返した場合、コンテナーはただちにオブジェクトをアクティブ化し、その呼び出しを引き起こしたウィンドウメッセージを転送する必要があります。その後、オブジェクトはアクティブなまま維持され、コンテナーが次の WM_SETCURSOR または WM_MOUSEMOVE を受け取るまで、以降のメッセージを自身のウィンドウで処理します。その時点で、コンテナーはオブジェクトを非アクティブ化する必要があります。

ウィンドウレスの OLE オブジェクトの場合、このメカニズムはわずかに異なります。ウィンドウレスオブジェクトのドラッグアンドドロップ操作の詳細については、IOleInPlaceSiteWindowless を参照してください。

オブジェクトが POINTERINACTIVE_ACTIVATEONENTRY 値と POINTERINACTIVE_DEACTIVATEONLEAVE 値の両方を返した場合、オブジェクトはマウスがオブジェクト上にある間のみアクティブ化されます。POINTERINACTIVE_ACTIVATEONENTRY 値のみが設定されている場合、オブジェクトはマウスが最初に入ったときに一度アクティブ化され、その後もアクティブなまま維持されます。

呼び出し元への注意事項

アクティブ化ポリシーはキャッシュしないでください。コンテナーは、非アクティブなオブジェクトにマウスが入るたびにこのメソッドを呼び出す必要があります。

vtbl 4 HRESULT OnInactiveMouseMove(RECT* pRectBounds, INT x, INT y, DWORD grfKeyState)

マウスポインターがオブジェクト上に移動したことをオブジェクトに通知し、オブジェクトがマウスイベントを発生させられるようにします。このメソッドは、非アクティブなオブジェクトがマウスポインターの下にある状態で WM_MOUSEMOVE メッセージを受信したときに、コンテナーによって呼び出されます。

pRectBounds	RECT*	in	含んでいるウィンドウのクライアント座標で表した、オブジェクトの境界矩形。このパラメーターは、WM_MOUSEMOVE メッセージを受信したときの画面上のオブジェクトの正確な位置とサイズをオブジェクトに伝えます。この値はクライアントの座標系の単位で指定されます。
x	INT	in	クライアントの含んでいるウィンドウの単位で表した、マウス位置の水平座標。
y	INT	in	クライアントの含んでいるウィンドウの単位で表した、マウス位置の垂直座標。
grfKeyState	DWORD	in	キーボードの修飾キーの現在の状態。設定される値は、MK_CONTROL、MK_SHIFT、MK_ALT、MK_BUTTON、MK_LBUTTON、MK_MBUTTON、MK_RBUTTON の各値の任意の組み合わせです。

戻り値

メソッドが成功した場合、戻り値は S_OK です。それ以外の場合は E_FAIL です。

解説(Remarks)

コンテナーは、IPointerInactive::GetActivationPolicy メソッドを呼び出してオブジェクトのアクティブ化ポリシーを確認した後、マウスポインターがオブジェクト上にあることを通知するためにこのメソッドを呼び出します。オブジェクトがその呼び出しを通じてインプレースでのアクティブ化を要求していない場合、コンテナーは、マウスポインターがオブジェクト上にとどまっている間、OnInactiveMouseMove を呼び出すことで以降の WM_MOUSEMOVE メッセージを非アクティブなオブジェクトにディスパッチします。オブジェクトはこれによりマウス移動イベントを発生させることができます。

丸め誤差を回避し、オブジェクト実装者の作業を容易にするため、このメソッドは通常の HIMETRIC 単位ではなく、含んでいるクライアントウィンドウ、つまりオブジェクトが表示されているウィンドウの単位でウィンドウ座標を受け取ります。これにより、オブジェクトがアクティブなときと非アクティブなときとで同じ座標とコードパスを使用できます。ウィンドウ座標はマウス位置を指定します。境界矩形も同じ座標系で指定されます。

vtbl 5 HRESULT OnInactiveSetCursor(RECT* pRectBounds, INT x, INT y, DWORD dwMouseMsg, BOOL fSetAlways)

非アクティブなオブジェクトのマウスポインターを設定します。このメソッドは、非アクティブなオブジェクトがマウスポインターの下にある状態で WM_SETCURSOR メッセージを受信したときに、コンテナーによって呼び出されます。

pRectBounds	RECT*	in	含んでいるウィンドウのクライアント座標単位で指定された、オブジェクトの境界矩形。このパラメーターは、WM_SETCURSOR メッセージを受信したときの画面上のオブジェクトの正確な位置とサイズをオブジェクトに伝えます。この値はクライアントの座標系の単位で指定されます。
x	INT	in	クライアントの含んでいるウィンドウの単位で表した、マウス位置の水平座標。
y	INT	in	クライアントの含んでいるウィンドウの単位で表した、マウス位置の垂直座標。
dwMouseMsg	DWORD	in	WM_SETCURSOR が発生する原因となったマウスメッセージの識別子。
fSetAlways	BOOL	in	この値が TRUE の場合、オブジェクトはカーソルを設定しなければなりません。この値が FALSE の場合、オブジェクトはカーソルを設定する義務はなく、その場合は S_FALSE を返す必要があります。

戻り値

このメソッドは、標準の戻り値 E_FAIL のほか、次の値を返すことがあります。

戻り値	説明
S_OK	マウスポインターが正常に設定されました。
S_FALSE	オブジェクトはカーソルを設定しませんでした。コンテナーは、カーソルを自身で設定するか、または fSetAlways パラメーターを TRUE に設定してオブジェクトを再度呼び出す必要があります。

解説(Remarks)

コンテナーは、IPointerInactive::GetActivationPolicy メソッドを呼び出してオブジェクトのアクティブ化ポリシーを確認した後、非アクティブなオブジェクト上のマウスポインターを設定するためにこのメソッドを呼び出します。オブジェクトがその呼び出しを通じてインプレースでのアクティブ化を要求していない場合、コンテナーは、マウスポインターがオブジェクト上にとどまっている間、OnInactiveSetCursor を呼び出すことで以降の WM_SETCURSOR メッセージを非アクティブなオブジェクトにディスパッチします。

OnInactiveSetCursor は、オブジェクトがカーソルを設定する義務があるかどうかを示す追加のパラメーター fSetAlways を受け取ります。コンテナーは、まずこのパラメーターを FALSE にしてこのメソッドを呼び出す必要があります。オブジェクトは、カーソルを設定しなかったことを示すために S_FALSE を返すことができます。その場合、コンテナーは、カーソルを自身で設定するか、またはそれを望まない場合は fSetAlways を TRUE にして OnInactiveSetCursor メソッドを再度呼び出す必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPointerInactive "{55980BA0-35AA-11CF-B671-00AA004CD6D8}"
#usecom global IPointerInactive IID_IPointerInactive "{}"
#comfunc global IPointerInactive_GetActivationPolicy  3 var
#comfunc global IPointerInactive_OnInactiveMouseMove  4 var,int,int,int
#comfunc global IPointerInactive_OnInactiveSetCursor  5 var,int,int,int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IPointerInactive "{55980BA0-35AA-11CF-B671-00AA004CD6D8}"
#usecom global IPointerInactive IID_IPointerInactive "{}"
#comfunc global IPointerInactive_GetActivationPolicy  3 sptr
#comfunc global IPointerInactive_OnInactiveMouseMove  4 sptr,int,int,int
#comfunc global IPointerInactive_OnInactiveSetCursor  5 sptr,int,int,int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。