IOleDocumentSite

COM

IIDb722bcc7-4e68-101b-a2bc-00aa00404770継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ドキュメントオブジェクトとして実装されたドキュメントが、インプレースアクティブオブジェクトに対する通常のアクティブ化シーケンスをバイパスし、クライアントサイトに対してドキュメントオブジェクトとしてアクティブ化するよう直接指示できるようにします。

メソッド 1

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

vtbl 3 HRESULT ActivateMe(IOleDocumentView* pViewToActivate)

ドキュメントサイトに対し、呼び出し元のドキュメントをインプレースアクティブオブジェクトではなくドキュメントオブジェクトとしてアクティブ化するよう要求します。また、オプションでオブジェクトドキュメントのどのビューをアクティブ化するかを指定します。

pViewToActivate

IOleDocumentView*

ドキュメントオブジェクトのアクティブ化に使用するドキュメントビューを表す IOleDocumentView インターフェイスポインターへのポインターです。このパラメーターは NULL にすることができ、その場合コンテナーは IOleDocument::CreateView を呼び出してドキュメントビューポインターを取得する必要があります。

戻り値

このメソッドは成功時に S_OK を返します。

解説(Remarks)

コンテナーがドキュメントをアクティブ化するために IOleObject::DoVerb を呼び出すと、ドキュメントオブジェクトは IOleDocumentSite::ActivateMe を呼び出すことで、通常のインプレースアクティブ化シーケンスをバイパスします。

ドキュメントオブジェクトに対して IOleObject::DoVerb を呼び出す際、最も適切なアクティブ化動詞は通常 OLEIVERB_SHOW です。その他に使用できる動詞には OLEIVERB_PRIMARY および OLEIVERB_UIACTIVATE があります。OLEIVERB_OPEN は、埋め込みオブジェクトを別のウィンドウで開くことを意味し、ドキュメントオブジェクトのアクティブ化の意図に反するため推奨されません。

呼び出し元への注意

このメソッドを呼び出すのはドキュメントオブジェクトのみである必要があります。通常のインプレースアクティブなドキュメントは、コンテナーによる IOleObject::DoVerb の呼び出しに対して、IOleInPlaceSite を呼び出すことで応答する必要があります。

ドキュメントオブジェクトは、IOleDocumentSite::ActivateMe を呼び出すことでアクティブ化を開始する必要があります。コンテナーが IOleDocumentSite を実装していない場合、ドキュメントは通常のインプレースアクティブ化シーケンスにフォールバックする必要があります。

データの複数のビューをサポートするドキュメントオブジェクトは、そのビューの IOleDocumentView インターフェイスへのポインターを pViewToActivate に渡すことで、どのビューをアクティブ化するかを指定できます。

IOleDocumentView ポインターをどのように取得したかにかかわらず、コンテナーは不要になった時点でそのポインターを解放する必要があります。

実装者への注意

この関数はドキュメントオブジェクトコンテナー内で完全に実装する必要があります。E_NOTIMPL は許容される戻り値ではありません。

ドキュメントオブジェクトが pViewToActivate に IOleDocumentView ポインターを渡した場合、コンテナーの IOleDocumentSite::ActivateMe の実装は IOleDocumentView::SetInPlaceSite を呼び出し、自身の IOleInPlaceSite インターフェイスへのポインターをビューオブジェクトに返す必要があります。コンテナーが IOleDocumentView ポインターを保持している場合(通常はそうなります)、IOleDocumentView::SetInPlaceSite の呼び出しに続けて IUnknown::AddRef を呼び出す必要があります。

pViewToActivate が NULL の場合、コンテナーはドキュメントに対して IOleDocument をクエリし、次に IOleDocument::CreateView を呼び出して自身の IOleInPlaceSite ポインターを渡すことで、ドキュメントビューへのポインターを取得できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IOleDocumentSite "{B722BCC7-4E68-101B-A2BC-00AA00404770}"
#usecom global IOleDocumentSite IID_IOleDocumentSite "{}"
#comfunc global IOleDocumentSite_ActivateMe  3 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。