IViewObject：:D raw 方法 (oleidl.h)

發行項
03/05/2024

將物件的表示法繪製到指定的裝置內容上。

語法

HRESULT Draw(
  [in] DWORD                          dwDrawAspect,
  [in] LONG                           lindex,
  [in] void                           *pvAspect,
  [in] DVTARGETDEVICE                 *ptd,
  [in] HDC                            hdcTargetDev,
  [in] HDC                            hdcDraw,
  [in] LPCRECTL                       lprcBounds,
  [in] LPCRECTL                       lprcWBounds,
  [in] BOOL(* )(ULONG_PTR dwContinue) pfnContinue,
  [in] ULONG_PTR                      dwContinue
);

參數

[in] dwDrawAspect

指定要繪製的外觀，亦即，如何表示該物件。表示法包括內容、圖示、縮圖或列印檔。有效值取自 DVASPECT 列舉和 DVASPECT2。請注意，支援優化繪圖介面的新物件和容器支援 DVASPECT2 列舉值。不支援優化繪圖介面的較舊物件和容器可能不支援 DVASPECT2。無視窗物件只允許 DVASPECT_CONTENT、 DVASPECT_OPAQUE和 DVASPECT_TRANSPARENT。

[in] lindex

想要進行繪製作業的物件部分。其解譯會根據 dwAspect 參數中的值而有所不同。如需詳細資訊，請參閱 DVASPECT 列舉。

[in] pvAspect

DVASPECTINFO 結構中其他資訊的指標，可根據指定的層面啟用繪圖優化。請注意，支援優化繪圖介面的新物件和容器也支援此參數。不支援優化繪圖介面的較舊物件和容器一律為此參數指定 NULL 。

[in] ptd

DVTARGETDEVICE 結構的指標，描述要呈現對象的裝置。如果為 NULL，則應該轉譯預設目標裝置的檢視， (通常是顯示) 。 NULL 以外的值會與 hdcTargetDev 和 hdcDraw 一起解譯。例如，如果 hdcDraw 將印表機指定為裝置內容， ptd 參數會指向描述該印表機裝置的結構。如果 hdcTargetDev 是有效的值，或如果 hdcTargetDev 是 NULL，則數據可能會實際列印在列印預覽模式中。

[in] hdcTargetDev

由 ptd 參數指出的目標裝置資訊內容，物件可以從中擷取裝置計量並測試裝置的功能。如果 ptd 為 NULL;對象應該忽略 hdcTargetDev 參數中的值。

[in] hdcDraw

要繪製的裝置內容。對於無視窗物件， hdcDraw 參數應該處於MM_TEXT對應模式，且其邏輯座標符合包含視窗的用戶端座標。對於無視窗對象，裝置內容的狀態應該與一般由WM_PAINT訊息傳遞的狀態相同。

[in] lprcBounds

RECTL 結構的指標，指定 hdcDraw 上應該繪製物件的矩形。此參數會控制物件的位置和延展。此參數應該是 NULL ，以繪製無視窗就地使用中物件。在其他情況下， NULL 不是合法的值，因此應該會產生E_INVALIDARG錯誤碼。如果容器將非 NULL 值傳遞至無視窗物件，對象應該會將要求的層面轉譯成指定的裝置內容和矩形。容器可以從無窗口物件要求此專案，以轉譯物件的第二個非使用中檢視，或列印物件。

[in] lprcWBounds

如果 hdcDraw 是元檔裝置內容，則指向 RECTL 結構的指標，以指定基礎元檔中的周框。矩形結構包含視窗範圍和視窗原點。這些值適用於繪製元檔。 lprcBounds 所指示的矩形會巢狀於這個 lprcWBounds 矩形內;它們位於相同的座標空間中。

如果 hdcDraw 不是元文件裝置內容; lprcWBounds 將會是 NULL。

[in] pfnContinue

回呼函式的指標，檢視物件應該於耗時繪製作業期間定期呼叫該函式，以判斷應該繼續還是取消作業。此函式會傳回 TRUE 以繼續繪製。它會傳回 FALSE 來停止繪圖，在此情況下 ，IViewObject：:D raw 會傳回DRAW_E_ABORT。

dwContinue

[in] dwContinue

要當做參數傳遞至 pfnContinue 參數所指向之函式的值。一般而言， dwContinue 是回呼函式內所需應用程式定義結構的指標。

傳回值

此方法會在成功時傳回S_OK。其他可能的傳回值包括下列專案。

傳回碼	Description
OLE_E_BLANK	沒有要從中繪製的數據。
DRAW_E_ABORT	繪製作業已中止。
VIEW_E_DRAW	繪圖時發生錯誤。
DV_E_LINDEX	lindex 的值無效;目前僅支援 -1。
DV_E_DVASPECT	dwAspect 的值無效。
OLE_E_INVALIDRECT	無效的矩形。

備註

容器應用程式發出 IViewObject：:D raw 的呼叫，以建立自主物件的表示法。這個方法會在指定的裝置內容 (hdcDraw) 上繪製指定檢視 (dwAspect 和 pvAspect) 的指定檢視 (lindex) 。格式化、字型和其他轉譯決策是根據 ptd 參數所指定的目標裝置進行。

dwDrawAspect 值與 lprcbounds 值之間有關聯性。 lprcbounds 值會指定要對應繪圖之 hdcDraw 上的矩形。針對 DVASPECT_THUMBNAIL、DVASPECT_ICON和 DVASPECT_SMALLICON，對象會繪製想要繪製的任何專案，並以最佳方式將它對應到指定的空間。有些物件可能會調整成適合，有些物件可能會調整為符合大小，但會保留外觀比例。此外，有些可能會縮放，使繪圖以全角顯示，但底部會裁剪。容器可以透過 IOleObject：：SetExtent 來建議大小，但無法控制轉譯大小。在 DVASPECT_CONTENT的情況下， IViewObject：:D raw 實作應該使用 IOleObject：：SetExtent 所提供的範圍，或使用 lprcBounds 參數中指定的周框。

對於支援優化繪圖技術和無窗口物件的新物件，應該使用此方法，如下所示：

dwAspect 支援新的繪圖層面，如DVASPECT2中所定義。
pvAspect 參數可用來傳遞其他資訊，允許透過 DVASPECTINFO 結構進行繪圖優化。
您可以呼叫 IViewObject：:D raw 方法，將 lrpcBounds 參數設定為 NULL，以重新繪製無視窗就地使用中物件。在其他情況下， NULL 是不合法的值，因此應該會產生E_INVALIDARG錯誤碼。無窗口物件會使用啟用動詞所傳遞的矩形，或呼叫 IOleInPlaceObject：：SetObjectRects ，而不是使用此參數。如果容器將非 NULL 值傳遞至無視窗物件，對象應該會將要求的層面轉譯成指定的裝置內容和矩形。容器可以從無窗口物件要求此專案，以轉譯物件的第二個非使用中檢視，或列印物件。如需繪製無視窗對象的詳細資訊，請參閱 IOleInPlaceSiteWindowless 介面。
對於無窗口物件，dwAspect 參數只允許 DVASPECT_CONTENT、DVASPECT_OPAQUE和 DVASPECT_TRANSPARENT層面。
對於無窗口物件，hdcDraw 參數應該處於MM_TEXT對應模式，其邏輯座標符合包含視窗的用戶端座標。對於無視窗對象，裝置內容的狀態應該與一般由WM_PAINT訊息傳遞的狀態相同。

為了維持與不支援繪圖優化之較舊物件和容器的相容性，必須保留原點和矩形範圍，所有物件、矩形都不需要。這可讓容器仍將其所有內嵌物件視為矩形，並在 Draw 中傳遞適當的轉譯矩形。

物件的範圍取決於繪圖層面。對於非矩形物件，範圍應該是涵蓋整個外觀的矩形大小。依照慣例，物件的原點是 DVASPECT_CONTENT外觀矩形的左上角。換句話說，原點一律會與物件月臺所維護的矩形左上角一致，即使是非矩形物件也一樣。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	oleidl.h