ホーム › System.Ole › IOleInPlaceSite

IOleInPlaceSite

COM

📘 Microsoft Learn (日本語) · English

IID00000119-0000-0000-c000-000000000046継承元IOleWindow自前メソッド開始 vtbl5

公式ドキュメント

コンテナーとオブジェクトのインプレースクライアントサイトとの間の対話を管理します。クライアントサイトとは、埋め込みオブジェクトの表示先であり、オブジェクトに関する位置情報および概念的な情報を提供するものであることを思い出してください。

メソッド 10

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

vtbl 5 HRESULT CanInPlaceActivate()

コンテナーがオブジェクトをインプレースでアクティブ化できるかどうかを判定します。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
S_FALSE	コンテナーはこのオブジェクトのインプレースアクティブ化を許可しません。
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

DVASPECT_CONTENT として表示されているオブジェクトのみがインプレースでアクティブ化できます。

呼び出し元への注意事項

CanInPlaceActivate は、クライアントサイトの直接の子オブジェクトがインプレースでアクティブ化する必要があるときに呼び出されます。この関数により、コンテナーアプリケーションはアクティブ化要求を受け入れるか拒否するかを選択できます。

vtbl 6 HRESULT OnInPlaceActivate()

コンテナーに対して、そのオブジェクトの1つがインプレースでアクティブ化されようとしていることを通知します。

戻り値

このメソッドは、コンテナーがインプレースアクティブ化を許可する場合に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

呼び出し元への注意事項

OnInPlaceActivate は、アクティブな埋め込みオブジェクトが初めてインプレースでアクティブ化されるときに呼び出されます。コンテナーは、オブジェクトがアクティブになりつつあることを記録しておく必要があります。

実装者への注意事項

埋め込みオブジェクトへのリンクをサポートするコンテナーは、インプレースオブジェクトが UI 非アクティブかつ非表示状態で実行されているときに、その実行状態を適切に管理する必要があります。インプレースオブジェクトを迅速に再アクティブ化するために、コンテナーは IOleInPlaceSite::DeactivateAndUndo メソッドが呼び出されるまで IOleObject::Close を呼び出すべきではありません。リンクを行うクライアントがサイレントに更新した場合にオブジェクトが不安定な状態のまま残されるのを防ぐため、コンテナーは OleLockRunning を呼び出してオブジェクトを実行状態にロックする必要があります。これにより、非表示のインプレースオブジェクトが、コンテナー内に保存される前にシャットダウンされるのを防ぎます。

vtbl 7 HRESULT OnUIActivate()

コンテナーに対して、オブジェクトがまさにインプレースでアクティブ化されようとしており、コンテナーのメインメニューをインプレース複合メニューに置き換えようとしていることを通知します。

戻り値

このメソッドは、コンテナーがインプレースアクティブ化を許可する場合に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

呼び出し元への注意事項

インプレースオブジェクトは、ユーザーインターフェイスをアクティブ化する直前に IOleInPlaceSite::OnUIActivate を呼び出します。

実装者への注意事項

コンテナーは、自身のアクティブ化に関連するユーザーインターフェイスをすべて削除する必要があります。コンテナー自体が埋め込みオブジェクトである場合は、ドキュメントレベルのユーザーインターフェイスを削除する必要があります。

同じドキュメント内にすでにインプレースでアクティブなオブジェクトが存在する場合、コンテナーは OnUIDeactivate を呼び出す前に IOleInPlaceObject::UIDeactivate を呼び出す必要があります。

vtbl 8 HRESULT GetWindowContext(IOleInPlaceFrame** ppFrame, IOleInPlaceUIWindow** ppDoc, RECT* lprcPosRect, RECT* lprcClipRect, OLEINPLACEFRAMEINFO* lpFrameInfo)

インプレースオブジェクトが、ウィンドウオブジェクト階層を構成するウィンドウインターフェイスと、オブジェクトのインプレースアクティブ化ウィンドウを配置すべき親ウィンドウ内の位置を取得できるようにします。

ppFrame	IOleInPlaceFrame**	out	フレームへのインターフェイスポインターを受け取る IOleInPlaceFrame ポインター変数へのポインター。エラーが発生した場合、実装は ppFrame を NULL に設定する必要があります。
ppDoc	IOleInPlaceUIWindow**	out	ドキュメントウィンドウへのインターフェイスポインターを受け取る IOleInPlaceUIWindow ポインター変数へのポインター。ドキュメントウィンドウがフレームウィンドウと同一である場合、ppDoc は NULL に設定されます。この場合、オブジェクトは ppFrame またはボーダーネゴシエーションのみを使用できます。エラーが返された場合、実装は ppDoc を NULL に設定する必要があります。
lprcPosRect	RECT*	out	親ウィンドウのクライアント座標におけるインプレースオブジェクトの位置を格納する矩形を表す RECT 構造体へのポインター。エラーが返された場合、このパラメーターは NULL に設定する必要があります。
lprcClipRect	RECT*	out	インプレースオブジェクトの位置矩形(lprcPosRect)を包含する外側の矩形を表す RECT 構造体へのポインター。この矩形は、オブジェクトの親ウィンドウのクライアント領域を基準とします。エラーが返された場合、このパラメーターは NULL に設定する必要があります。
lpFrameInfo	OLEINPLACEFRAMEINFO*	inout	コンテナーが適切なデータを格納する OLEINPLACEFRAMEINFO 構造体へのポインター。エラーが返された場合、このパラメーターは NULL に設定する必要があります。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
E_INVALIDARG	指定されたポインターの1つ以上が無効です。
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

OLEINPLACEFRAMEINFO 構造体は、オブジェクトがインプレースでアクティブな間に、キーストロークアクセラレーターをコンテナーフレームにディスパッチするために OLE が必要とするデータを提供します。

オブジェクトはアクティブ化されると、コンテナーの GetWindowContext を呼び出します。コンテナーは、OLEINPLACEFRAMEINFO 構造体を通じて、自身のインプレースアクセラレーターテーブルのハンドルを返します。GetWindowContext を呼び出す前に、オブジェクトは lpFrameInfo が指す OLEINPLACEFRAMEINFO 構造体の cb メンバーを設定して、その構造体のサイズを提供する必要があります。

vtbl 9 HRESULT Scroll(SIZE scrollExtant)

コンテナーに対して、オブジェクトのビューを指定されたピクセル数だけスクロールするよう指示します。

scrollExtant

SIZE

X 方向および Y 方向にスクロールするピクセル数。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
E_INVALIDARG	指定されたポインターが無効です。
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

スクロールの結果として、オブジェクトの可視矩形が変化する場合があります。その場合、コンテナーは IOleInPlaceObject::SetObjectRects を呼び出して、新しいクリッピング矩形をオブジェクトに与える必要があります。lprcClipRect と lprcPosRect の矩形の交差部分が、新しい可視矩形となります。詳細については IOleInPlaceSite::GetWindowContext を参照してください。

呼び出し元への注意事項

アクティブなインプレースオブジェクトが、コンテナーにスクロールを要求するときに呼び出されます。

vtbl 10 HRESULT OnUIDeactivate(BOOL fUndoable)

コンテナーに対して、自身のユーザーインターフェイスを再インストールしてフォーカスを取得すべきこと、およびオブジェクトが元に戻せる(アンドゥ可能な)状態を持つかどうかを通知します。

fUndoable

BOOL

オブジェクトが変更を元に戻せるか(TRUE)、元に戻せないか(FALSE)を指定します。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

オブジェクトは、fUndoable フラグを通じて変更を元に戻せるかどうかを示します。オブジェクトが変更を元に戻せる場合、コンテナーは(ユーザーが「編集」「元に戻す」コマンドを実行することにより)IOleInPlaceObject::ReactivateAndUndo メソッドを呼び出して変更を元に戻すことができます。

呼び出し元への注意事項

IOleInPlaceSite::OnUIDeactivate は、サイトの直接の子オブジェクトが非アクティブ化される際に、コンテナーに対して自身のユーザーインターフェイスコンポーネントを再インストールしてフォーカスを取得すべきことを通知するために呼び出されます。コンテナーは、複合サブメニューを完全にクリーンアップおよび破棄する前に、IOleInPlaceSite::OnUIDeactivate の呼び出しが完了するのを待つ必要があります。

vtbl 11 HRESULT OnInPlaceDeactivate()

コンテナーに対して、オブジェクトがインプレースでアクティブではなくなったことを通知します。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

呼び出し元への注意事項

OnInPlaceDeactivate は、インプレースオブジェクトが完全に非アクティブ化されたときに呼び出されます。この関数は、オブジェクトが非アクティブ化されたことをコンテナーに通知し、コンテナーがオブジェクトの非アクティブ化に関連するコードを実行する機会を与えます。特に OnInPlaceDeactivate は、IOleInPlaceObject::InPlaceDeactivate が呼び出された結果として呼び出されます。OnInPlaceDeactivate の呼び出しは、オブジェクトがもはやアンドゥをサポートできないことを示します。

実装者への注意事項

コンテナーが IOleInPlaceObject および IOleInPlaceActiveObject インターフェイス実装へのポインターを保持している場合は、OnInPlaceDeactivate の呼び出し後にそれらを解放する必要があります。

vtbl 12 HRESULT DiscardUndoState()

コンテナーに対して、アンドゥ状態を破棄するよう指示します。コンテナーは IOleInPlaceObject::ReActivateAndUndo を呼び出すべきではありません。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

オブジェクトがインプレースでアクティブ化されており、そのオブジェクトに関連付けられたオブジェクトアプリケーションがアンドゥのレベルを1段階しか保持しない場合、アンドゥスタックに複数のエントリを持つ必要はありません。つまり、コンテナーによって保存されたアンドゥ状態を無効化するような変更がアクティブオブジェクトに加えられた後は、このアンドゥ状態をコンテナー内に保持する必要はありません。

呼び出し元への注意事項

DiscardUndoState は、アクティブオブジェクトが自身のアンドゥ状態を破棄するような何らかのアクションを実行する際に呼び出されます。インプレースオブジェクトは、コンテナーに対してオブジェクトの最後に保存したアンドゥ状態を破棄するよう通知するために、このメソッドを呼び出します。

vtbl 13 HRESULT DeactivateAndUndo()

オブジェクトを非アクティブ化し、インプレースセッションを終了して、コンテナーが保存したアンドゥ状態に戻します。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

呼び出し元への注意事項

オブジェクトをアクティブ化した直後にユーザーがアンドゥを実行したときに、アクティブオブジェクトによって呼び出されます。

実装者への注意事項

この呼び出しが完了すると、コンテナーは IOleInPlaceObject::UIDeactivate を呼び出して、オブジェクトのユーザーインターフェイスを削除し、自身をアクティブ化して、アンドゥを行う必要があります。

vtbl 14 HRESULT OnPosRectChange(RECT* lprcPosRect)

コンテナーに対して、オブジェクトのエクステント(範囲)が変化したことを通知します。

lprcPosRect

RECT*

親ウィンドウのクライアント座標におけるインプレースオブジェクトの位置を格納する RECT 構造体へのポインター。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
E_INVALIDARG	指定されたポインターが無効です。
E_UNEXPECTED	予期しないエラーが発生しました。

解説(Remarks)

呼び出し元への注意事項

OnPosRectChange メソッドは、インプレースオブジェクトによって呼び出されます。

実装者への注意事項

インプレースオブジェクトが OnPosRectChange を呼び出した場合、コンテナーは IOleInPlaceObject::SetObjectRects を呼び出して、インプレースウィンドウの新しい位置とクリッピング矩形を指定する必要があります。それを行って初めて、オブジェクトは自身のウィンドウのサイズを変更します。

ほとんどの場合、オブジェクトは右方向および/または下方向に拡大します。lprcPosRect を通じて示されるように、オブジェクトが左方向および/または上方向に拡大する場合もあります。また、サイズを変更せずにオブジェクトの位置を変更することも可能です。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IOleInPlaceSite "{00000119-0000-0000-C000-000000000046}"
#usecom global IOleInPlaceSite IID_IOleInPlaceSite "{}"
#comfunc global IOleInPlaceSite_CanInPlaceActivate   5
#comfunc global IOleInPlaceSite_OnInPlaceActivate    6
#comfunc global IOleInPlaceSite_OnUIActivate         7
#comfunc global IOleInPlaceSite_GetWindowContext     8 sptr,sptr,var,var,var
#comfunc global IOleInPlaceSite_Scroll               9 int
#comfunc global IOleInPlaceSite_OnUIDeactivate       10 int
#comfunc global IOleInPlaceSite_OnInPlaceDeactivate  11
#comfunc global IOleInPlaceSite_DiscardUndoState     12
#comfunc global IOleInPlaceSite_DeactivateAndUndo    13
#comfunc global IOleInPlaceSite_OnPosRectChange      14 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IOleInPlaceSite "{00000119-0000-0000-C000-000000000046}"
#usecom global IOleInPlaceSite IID_IOleInPlaceSite "{}"
#comfunc global IOleInPlaceSite_CanInPlaceActivate   5
#comfunc global IOleInPlaceSite_OnInPlaceActivate    6
#comfunc global IOleInPlaceSite_OnUIActivate         7
#comfunc global IOleInPlaceSite_GetWindowContext     8 sptr,sptr,sptr,sptr,sptr
#comfunc global IOleInPlaceSite_Scroll               9 int
#comfunc global IOleInPlaceSite_OnUIDeactivate       10 int
#comfunc global IOleInPlaceSite_OnInPlaceDeactivate  11
#comfunc global IOleInPlaceSite_DiscardUndoState     12
#comfunc global IOleInPlaceSite_DeactivateAndUndo    13
#comfunc global IOleInPlaceSite_OnPosRectChange      14 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。