IViewObject::Draw - OLE Programmer's Reference (ole.hlp)

IViewObject::Draw

Draws a representation of an object onto the specified device context.

HRESULT Draw(

DWORD dwAspect,	//Specifies how the object is to be represented
LONG lindex,	//Specifies the part of the object to draw
void * pvAspect,	//Always NULL
DVTARGETDEVICE * ptd,	//Specifies the target device in a structure
HDC hicTargetDev,	//Specifies the information context for the target device ptd
HDC hdcDraw,	//Identifies the device context on which to draw
const LPRECTL lprcBounds,	//Specifies the rectangle in which the object is drawn
const LPRECTL lprcWBounds,	//Specifies the window extent and window origin when drawing a metafile
*BOOL () (DWORD)** pfnContinue,	//Callback function for canceling or continuing the drawing
DWORD dwContinue	//Parameter to pass to the callback function pfnContinue
);

Parameters
dwAspect

[in]Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information.

lindex

[in]Indicates the portion of the object that is of interest for the draw operation. Its interpretation varies depending on the value in the dwAspect parameter. See the DVASPECT enumeration for more information.

pvAspect

[in]Provides more information about the view of the object specified in dwAspect. Since none of the current aspects support additional information; pvAspect must always be NULL.

ptd

[in]Points to the target device structure that describes the device for which the object is to be rendered. If NULL, the view should be rendered for the default target device (typically the display). A value other than NULL is interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, the ptd parameter points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value or it may be displayed in print preview mode if hicTargetDev is NULL.

hicTargetDev

[in]Specifies the information context for the target device indicated by the ptd parameter from which the object can extract device metrics and test the device's capabilities. If ptd is NULL; the object should ignore the value in the hicTargetDev parameter.

hdcDraw

[in]Specifies the device context on which to draw.

lprcBounds

[in]Points to a RECTL structure specifying the rectangle on hdcDraw and in which the object should be drawn. This parameter controls the positioning and stretching of the object.

lprcWBounds

[in]If hdcDraw is a metafile device context, the lprcWBounds parameter points to a RECTL structure specifying the bounding rectangle in the underlying metafile. The rectangle structure contains the window extent and window origin. These values are useful for drawing metafiles. The rectangle indicated by lprcBounds is nested inside this lprcWBounds rectangle; they are in the same coordinate space.

If hdcDraw is not a metafile device context; lprcWBounds will be NULL.

pfnContinue

[in]Points to a callback function that the view object should call periodically during a lengthy drawing operation to determine whether the operation should continue or be canceled. This function returns TRUE to continue drawing. It returns FALSE to stop the drawing in which case IViewObject::Draw returns DRAW_E_ABORT.

dwContinue

[in]Contains a value to pass as a parameter to the function pointed to by the pfnContinue parameter. Typically, dwContinue is a pointer to an application-defined structure needed inside the callback function.

Return Values
S_OK

The object was drawn successfully.

E_INVALIDARG

Invalid window boundaries specified for metafile device context.

E_OUTOFMEMORY

Ran out of memory.

OLE_E_BLANK

No data to draw from.

DRAW_E_ABORT

Draw operation aborted.

VIEW_E_DRAW

Error in drawing.

DV_E_LINDEX

Invalid value for lindex; currently only -1 is supported.

DV_E_DVASPECT

Invalid value for dwAspect.

OLE_E_INVALIDRECT

Invalid rectangle.

Comments
A container application issues a call to IViewObject::Draw to create a representation of a contained object. This method draws the specified piece (lindex) of the specified view (dwAspect and pvAspect) on the specified device context (hdcDraw). Formatting, fonts, and other rendering decisions are made on the basis of the target device specified by the ptd parameter.

There is a relationship between the dwDrawAspect value and lprcbounds value. The lprcbounds value specifies the rectangle on hdcDraw into which the drawing is to be mapped. For DVASPECT_THUMBNAIL, DVASPECT_ICON, and DVASPECT_SMALLICON, the object draws whatever it wants to draw, and it maps it into the space given in the best way. Some objects might scale to fit while some might scale to fit but preserve aspect ratio. In addition; some might scale so the drawing appears at full width; but the bottom is cropped. The container can suggest a size via IOleObject::SetExtent, but it has no control over the rendering size. In the case of DVASPECT_CONTENT, the Draw implementation should either use the extents given by IOleObject::SetExtent or use the bounding rectangle given in the lprcBounds parameter.

Note to Callers
The value of hicTargetDevice is typically an information context for the target device. However, it may be a full device context instead.

Note to Implementors
If you are writing an object handler (such as the default handler) that implements IViewObject::Draw by playing a metafile, you have to treat SetPaletteEntries metafile records in a special way because of Windows' behavior. The Windows function PlayMetaFile sets these palette entries to the foreground. You must override this default by setting them to the background palette. Use EnumMetaFile to do this. Enhanced metafiles are always recorded with the background palette so there is no need to do it manually.