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

IOleControl

COM
📘 Microsoft Learn (日本語) · English
IIDb196b288-bab4-101a-b69c-00aa00341d07継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

コントロールオブジェクトにおけるキーボードニーモニック、アンビエントプロパティ、およびイベントをサポートするための機能を提供します。

メソッド 4

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

vtbl 3 HRESULT GetControlInfo(CONTROLINFO* pCI)

コントロールのキーボードニーモニックと動作に関する情報を取得します。

pCICONTROLINFO*inout情報を受け取る CONTROLINFO 構造体へのポインター。

戻り値

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

戻り値 説明
S_OK
 メソッドは正常に完了しました。
E_NOTIMPL
 コントロールにニーモニックがありません。
E_POINTER
 pCI のアドレスが無効です。たとえば NULL である可能性があります。
vtbl 4 HRESULT OnMnemonic(MSG* pMsg)

キーボードニーモニックを表すキー操作をユーザーが押したことをコントロールに通知します。

pMsgMSG*in処理対象のキー操作を表す MSG 構造体へのポインター。

戻り値

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

戻り値 説明
S_OK
 メソッドは正常に完了しました。
E_NOTIMPL
 コントロールはニーモニックを処理しません。これは予期しない状態であり、呼び出し元のエラーを示します。たとえば、呼び出し元がどのコントロールがどのニーモニックを持つかを取り違えている場合です。

解説(Remarks)

キー操作は、IOleControl::GetControlInfo を通じて返されるニーモニックテーブル内の ACCEL エントリのいずれかに一致する必要があります。コントロールは、そのキー操作に対して適切な処理を行います。

呼び出し元への注意

コントロールのコンテナーは、キャッシュした情報をいつ更新すべきかを知るために IOleControlSite::OnControlInfoChanged を実装していれば、コントロールの CONTROLINFO 構造体をキャッシュすることが許可されています。

実装者への注意

コントロールが自身の CONTROLINFO 構造体の内容を変更した場合は、IOleControlSite::OnControlInfoChanged を呼び出してコンテナーに通知する必要があります。
vtbl 5 HRESULT OnAmbientPropertyChange(INT dispID)

コンテナーのアンビエントプロパティのうち 1 つ以上が変更されたことをコントロールに通知します。

dispIDINTin変更されたアンビエントプロパティのディスパッチ識別子。このパラメーターが DISPID_UNKNOWN の場合は、複数のプロパティが変更されたことを示します。この場合、コントロールは関心のあるすべてのアンビエントプロパティを確認し、現在の値を取得する必要があります。

戻り値

このメソッドは、すべての場合において S_OK を返します。

解説(Remarks)

実装者への注意

コントロールがアンビエントプロパティをサポートしていない場合やその他の失敗が発生した場合であっても、すべての場合において S_OK が返されます。通知を送信する呼び出し元は、今後通知を送信するかどうかを判断するためにエラーコード(E_NOTIMPL など)を利用することはできません。そのようなセマンティクスはこのインターフェイスの一部ではありません。
vtbl 6 HRESULT FreezeEvents(BOOL bFreeze)

コンテナーがコントロールからのイベントを無視しているか受け入れているかを示します。

bFreezeBOOLinコンテナーがコントロールからのイベントを無視する(TRUE)か、これから処理する(FALSE)かを示します。

戻り値

このメソッドは、すべての場合において S_OK を返します。

解説(Remarks)

bFreeze が TRUE のとき、コントロールはイベントの送信を停止する必要はありません。ただし、この場合コンテナーはそれらを処理しません。コンテナーの処理に依存するコントロール(コンテナーから情報を返す要求イベントなど)の場合、コントロールはそのイベントを破棄するか、bFreeze が FALSE になったときに後で送信するためにキューに入れる必要があります。

実装者への注意

IOleControl::OnAmbientPropertyChange と同様に、コンテナーが戻り値に基づいてコントロールの動作について推測を行うことを防ぐため、すべての場合において S_OK が返されます。
出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IOleControl "{B196B288-BAB4-101A-B69C-00AA00341D07}"
#usecom global IOleControl IID_IOleControl "{}"
#comfunc global IOleControl_GetControlInfo           3 var
#comfunc global IOleControl_OnMnemonic               4 var
#comfunc global IOleControl_OnAmbientPropertyChange  5 int
#comfunc global IOleControl_FreezeEvents             6 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。