IOleInPlaceUIWindow

コンテナーアプリケーションによって実装され、オブジェクトアプリケーションがドキュメントウィンドウまたはフレームウィンドウ上のボーダースペースをネゴシエートするために使用します。

オブジェクトがインプレースでアクティブな状態のときに、ツールバーおよびコントロール用の外側の矩形を取得します。

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

戻り値	説明
INPLACE_E_NOTOOLSPACE	オブジェクトはこのウィンドウオブジェクトにツールバーをインストールできません。
E_OUTOFMEMORY	この操作に使用できるメモリが不足しています。
E_UNEXPECTED	予期しないエラーが発生しました。

呼び出し側への注意

IOleInPlaceUIWindow::GetBorder 関数は、ドキュメントウィンドウまたはフレームウィンドウのオブジェクトに対して呼び出されると、オブジェクトがツールバーまたは同様のコントロールを配置できる外側の矩形(ウィンドウを基準とした相対座標)を返します。

オブジェクトがこれらのツールをインストールする場合は、IOleInPlaceUIWindow::RequestBorderSpace を使用してこの矩形内でツール用のスペースをネゴシエートし、その後 IOleInPlaceUIWindow::SetBorderSpace を呼び出してこのスペースを割り当てる必要があります。

オブジェクトがインプレースでアクティブな状態のときに、オブジェクトのウィンドウフレーム周辺にツールをインストールするためのスペースが利用可能かどうかを判定します。

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

戻り値	説明
INPLACE_E_NOTOOLSPACE	実装がツールバーをサポートしていない、またはツールバーをインストールするための十分なスペースがないため、オブジェクトはこのウィンドウオブジェクトにツールバーをインストールできません。
E_UNEXPECTED	予期しないエラーが発生しました。

呼び出し側への注意

インプレースでアクティブなオブジェクトは、IOleInPlaceUIWindow::RequestBorderSpace を呼び出して、ウィンドウフレーム内にツールをインストールできるかどうかを問い合わせます。これらのツールは、IOleInPlaceUIWindow::GetBorder が返した矩形と、この呼び出しの引数で指定される BORDERWIDTHS 構造体との間に割り当てられます。

ツール用のスペースは、オブジェクトが IOleInPlaceUIWindow::SetBorderSpace を呼び出すまで実際には割り当てられません。これにより、オブジェクトは(ツールバーをドラッグして移動する場合などに)スペースのネゴシエーションを行いつつ、ツールの実際の移動を操作の完了まで遅延させることができます。

オブジェクトは、各辺で使用するピクセル単位の幅を渡すことでこれらのツールをインストールできます。たとえば、オブジェクトが上に10ピクセル、下に0ピクセル、左右に5ピクセルずつ必要とする場合、IOleInPlaceUIWindow::RequestBorderSpace に次の BORDERWIDTHS 構造体を渡します。

lpbw->top    = 10
lpbw->bottom =  0
lpbw->lLeft  =  5
lpbw->right  =  5

実装者への注意

アクティブなオブジェクトがツールバーに使用するスペースの量がコンテナーにとって重要でない場合は、次の IOleInPlaceUIWindow::RequestBorderSpace の例に示すように単に NOERROR を返すことができます。コンテナーは、インプレースでアクティブなオブジェクトによるツールの表示を過度に制限すべきではありません。

HRESULT InPlaceUIWindow_RequestBorderSpace( 
    IOleInPlaceFrame *  lpThis, 
    LPCBORDERWIDTHS     pborderwidths) 
{ 
    // Container allows the object to have as much border space as it 
    // wants.  
    return NOERROR; 
} 

IOleInPlaceUIWindow::RequestBorderSpace の呼び出しで要求されたボーダー用のスペースを割り当てます。

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

戻り値	説明
OLE_E_INVALIDRECT	矩形が IOleInPlaceUIWindow::GetBorder が返した仕様の範囲内にありません。

オブジェクトは IOleInPlaceUIWindow::SetBorderSpace を呼び出す必要があります。次のいずれかを行うことができます。

• 独自のツールバーを使用し、特定のサイズのボーダースペースを要求します。
• ツールバーを使用しませんが、pborderwidths パラメーターにすべてゼロのみを含む有効な BORDERWIDTHS 構造体を渡すことで、コンテナーに自身のツールバーを削除させます。
• ツールバーを使用しませんが、pborderwidths パラメーターに NULL を渡すことで、インプレースコンテナーが自身のツールバーを表示したままにすることを許可します。

この呼び出しで使用する BORDERWIDTHS 構造体は、通常、直前の IOleInPlaceUIWindow::RequestBorderSpace の呼び出しで渡されたものであり、その呼び出しは S_OK を返している必要があります。

オブジェクトがボーダー上のスペースを再ネゴシエートする必要がある場合は、新しい幅を指定して IOleInPlaceUIWindow::SetBorderSpace を再度呼び出すことができます。IOleInPlaceUIWindow::SetBorderSpace の呼び出しが失敗した場合、オブジェクトは IOleInPlaceUIWindow::GetBorder、IOleInPlaceUIWindow::RequestBorderSpace、および IOleInPlaceUIWindow::SetBorderSpace の呼び出しによって、ボーダースペースの完全なネゴシエーションを行うことができます。

オブジェクトとフレームウィンドウおよびドキュメントウィンドウのそれぞれとの間に、直接の通信チャネルを提供します。

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

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

一般に、埋め込みオブジェクトは pszObjName パラメーターに NULL を渡すべきです(以下の「実装者への注意」を参照)。ただし、インプレースでアクティブなオブジェクトの名前をタイトルバーに表示するコンテナーと連携して動作する場合は、次の形式の文字列を構成する必要があります: <アプリケーション名> – <オブジェクトの短い型名>。

呼び出し側への注意

IOleInPlaceUIWindow::SetActiveObject は、オブジェクトが自身とドキュメントウィンドウおよびフレームウィンドウとの間に直接の通信リンクを確立するために呼び出します。

非アクティブ化するとき、オブジェクトは pActiveObject および pszObjName パラメーターに NULL を渡して IOleInPlaceUIWindow::SetActiveObject を呼び出します。

オブジェクトは、IOleInPlaceFrame::SetMenu を呼び出す前に IOleInPlaceUIWindow::SetActiveObject を呼び出して、コンテナーにアクティブなオブジェクトへのポインターを渡す必要があります。コンテナーはその後、このポインターを IOleInPlaceFrame::SetMenu の処理に使用し、OleSetMenuDescriptor に渡します。

実装者への注意

Microsoft Windows ユーザーインターフェースデザインガイドでは、インプレースコンテナーはこのメソッドで渡される pszObjName パラメーターを無視することを推奨しています。同ガイドには「タイトルバーはインプレースアクティブ化の影響を受けない。常に最上位コンテナーの名前を表示する。」と記載されています。

#define global IID_IOleInPlaceUIWindow "{00000115-0000-0000-C000-000000000046}"
#usecom global IOleInPlaceUIWindow IID_IOleInPlaceUIWindow "{}"
#comfunc global IOleInPlaceUIWindow_GetBorder           5 var
#comfunc global IOleInPlaceUIWindow_RequestBorderSpace  6 var
#comfunc global IOleInPlaceUIWindow_SetBorderSpace      7 var
#comfunc global IOleInPlaceUIWindow_SetActiveObject     8 sptr,wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。