IViewObject

オブジェクトが、呼び出し側にデータオブジェクトを渡すことなく、自身を直接表示できるようにします。さらに、このインターフェイスはアドバイズシンクとの接続を作成および管理でき、これによって呼び出し側はビューオブジェクトの変更を通知されることができます。

オブジェクトの表現を指定されたデバイスコンテキストに描画します。

このメソッドは成功時に S_OK を返します。その他の可能な戻り値には以下があります。

Return code	Description
OLE_E_BLANK	描画するデータがありません。
DRAW_E_ABORT	描画操作が中止されました。
VIEW_E_DRAW	描画中のエラーです。
DV_E_LINDEX	lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_DVASPECT	dwAspect の値が無効です。
OLE_E_INVALIDRECT	矩形が無効です。

コンテナーアプリケーションは、含まれるオブジェクトの表現を作成するために IViewObject::Draw を呼び出します。このメソッドは、指定されたビュー(dwAspect および pvAspect)の指定された部分(lindex)を、指定されたデバイスコンテキスト(hdcDraw)に描画します。書式設定、フォント、その他のレンダリングに関する判断は、ptd パラメーターで指定されたターゲットデバイスに基づいて行われます。

dwDrawAspect の値と lprcbounds の値の間には関係があります。lprcbounds の値は、描画をマッピングする対象となる hdcDraw 上の矩形を指定します。DVASPECT_THUMBNAIL、DVASPECT_ICON、および DVASPECT_SMALLICON の場合、オブジェクトは描画したいものを描画し、それを与えられた空間に最良の方法でマッピングします。一部のオブジェクトはフィットするようにスケーリングし、一部はフィットさせつつアスペクト比を維持します。さらに、描画が全幅で表示されるようにスケーリングするが下部が切り取られるものもあります。コンテナーは IOleObject::SetExtent を介してサイズを提案できますが、レンダリングサイズを制御することはできません。DVASPECT_CONTENT の場合、IViewObject::Draw の実装は、IOleObject::SetExtent によって与えられた範囲を使用するか、lprcBounds パラメーターで与えられた境界矩形を使用する必要があります。

最適化された描画技術をサポートする新しいオブジェクトおよびウィンドウレスオブジェクトの場合、このメソッドは次のように使用する必要があります。

• DVASPECT2 で定義されている新しい描画アスペクトが dwAspect でサポートされます。
• pvAspect パラメーターを使用して、DVASPECTINFO 構造体を通じて描画の最適化を可能にする追加情報を渡すことができます。
• IViewObject::Draw メソッドは、lrpcBounds パラメーターを NULL に設定することで、ウィンドウレスのインプレースアクティブなオブジェクトを再描画するために呼び出すことができます。それ以外のすべての状況では、NULL は不正な値であり、E_INVALIDARG エラーコードを返す必要があります。ウィンドウレスオブジェクトは、このパラメーターを使用する代わりに、アクティブ化動詞によって渡された矩形を使用するか、IOleInPlaceObject::SetObjectRects を呼び出します。コンテナーがウィンドウレスオブジェクトに NULL 以外の値を渡した場合、オブジェクトは要求されたアスペクトを指定されたデバイスコンテキストおよび矩形にレンダリングする必要があります。コンテナーは、オブジェクトの2つ目の非アクティブなビューをレンダリングするため、またはオブジェクトを印刷するために、ウィンドウレスオブジェクトにこれを要求できます。ウィンドウレスオブジェクトの描画の詳細については、IOleInPlaceSiteWindowless インターフェイスを参照してください。
• ウィンドウレスオブジェクトの場合、dwAspect パラメーターでは DVASPECT_CONTENT、DVASPECT_OPAQUE、および DVASPECT_TRANSPARENT のアスペクトのみが許可されます。
• ウィンドウレスオブジェクトの場合、hdcDraw パラメーターは MM_TEXT マッピングモードであり、その論理座標が包含ウィンドウのクライアント座標に一致している必要があります。ウィンドウレスオブジェクトの場合、デバイスコンテキストは通常 WM_PAINT メッセージによって渡されるものと同じ状態である必要があります。

描画の最適化をサポートしない古いオブジェクトおよびコンテナーとの互換性を維持するため、すべてのオブジェクトは、矩形かどうかにかかわらず、原点と矩形の範囲を保持することが求められます。これにより、コンテナーは埋め込まれたすべてのオブジェクトを依然として矩形とみなし、Draw で適切なレンダリング矩形を渡すことができます。

オブジェクトの範囲は描画アスペクトによって異なります。矩形でないオブジェクトの場合、範囲はアスペクト全体を覆う矩形のサイズにする必要があります。慣例により、オブジェクトの原点は DVASPECT_CONTENT アスペクトの矩形の左上隅です。言い換えれば、原点は矩形でないオブジェクトであっても、常にオブジェクトのサイトが保持する矩形の左上隅と一致します。

IViewObject::Draw メソッドで、対応するパラメーターを用いて描画する際にオブジェクトが使用する論理パレットを返します。

このメソッドは成功時に S_OK を返します。その他の可能な戻り値には以下があります。

Return code	Description
S_FALSE	色のセットが空であるか、オブジェクトが情報を提供しません。
OLE_E_BLANK	オブジェクトのプレゼンテーションデータがありません。
DV_E_LINDEX	lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_DVASPECT	dwAspect の値が無効です。
E_INVALIDARG	指定されたパラメーター値の1つ以上が無効です。
E_OUTOFMEMORY	この操作に利用できるメモリが不足しています。

IViewObject::GetColorSet メソッドは、入れ子になったオブジェクトを再帰的に問い合わせ、要求されたすべての色の和集合を表す色のセットを返します。色のセットは最終的に、ウィンドウフレームを所有する最上位のコンテナーへと集約されます。このコンテナーは、埋め込まれた各オブジェクトに対して IViewObject::GetColorSet を呼び出すことで、埋め込みオブジェクトの描画に必要なすべての色を取得できます。コンテナーは、取得した色のセットを自身に必要なその他の色と組み合わせて使用し、全体の色パレットを設定できます。

OLE が提供する IViewObject::GetColorSet の実装は、絵を描画するために手元にあるデータを調べます。描画形式が CF_DIB の場合、ビットマップ内のパレットが使用されます。通常のビットマップの場合、色情報は返されません。描画形式がメタファイルの場合、オブジェクトハンドラーはメタファイルを列挙して CreatePalette メタファイルレコードを探します。見つかった場合、ハンドラーはそれを色のセットとして使用します。

オブジェクトの描画された表現を、IViewObject::Unfreeze メソッドが呼び出されるまで変化しないように固定します。このメソッドの最も一般的な用途はバンド印刷です。

このメソッドは成功時に S_OK を返します。その他の可能な戻り値には以下があります。

Return code	Description
VIEW_S_ALREADY_FROZEN	プレゼンテーションは既に固定されています。pdwFreeze の値は、既に固定されているオブジェクトの識別キーです。
OLE_E_BLANK	プレゼンテーションがキャッシュにありません。
DV_E_LINDEX	lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_DVASPECT	dwAspect の値が無効です。

IViewObject::Freeze メソッドは、後続の IViewObject::Unfreeze の呼び出しによって解放されるまで、ビューオブジェクトに描画された表現を固定させます。IViewObject::Freeze を呼び出した後は、同じパラメーターで IViewObject::Draw を連続して呼び出しても、IViewObject::Unfreeze が呼び出されるまで同じ絵が生成されます。

IViewObject::Freeze はオブジェクトの永続的な状態の一部ではなく、オブジェクトのアンロードおよび再読み込みをまたいで維持されることはありません。

このメソッドの最も一般的な用途はバンド印刷です。

固定状態の間、ビュー通知は送信されません。保留中のビュー通知は、後続の IViewObject::Unfreeze の呼び出しまで延期されます。

IViewObject::Freeze を使用して以前に固定された描画を解放します。このメソッドの最も一般的な用途はバンド印刷です。

このメソッドは成功時に S_OK を返します。その他の可能な戻り値には以下があります。

Return code	Description
OLE_E_NOCONNECTION	固定解除の処理中にエラーが発生したか、オブジェクトが現在固定されていません。

ビューオブジェクトとアドバイズシンクの間に接続を確立し、アドバイズシンクがオブジェクトのビューの変更について通知を受けられるようにします。

このメソッドは成功時に S_OK を返します。その他の可能な戻り値には以下があります。

Return code	Description
OLE_E_ADVISENOTSUPPORTED	アドバイザリ通知はサポートされていません。
DV_E_DVASPECT	dwAspect の値が無効です。
E_INVALIDARG	指定された値の1つ以上が無効です。
E_OUTOFMEMORY	この操作に利用できるメモリが不足しています。

ビューオブジェクトに対して描画操作を要求するコンテナーアプリケーションは、IViewObject::SetAdvise メソッドで登録することにより、ビューオブジェクトのプレゼンテーションが変化したときに通知を受けることもできます。オブジェクトの基になるデータがいつ変化するかを知るには、IDataObject::DAdvise を別途呼び出す必要があります。

既存のアドバイザリ接続を削除するには、pAdvSink を NULL に設定して IViewObject::SetAdvise メソッドを呼び出します。

ビューオブジェクトが変化すると、適切なアドバイズシンクの IAdviseSink::OnViewChange メソッドを通じて呼び出しが行われます。

任意の時点で、特定のビューオブジェクトがサポートできるアドバイザリ接続は1つだけです。したがって、IViewObject::SetAdvise が呼び出された時点でビューオブジェクトが既にアドバイズシンクポインターを保持している場合、OLE は新しいポインターが登録される前に既存のポインターを解放します。

直近の IViewObject::SetAdvise 呼び出しで使用された、オブジェクト上のアドバイザリ接続を取得します。

このメソッドは成功時に S_OK を返します。

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