IOleControlSite
COM公式ドキュメント
サイトオブジェクトが、コンテナー内に埋め込まれた各コントロールを管理できるようにするためのメソッドを提供します。
メソッド 7
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
コントロールの CONTROLINFO 構造体が変更されたことをコンテナーに通知し、コンテナーが更新のためにコントロールの IOleControl::GetControlInfo を呼び出す必要があることを示します。
戻り値
このメソッドはすべての場合において S_OK を返します。
コントロールをインプレースアクティブのまま維持すべきかどうかを示します。通常、このメソッドの呼び出しはイベントをネストして、イベントの処理中を通じてオブジェクトのアクティブ化状態が安定した状態に保たれるようにします。
| fLock | BOOL | in | インプレースアクティブ状態を維持する（TRUE）か、アクティブ化の変更を許可する（FALSE）かを示します。TRUE の場合、対応するコンテナーは、このメソッドが再度 FALSE で呼び出されるまで、インプレースオブジェクトを非アクティブ化してはなりません。 |
戻り値
解説(Remarks)
このメソッドはコントロールのインプレースアクティブ状態に影響しますが、UI アクティブ状態には影響しません。
コンテナーが実際のコントロールをラップするために使用する拡張コントロールへの IDispatch ポインターを取得します。
| ppDisp | IDispatch** | out | 拡張コントロールへのインターフェイスポインターを受け取る IDispatch ポインター変数へのポインター。エラーが発生した場合、実装は *ppDisp を NULL に設定する必要があります。成功した場合、呼び出し元は *ppDisp が不要になった時点で Release を呼び出す責任があります。 |
戻り値
このメソッドは、標準の戻り値である E_OUTOFMEMORY および E_UNEXPECTED に加えて、次の値を返す可能性があります。
| 戻り値コード | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| コンテナーは拡張コントロールを実装していません。 | |
| ppDisp または *ppDisp のアドレスが無効です。たとえば、NULL である可能性があります。 |
解説(Remarks)
このメソッドは、コンテナーが拡張コントロール内で保持しているプロパティおよびメソッドへのアクセスを実際のコントロールに与えます。これらのプロパティおよびメソッドは、これがなければコントロールからはアクセスできません。
呼び出し元への注意
返されたポインターは呼び出し元の責任であり、不要になった時点で解放する必要があります。HIMETRIC 単位（OLE で標準的に使用される単位）で表された座標を、コンテナーが指定する単位に変換します。
| pPtlHimetric | POINTL* | inout | HIMETRIC 単位で表された座標を含む POINTL 構造体のアドレス。dwFlags に XFORMCOORDS_HIMETRICTOCONTAINER が含まれる場合、これは [in] パラメーターです。XFORMCOORDS_CONTAINERTOHIMETRIC の場合は [out] パラメーターです。後者の場合、エラー時には内容は未定義です。 | ||||||||||||
| pPtfContainer | POINTF* | inout | 変換後の座標を受け取る、呼び出し元が割り当てた POINTF 構造体のアドレス。dwFlags に XFORMCOORDS_CONTAINERTOHIMETRIC が含まれる場合、これは [in] パラメーターです。XFORMCOORDS_HIMETRICTOCONTAINER の場合は [out] パラメーターです。後者の場合、エラー時には内容は未定義です。 | ||||||||||||
| dwFlags | DWORD | in | 実行する正確な変換を示すフラグ。このパラメーターには、指定がない限り、次の値の任意の組み合わせを指定できます。
|
戻り値
このメソッドは、標準の戻り値である E_INVALIDARG および E_UNEXPECTED に加えて、次の値を返す可能性があります。
| 戻り値コード | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| コンテナーは特別な座標変換を必要としません。コンテナーは完全に HIMETRIC で処理します。 | |
| pPtlHimetric または pPtfContainer のアドレスが無効です。たとえば、NULL である可能性があります。 |
解説(Remarks)
コントロールは、イベント内やその他のカスタム呼び出しでコンテナーに座標を送信する必要がある場合、またはコンテナー座標を HIMETRIC 単位に変換する必要がある場合に、このメソッドを使用します。
キーストロークを処理のためにコントロールサイトに渡します。
| pMsg | MSG* | in | 処理対象のキーストロークを記述する MSG 構造体へのポインター。 |
| grfModifiers | KEYMODIFIERS | in | Control、Alt、Shift の各キーの状態を記述するフラグ。このフラグの値には、有効な KEYMODIFIERS 列挙値のいずれかを指定できます。 |
戻り値
このメソッドは次の値を返す可能性があります。
| 戻り値コード | 説明 |
|---|---|
| コンテナーがメッセージを処理しました。 | |
| コンテナーはメッセージを処理しませんでした。E_NOTIMPL 以外のすべてのエラーケースでも、この値を返す必要があります。 | |
| コンテナーはアクセラレーターのサポートを実装していません。 |
解説(Remarks)
このメソッドは、UI アクティブになり得るコントロールから呼び出されます。そのような場合、コントロールは、通常の OLE 複合ドキュメントのルールに従って、まずすべてのキーストロークを IOleInPlaceActiveObject::TranslateAccelerator を通じて処理できます。そのメソッド内で、コントロールは IOleControlSite::TranslateAccelerator を呼び出すことで特定のメッセージを先にコンテナーに処理させ、その戻り値を使用して何らかの処理が行われたかどうかを判断できます。それ以外の場合、コントロールは常に最初にメッセージを処理します。コントロールがキーストロークをアクセラレーターとして使用しない場合、このメソッドを通じてキーストロークをコンテナーに渡します。
このコントロールサイトが管理するコントロールがフォーカスを取得したか、または失ったかを示します。
| fGotFocus | BOOL | in | コントロールがフォーカスを取得した（TRUE）か、失った（FALSE）かを示します。 |
戻り値
このメソッドはすべての場合において S_OK を返します。
解説(Remarks)
コンテナーはこの情報を使用して、フォーカスを持つコントロールが Return キーや Esc キーをどのように処理するかに応じて、既定ボタンおよびキャンセルボタンの状態を更新します。Return キーおよび Esc キーに関するコントロールの動作は、コントロールの CONTROLINFO 構造体で指定されます。詳細については、IOleControl::GetControlInfo を参照してください。
このサイトに埋め込まれたコントロールのプロパティシートを表示するようコンテナーに指示します。
戻り値
このメソッドは、標準の戻り値である E_OUTOFMEMORY に加えて、次の値を返す可能性があります。
| 戻り値コード | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| コンテナー自身がプロパティページを表示する必要はありません。 |
解説(Remarks)
コントロールは、自身のプロパティページを表示しようとする場合、常にまずコンテナー内でこのメソッドを呼び出す必要があります。このメソッドを呼び出すことで、コンテナーがそれらのプロパティページをコンテナーの拡張コントロールと連携させる機会を得られます。そのような場合、コンテナーは自身のプロパティページを含めることもでき、これはコントロールにはまったく影響しません。コンテナーがこのメソッドを実装していない場合、または何らかの失敗を返す場合、コントロールは自身のプロパティページを直接表示できます。それ以外の場合は、コンテナーがページを表示しています。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IOleControlSite "{B196B289-BAB4-101A-B69C-00AA00341D07}" #usecom global IOleControlSite IID_IOleControlSite "{}" #comfunc global IOleControlSite_OnControlInfoChanged 3 #comfunc global IOleControlSite_LockInPlaceActive 4 int #comfunc global IOleControlSite_GetExtendedControl 5 sptr #comfunc global IOleControlSite_TransformCoords 6 var,var,int #comfunc global IOleControlSite_TranslateAccelerator 7 var,int #comfunc global IOleControlSite_OnFocus 8 int #comfunc global IOleControlSite_ShowPropertyFrame 9 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IOleControlSite "{B196B289-BAB4-101A-B69C-00AA00341D07}" #usecom global IOleControlSite IID_IOleControlSite "{}" #comfunc global IOleControlSite_OnControlInfoChanged 3 #comfunc global IOleControlSite_LockInPlaceActive 4 int #comfunc global IOleControlSite_GetExtendedControl 5 sptr #comfunc global IOleControlSite_TransformCoords 6 sptr,sptr,int #comfunc global IOleControlSite_TranslateAccelerator 7 sptr,int #comfunc global IOleControlSite_OnFocus 8 int #comfunc global IOleControlSite_ShowPropertyFrame 9 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。