IOleInPlaceSiteWindowless

IOleInPlaceSiteEx インターフェイスを拡張します。

コンテナーが、オブジェクトをインプレースアクティブ化できるウィンドウレスオブジェクトとしてサポートできるかどうかをオブジェクトに通知します。

オブジェクトがウィンドウなしでインプレースアクティブ化できる場合、このメソッドは S_OK を返します。

このメソッドが S_OK を返す場合、コンテナーは IOleInPlaceObjectWindowless を使用してオブジェクトにイベントをディスパッチできます。

このメソッドが S_FALSE を返す場合、オブジェクトはウィンドウを作成し、通常の複合ドキュメントオブジェクトとして動作する必要があります。

インプレースアクティブなウィンドウレスオブジェクトが、まだマウスキャプチャを保持しているかどうかを判断するために呼び出します。

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

Return code	Description
S_FALSE	オブジェクトは現在マウスキャプチャを保持していません。

このメソッドを呼び出す代わりに、オブジェクトはマウスキャプチャを保持しているかどうかの情報をキャッシュすることもできます。

インプレースアクティブなウィンドウレスオブジェクトがすべてのマウスメッセージをキャプチャできるようにします。

マウスキャプチャがオブジェクトに正常に付与された場合、このメソッドは S_OK を返します。マウスキャプチャを解放するために呼び出された場合、このメソッドは失敗してはなりません。その他に返される可能性のある値は次のとおりです。

Return code	Description
S_FALSE	オブジェクトへのマウスキャプチャが拒否されました。

ウィンドウレスオブジェクトは、そのサイトオブジェクト上で IOleInPlaceSiteWindowless::SetCapture を TRUE で呼び出すことにより、マウス入力をキャプチャします。コンテナーはマウスキャプチャを拒否でき、その場合このメソッドは S_FALSE を返します。キャプチャが付与された場合、コンテナーは Windows のマウスキャプチャを自身のウィンドウに設定し、マウスカーソルの位置がこのオブジェクトの上にあるかどうかにかかわらず、以降のマウスメッセージをすべてオブジェクトにディスパッチする必要があります。

オブジェクトは後で、そのサイトオブジェクト上で IOleInPlaceSiteWindowless::SetCapture を FALSE で呼び出すことにより、マウスキャプチャを解放できます。キャプチャは、ESC キーが押されるなどの外部イベントによっても解放されることがあります。この場合、コンテナーがキーボードフォーカスとともにディスパッチする WM_CANCELMODE メッセージによって、オブジェクトに通知されます。

コンテナーは、WM_SETCURSOR を含むすべてのマウスメッセージを、マウスをキャプチャしたウィンドウレス OLE オブジェクトにディスパッチする必要があります。マウスをキャプチャしているオブジェクトがない場合、コンテナーはマウスカーソルの下にあるオブジェクトにマウスメッセージをディスパッチする必要があります。

コンテナーは、ウィンドウレスオブジェクト上で IOleInPlaceObjectWindowless::OnWindowMessage を呼び出すことにより、これらのウィンドウメッセージをディスパッチします。ウィンドウレスオブジェクトは、マウスメッセージを処理しなかったことを示すために、このメソッドに対して S_FALSE を返すことができます。その場合、コンテナーは DefWindowProc 関数を呼び出すことにより、メッセージのデフォルト動作を実行する必要があります。WM_SETCURSOR については、コンテナーはカーソルを自身で設定することも、何もしないこともできます。

オブジェクトは、IOleInPlaceSiteWindowless::OnDefWindowMessage を使用して、コンテナーからのデフォルトメッセージ処理を呼び出すこともできます。WM_SETCURSOR メッセージの場合、これにより、コンテナーがカーソルを設定しないときにオブジェクトがアクションを実行できます。

インプレースアクティブなウィンドウレスオブジェクトが、まだキーボードフォーカスを保持しているかどうかを判断するために呼び出します。

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

Return code	Description
S_FALSE	オブジェクトは現在キーボードフォーカスを保持していません。

ウィンドウレスオブジェクトは、現在フォーカスを保持しているかどうかを調べるためにこのメソッドを呼び出します。このメソッドを呼び出す代わりに、オブジェクトはキーボードフォーカスを保持しているかどうかの情報をキャッシュすることもできます。

UI アクティブなウィンドウレスオブジェクトのキーボードフォーカスを設定します。

キーボードフォーカスがオブジェクトに正常に付与された場合、このメソッドは S_OK を返します。フォーカスを解放するために呼び出された場合、このメソッドは決して失敗しないはずです。その他に返される可能性のある値は次のとおりです。

Return code	Description
S_FALSE	オブジェクトへのキーボードフォーカスが拒否されました。

ウィンドウレスオブジェクトは、ウィンドウを持つオブジェクトが SetFocus 関数を呼び出すのと同じタイミングで、このメソッドを呼び出します。この呼び出しを通じて、ウィンドウレスオブジェクトはキーボードフォーカスを取得し、ウィンドウメッセージに応答できます。通常、この呼び出しは UI アクティブ化プロセス中に、通知メソッド IOleInPlaceActiveObject::OnDocWindowActivate を TRUE で、および IOleInPlaceActiveObject::OnFrameWindowActivate を TRUE で呼び出す中で行われます。

この呼び出しに応答して、コンテナーはキーボードメッセージの取得に使用しているウィンドウ(通常はコンテナーウィンドウ)に Windows フォーカスを設定し、以降のキーボードメッセージをフォーカスを要求したウィンドウレスオブジェクトにリダイレクトします。

ウィンドウレスオブジェクトは、fFocus パラメーターを FALSE に設定して IOleInPlaceSiteWindowless::SetFocus メソッドを呼び出すことにより、他のいずれのオブジェクトにも割り当てずにキーボードフォーカスを解放することもできます。この場合、コンテナーは NULL パラメーターで SetFocus 関数を呼び出して、どのウィンドウもフォーカスを持たないようにする必要があります。

オブジェクトに、コンテナーからスクリーンまたは互換デバイス用のデバイスコンテキストへのハンドルを提供します。

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

Return code	Description
OLE_E_NESTEDPAINT	コンテナーはすでに描画セッションの途中にあります。つまり、このメソッドがすでに呼び出されており、IOleInPlaceSiteWindowless::ReleaseDC メソッドがまだ呼び出されていません。

このメソッドで取得したデバイスコンテキストは、IOleInPlaceSiteWindowless::ReleaseDC を呼び出して解放する必要があります。

このインターフェイスの他のメソッドと同様に、矩形は含んでいるウィンドウのクライアント座標で指定します。コンテナーは、この矩形をオブジェクトのサイト矩形と交差させ、結果として得られる矩形の外側のすべてをクリップアウトすることが期待されます。これにより、オブジェクトが本来描画すべきでない場所に誤って描画することを防ぎます。

コンテナーは、オブジェクトが含んでいるウィンドウ(通常はコンテナーのウィンドウ)のクライアント座標で描画できるように、デバイスコンテキストの原点をマップすることも期待されます。コンテナーが単に自身のウィンドウデバイスコンテキストを渡している場合、これは自動的に行われます。別のデバイスコンテキスト(たとえばオフスクリーンのメモリデバイスコンテキストなど)を返している場合は、ビューポートの原点を適切に設定する必要があります。

実装者への注意

オンスクリーンとオフスクリーンのどちらのデバイスコンテキストを返すか、およびどの程度高度であるかに応じて、コンテナーは次のいずれかのアルゴリズムを使用できます。

1. オンスクリーン、シングルパス描画
   1. IOleInPlaceSiteWindowless::GetDC メソッドで、コンテナーは次のことを行う必要があります。
      • ウィンドウデバイスコンテキストを取得する。
      • OLEDC_PAINTBKGND が設定されている場合、デバイスコンテキストを要求しているオブジェクトの背後にあるすべてのオブジェクトの DVASPECT_CONTENT アスペクトを描画する。
      • デバイスコンテキストを返す。
   2. ReleaseDC メソッドで、コンテナーは次のことを行う必要があります。
      • 重なり合うすべてのオブジェクトの DVASPECT_CONTENT を描画する。
      • デバイスコンテキストを解放する。
2. オンスクリーン、ツーパス描画
   1. IOleInPlaceSiteWindowless::GetDC メソッドで、コンテナーは次のことを行う必要があります。
      • ウィンドウデバイスコンテキストを取得する。
      • 重なり合うオブジェクトの不透明な領域をクリップアウトする。これらの領域はスクリーン上ですでに正しいため、再描画する必要はありません。
      • OLEDC_PAINTBKGND が設定されていない場合、デバイスコンテキストを返す。
      • そうでない場合、デバイスコンテキストを要求しているオブジェクトの不透明な部分をクリップアウトし、その背後にあるすべてのオブジェクトの不透明な部分を手前から奥へ描画する。
      • 背後にあるすべてのオブジェクトの透明なアスペクトを奥から手前へ描画し、その都度クリッピング領域を適切に設定する。
      • 最後にデバイスコンテキストを返す。
   2. IOleInPlaceSiteWindowless::ReleaseDC メソッドで、コンテナーは次のことを行う必要があります。
      • 重なり合うすべてのオブジェクトの透明な部分を描画する。
      • デバイスコンテキストを解放する。
3. オフスクリーン描画
   1. IOleInPlaceSiteWindowless::GetDC メソッドで、コンテナーは次のことを行う必要があります。
      • 適切なサイズの互換ビットマップを含む、スクリーン互換のメモリデバイスコンテキストを作成する。
      • 呼び出し元オブジェクトが含んでいるウィンドウのクライアント領域座標を使用して描画できるように、デバイスコンテキストのビューポートの原点をマップする。
      • OLEDC_PAINTBKGND が設定されている場合、呼び出し元オブジェクトの背後にあるすべてのオブジェクトの DVASPECT_CONTENT を描画する。
      • デバイスコンテキストを返す。
   2. IOleInPlaceSiteWindowless::ReleaseDC メソッドで、コンテナーは次のことを行う必要があります。
      • 重なり合うすべてのオブジェクトの DVASPECT_CONTENT アスペクトを描画する。
      • オフスクリーンビットマップを、呼び出し元オブジェクトが IOleInPlaceSiteWindowless::GetDC で最初に要求した位置でスクリーンにコピーする。
      • メモリデバイスコンテキストを削除して解放する。

このメソッドが戻るとき、デバイスコンテキストのクリッピング領域は、オブジェクトが描画すべきでない領域に描画できないように設定されている必要があります。オブジェクトが不透明でない場合、背景は描画済みである必要があります。デバイスコンテキストがスクリーンの場合、重なり合う不透明な領域はクリップアウトされている必要があります。

IOleInPlaceSiteWindowless::GetDC の呼び出しによって以前に取得したデバイスコンテキストを解放します。

成功した場合、このメソッドは S_OK を返します。

オブジェクトは、デバイスコンテキストの使用が完了したことをコンテナーに通知するためにこのメソッドを呼び出します。デバイスコンテキストが描画に使用された場合、コンテナーは重なり合うすべてのオブジェクトが正しく再描画されるようにする必要があります。デバイスコンテキストがオフスクリーンデバイスコンテキストだった場合、その内容も IOleInPlaceSiteWindowless::GetDC に最初に渡された矩形内でスクリーンにコピーする必要があります。IOleInPlaceSiteWindowless::ReleaseDC に関連する実装上の注意については、IOleInPlaceSiteWindowless::GetDC を参照してください。

オブジェクトが、スクリーン上のインプレースイメージの指定された矩形を無効化できるようにします。

成功した場合、このメソッドは S_OK を返します。

オブジェクトは、自身のサイト矩形に含まれるピクセルのみを無効化できます。その矩形の外側の領域を無効化しようとしても、何も行われません。

オブジェクトが、スクリーン上のインプレースイメージの指定された領域を無効化できるようにします。

成功した場合、このメソッドは S_OK を返します。

オブジェクトは、自身のサイト領域に含まれるピクセルのみを無効化できます。その領域の外側の領域を無効化しようとしても、何も行われません。

オブジェクトが、スクリーン上のインプレースアクティブイメージ内の領域をスクロールできるようにします。

成功した場合、このメソッドは S_OK を返します。

このメソッドは、呼び出し元が透明である可能性、および不透明または透明な重なり合うオブジェクトが存在する可能性を考慮する必要があります。このメソッドが使用できるアルゴリズムの提案については、後述の「実装者への注意」を参照してください。

実装者への注意

コンテナーはこのメソッドをさまざまな方法で実装できます。ただし、いずれの場合も、スクロールを要求しているオブジェクトが透明である、または不透明な背景を持たない可能性を考慮する必要があります。コンテナーは、重なり合うオブジェクトが存在する可能性も考慮する必要があります。

このメソッドを実装する最も単純な方法は、スクロールする矩形を単純に再描画することです。

この単純な実装への追加的な改良として、スクロールを要求しているオブジェクトが不透明で、オブジェクトが不透明な背景を持ち、重なり合うオブジェクトが存在しない場合に、ScrollDC 関数を使用する方法があります。

より高度な実装では、次の手順を使用できます。

• IViewObjectEx::GetViewStatus を使用して、オブジェクトが不透明で不透明な背景を持つかどうかを確認します。そうでない場合は、スクロールする矩形を単純に無効化します。追加的な改良として、スクロール矩形が部分的に透明なオブジェクトの不透明な領域内に完全に収まっているかどうかを確認する方法があります。
• ウィンドウデバイスコンテキストを取得します。
• IViewObjectEx::GetRect によって返される重なり合うオブジェクトの不透明な部分をクリップアウトします。
• 最後に、ScrollDC 関数を呼び出します。
• 以前に無効化した、重なり合うオブジェクトの透明な部分を再描画します。

スクロール矩形やクリップ矩形にかかわらず、オブジェクトのサイト矩形に含まれるピクセルのみが描画されます。スクロール操作によって新たに現れた領域は無効化され、このメソッドが戻る前に直ちに再描画されます。

このメソッドによって生成されるすべての再描画は、このメソッドが戻る前に同期的に行われる必要があります。

このメソッドは、スクロール操作中にキャレットを自動的に非表示にし、キャレットがクリップ矩形の内側にある場合はスクロール量だけキャレットを移動する必要があります。

指定された矩形が、重なり合う不透明なオブジェクトによって全体または部分的に覆われている場合に、その矩形を調整します。

矩形が正常に調整された場合、つまり矩形が完全には覆われていなかった場合、このメソッドは S_OK を返します。その他に返される可能性のある値は次のとおりです。

Return code	Description
S_FALSE	矩形は正常に調整されました。S_FALSE は矩形が完全に覆われていたことを意味することに注意してください。その幅と高さは現在 NULL です。

このメソッドの主な用途は、キャレットのサイズを調整することです。キャレットを作成しようとするオブジェクトは、このメソッドを呼び出してキャレット矩形をサイトオブジェクトに提出し、そこから返された調整済みの矩形をキャレットに使用する必要があります。キャレットが完全に隠れている場合、このメソッドは S_FALSE を返し、この場合キャレットをまったく表示すべきではありません。

オブジェクトが重なり合っている状況では、このメソッドは完全に表示されている最大の矩形を返す必要があります。

このメソッドは、点または矩形領域が表示されているか、重なり合うオブジェクトによって隠れているかを判断するためにも使用できます。

オブジェクトに渡されたすべてのメッセージに対するデフォルト処理を呼び出します。

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

Return code	Description
S_FALSE	ウィンドウメッセージに対するコンテナーのデフォルト処理は呼び出されませんでした。後述の「実装者への注意」を参照してください。

ウィンドウレスオブジェクトは、このメソッドを呼び出すことにより、ウィンドウメッセージに対するデフォルト処理を明示的に呼び出すことができます。コンテナーは、IOleInPlaceObjectWindowless::OnWindowMessage を呼び出すことにより、ウィンドウメッセージをウィンドウレスオブジェクトにディスパッチします。オブジェクトは通常、メッセージを処理しなかったことを示すために S_FALSE を返します。その場合、コンテナーは DefWindowProc 関数を呼び出すことにより、メッセージのデフォルト動作を実行できます。

代わりに、オブジェクトはコンテナーのサイトオブジェクト上でこのメソッドを呼び出して、デフォルト処理を明示的に呼び出すことができます。その後、オブジェクトは、コンテナーがメッセージを処理しない場合に自身でアクションを実行できます。

実装者への注意

コンテナーは、次のウィンドウメッセージをデフォルトのウィンドウプロシージャ(DefWindowProc 関数)に渡し、S_OK を返す必要があります。*plResult には DefWindowProc によって返された値が含まれている必要があることに注意してください。

• WM_CHAR
• WM_DEADCHAR
• WM_IMExxx
• WM_KEYDOWN
• WM_KEYUP
• WM_MOUSEMOVE
• WM_SYSCHAR
• WM_SYSDEADCHAR
• WM_SYSKEYUP
• WM_XBUTTONDOWN
• WM_XBUTTONUP
• WM_XBUTTONDBLCLK

コンテナーは、次のウィンドウメッセージを自身のものとして処理して S_OK を返すか、何もせずに S_FALSE を返すことができます。

• WM_CONTEXTMENU
• WM_HELP
• WM_SETCURSOR

コンテナーが S_FALSE を返す場合、オブジェクトは自身でウィンドウメッセージを処理するアクションを実行できます。

#define global IID_IOleInPlaceSiteWindowless "{922EADA0-3424-11CF-B670-00AA004CD6D8}"
#usecom global IOleInPlaceSiteWindowless IID_IOleInPlaceSiteWindowless "{}"
#comfunc global IOleInPlaceSiteWindowless_CanWindowlessActivate  18
#comfunc global IOleInPlaceSiteWindowless_GetCapture             19
#comfunc global IOleInPlaceSiteWindowless_SetCapture             20 int
#comfunc global IOleInPlaceSiteWindowless_GetFocus               21
#comfunc global IOleInPlaceSiteWindowless_SetFocus               22 int
#comfunc global IOleInPlaceSiteWindowless_GetDC                  23 var,int,sptr
#comfunc global IOleInPlaceSiteWindowless_ReleaseDC              24 sptr
#comfunc global IOleInPlaceSiteWindowless_InvalidateRect         25 var,int
#comfunc global IOleInPlaceSiteWindowless_InvalidateRgn          26 sptr,int
#comfunc global IOleInPlaceSiteWindowless_ScrollRect             27 int,int,var,var
#comfunc global IOleInPlaceSiteWindowless_AdjustRect             28 var
#comfunc global IOleInPlaceSiteWindowless_OnDefWindowMessage     29 int,sptr,sptr,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。