IOleInPlaceFrame

コンテナーのトップレベルのフレームウィンドウを制御します。

インプレースセッション中に使用される複合メニューへ、コンテナーがメニューグループを挿入できるようにします。

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

戻り値	説明
E_UNEXPECTED	予期しないエラーが発生しました。

呼び出し側への注意

このメソッドは、オブジェクトアプリケーションが最初にアクティブ化されるときに呼び出されます。オブジェクトアプリケーションは、自身のメニューをフレームレベルのユーザーインターフェイスに挿入するためにこれを呼び出します。

オブジェクトアプリケーションは、hmenuShared で指定されたメニューに自身のメニューを追加し、lpMenuWidths が指す OLEMENUGROUPWIDTHS 配列内のグループカウントを設定するよう、コンテナーに要求します。次に、オブジェクトアプリケーションは自身のメニューとカウントを追加します。オブジェクトは、複合メニューを構築するために必要なだけ IOleInPlaceFrame::InsertMenus を呼び出すことができます。コンテナーは、ドロップダウンメニュー内のすべてのメニュー項目に対して、複合メニューに関連付けられた最初のメニューハンドルを使用する必要があります。

インプレースでアクティブ化されるオブジェクトを含むウィンドウフレームに、複合メニューを追加します。

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

戻り値	説明
E_INVALIDARG	指定されたハンドルが無効です。
E_UNEXPECTED	予期しないエラーが発生しました。

呼び出し側への注意

オブジェクトは、IOleInPlaceFrame::InsertMenus の呼び出しによって設定された複合メニュー構造をインストールするようコンテナーに要求するために、IOleInPlaceFrame::SetMenu を呼び出します。

実装者への注意

SDI コンテナーによるこのメソッドの実装では、SetMenu 関数を呼び出す必要があります。MDI コンテナーは、インストールするメニューとして hmenuShared を使用し、WM_MDISETMENU メッセージを送信する必要があります。コンテナーは、OLE のディスパッチコードをインストールするために OleSetMenuDescriptor を呼び出す必要があります。

非アクティブ化する際、コンテナーは、共有メニューを削除するために NULL を指定して IOleInPlaceFrame::SetMenu を呼び出す必要があります。これは、ウィンドウの再描画を最小限に抑えるために行われます。コンテナーはまた、ディスパッチコードのフックを解除するために NULL を指定して OleSetMenuDescriptor を呼び出す必要があります。最後に、オブジェクトアプリケーションは、データ構造を解放するために OleDestroyMenuDescriptor を呼び出します。

コンテナーのメニュー要素を複合メニューから削除します。

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

戻り値	説明
E_INVALIDARG	指定されたハンドルが無効です。
E_UNEXPECTED	予期しないエラーが発生しました。

オブジェクトは、共有ユーザーインターフェイスを非アクティブ化する前に、必ずコンテナーが自身のメニュー要素を複合メニューから削除する機会を与える必要があります。

呼び出し側への注意

このメソッドは、オブジェクトアプリケーションが UI を非アクティブ化する際に、自身のメニューを削除するために呼び出します。

インプレースオブジェクトに関するステータステキストを設定し、コンテナーのフレームウィンドウのステータス行に表示します。

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

戻り値	説明
S_TRUNCATED	テキストの一部は表示されましたが、メッセージが長すぎたため切り詰められました。
E_FAIL	操作が失敗しました。
E_INVALIDARG	指定されたポインターが無効です。
E_UNEXPECTED	予期しないエラーが発生しました。

呼び出し側への注意

コンテナーのフレームにステータス行がある場合に、そこへオブジェクトのテキストを表示するようコンテナーに要求する必要があるときは、IOleInPlaceFrame::SetStatusText を呼び出してください。ステータス行はコンテナーのフレームウィンドウが所有しているため、オブジェクトがコンテナーのフレームウィンドウにステータス情報を表示できる唯一の方法は、IOleInPlaceFrame::SetStatusText を呼び出すことです。ただし、コンテナーがオブジェクトの要求を拒否した場合でも、オブジェクトアプリケーションは、独自のステータスウィンドウを表示するためのボーダースペースについて交渉することができます。

コンテナーが所有するメニューとインプレースアクティブなオブジェクトが所有するメニューを切り替える際、オブジェクトがコンテナーの IOleInPlaceFrame::SetStatusText メソッドを呼び出さないと、ステータスバーのテキストが正しく反映されません。たとえば、インプレースセッション中にユーザーが File メニューを選択した場合、ステータスバーには、このメニューを選択したときに発生する動作が反映されます。次にユーザーが（インプレースオブジェクトが所有する）Edit メニューを選択した場合、たまたま IOleInPlaceFrame::SetStatusText が呼び出されない限り、ステータスバーのテキストは変化しません。これは、コンテナーがトラップするはずのすべてのメッセージがオブジェクトに送られるようになるため、オブジェクトのメニューの 1 つがアクティブになったことをコンテナーが認識する手段がないためです。

実装者への注意

潜在的な問題を回避するため、インプレースでアクティブ化されるすべてのオブジェクトは、通常はステータス情報を提供しない場合であっても、WM_MENUSELECT メッセージを処理し、IOleInPlaceFrame::SetStatusText を呼び出す必要があります（その場合、オブジェクトは要求されたステータステキストとして単に NULL 文字列を渡すことができます）。

フレームのモードレスダイアログボックスを有効または無効にします。

このメソッドは、fEnable の値に応じて、ダイアログボックスが正常に有効化または無効化された場合に S_OK を返します。

オブジェクトがインプレースでアクティブな間に、コンテナーのフレーム向けのアクセラレーターキー入力を変換します。

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

戻り値	説明
S_FALSE	キー入力は使用されませんでした。
E_INVALIDARG	指定されたポインターが無効です。
E_UNEXPECTED	予期しないエラーが発生しました。

呼び出し側への注意

IOleInPlaceFrame::TranslateAccelerator メソッドは、コンテナー（フレーム）向けのアクセラレーターキー入力を受信したときに、OleTranslateAccelerator によって間接的に呼び出されます。

実装者への注意

コンテナーアプリケーションは、通常のアクセラレーター処理を実行するか、または wID を直接使用し、その後、アクセラレーターキー入力が処理されたかどうかを示して戻る必要があります。コンテナーが MDI アプリケーションで、TranslateAccelerator 関数が失敗した場合、コンテナーは、通常のメッセージ処理と同様に TranslateMDISysAccel 関数を呼び出すことができます。

インプレースオブジェクトには、アクセラレーターメッセージの変換を最初に試みる機会が与えられるべきです。ただし、DLL オブジェクトアプリケーションによって実装されたオブジェクトは独自のメッセージポンプを持たないため、コンテナーのメッセージキューからメッセージを受け取ります。オブジェクトが最初にメッセージを変換する機会を確実に得られるようにするため、コンテナーは自身のアクセラレーター変換を行う前に、常に IOleInPlaceFrame::TranslateAccelerator を呼び出す必要があります。逆に、実行可能形式のオブジェクトアプリケーションは、TranslateAccelerator を呼び出した後に OleTranslateAccelerator を呼び出し、両方の変換関数が失敗した場合にのみ TranslateMessage と DispatchMessage を呼び出す必要があります。

コンテナー用のアクセラレーターテーブルは、独自のアクセラレーターキー入力変換を行うオブジェクトアプリケーションと正しく連携できるように定義する必要があります。テーブルは、次のように定義してください。

"char", wID, VIRTKEY, CONTROL

これは、キーボードアクセラレーターを記述する最も一般的な方法です。このように定義しないと、インプレースセッション中にキー入力が失われたり、誤ったオブジェクトに送られたりする可能性があります。

#define global IID_IOleInPlaceFrame "{00000116-0000-0000-C000-000000000046}"
#usecom global IOleInPlaceFrame IID_IOleInPlaceFrame "{}"
#comfunc global IOleInPlaceFrame_InsertMenus           9 sptr,var
#comfunc global IOleInPlaceFrame_SetMenu               10 sptr,sptr,sptr
#comfunc global IOleInPlaceFrame_RemoveMenus           11 sptr
#comfunc global IOleInPlaceFrame_SetStatusText         12 wstr
#comfunc global IOleInPlaceFrame_EnableModeless        13 int
#comfunc global IOleInPlaceFrame_TranslateAccelerator  14 var,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。