Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method draws a representation of an object onto the specified device context.

Syntax 

HRESULT Draw( 
  DWORD 
dwAspect, 
  LONG 
lindex, 
  void* 
pvAspect, 
  DVTARGETDEVICE* 
ptd, 
  HDC 
hicTargetDev, 
  HDC 
hdcDraw, 
  const LPRECTL 
lprcBounds, 
  const LPRECTL 
lprcWBounds, 
  BOOL (*) (DWORD) 
pfnContinue, 
  DWORD 
dwContinue
);

Parameters

dwAspect

[in] Specifies the aspect to be drawn, that is, 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.

Windowless objects allow only DVASPECT_CONTENT, DVASPECT_OPAQUE, and DVASPECT_TRANSPARENT.

lindex

[in] Portion of the object that is of interest for the draw operation.

Its interpretation varies depending on the value in the dwAspectparameter. For more information, see the DVASPECTenumeration.

pvAspect

[in] Pointer to additional information in a DVASPECTINFOstructure that enables drawing optimizations depending on the aspect specified.

Newer objects and containers that support optimized drawing interfaces support this parameter.

Older objects and containers that do not support optimized drawing interfaces always specify NULL for this parameter.

ptd

[in] Pointer to the DVTARGETDEVICEstructure that describes the device that the object is to be rendered for.

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 hicTargetDevand hdcDraw. For example, if hdcDrawspecifies a printer as the device context, the ptdparameter points to a structure describing that printer device.

The data might actually be printed if hicTargetDevis a valid value or it might be displayed in print preview mode if hicTargetDevis NULL.

hicTargetDev

[in] Information context for the target device indicated by the ptdparameter from which the object can extract device metrics and test the device's capabilities.

If ptdis NULL, the object should ignore the value in the hicTargetDevparameter.

hdcDraw

[in] Device context on which to draw.

For a windowless object, do the following:

  • The hdcDrawparameter should be in MM_TEXT mapping mode with its logical coordinates matching the client coordinates of the containing window.

  • The device context should be in the same state as the one normally passed by a WM_PAINT message.

lprcBounds

[in] Long pointer to a RECTLstructure that specifies the rectangle on hdcDrawand in which the object should be drawn.

This parameter controls the positioning and stretching of the object.

This parameter should be NULL to draw a windowless in-place active object. In every other situation, NULL is not a legal value and should result in an E_INVALIDARG error code.

If the container passes a non-NULL value to a windowless object, the object should render the requested aspect into the specified device context and rectangle.

A container can request this from a windowless object to render a second, nonactive view of the object or to print the object.

lprcWBounds

[in] If hdcDrawis a metafile device context, this parameter is a long pointer to a RECTLstructure 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 lprcBoundsis nested inside this lprcWBoundsrectangle; they are in the same coordinate space.

If hdcDrawis not a metafile device context; lprcWBoundswill be NULL.

pfnContinue

[in] Pointer 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 Drawreturns DRAW_E_ABORT.

dwContinue

[in] Specifies a value to pass as a parameter to the function pointed to by the pfnContinueparameter.

Typically, dwContinueis a pointer to an application-defined structure needed inside the callback function.

Return Value

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the values described in the following table.

Value Description

S_OK

The object was drawn successfully.

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.

Remarks

A container application issues a call to Drawto create a representation of a contained object. This method draws the specified piece ( lindex) of the specified view ( dwAspectand 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 ptdparameter.

There is a relationship between the dwDrawAspectvalue and the lprcboundsvalue. The lprcboundsvalue specifies the rectangle on hdcDrawinto 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 the aspect ratio. In addition, some might scale so the drawing appears at full width, but the bottom is cropped.

The container can use IOleObject::SetExtentto suggest a size, but it has no control over the rendering size. In the case of DVASPECT_CONTENT, the Drawimplementation should either use the extents given by SetExtentor use the bounding rectangle given in the lprcBoundsparameter.

To maintain compatibility with older objects and containers that do not support drawing optimizations, all objects, rectangular or not, are required to maintain an origin and a rectangular extent.

This allows the container to still consider all its embedded objects as rectangles and to pass them appropriate rendering rectangles in Draw.

An object's extent depends on the drawing aspect. For nonrectangular objects, the extent should be the size of a rectangle covering the entire aspect.

By convention, the origin of an object is the top left corner of the rectangle of the DVASPECT_CONTENT aspect.

In other words, the origin always coincides with the top left corner of the rectangle maintained by the object's site, even for a nonrectangular object.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Note to Callers

The value of hicTargetDeviceis typically an information context for the target device. However, it can be a full device context.

Note to Implementers

If you are writing an object handler (such as the default handler) that implements Drawby playing a metafile, you must treat SetPaletteEntriesmetafile records in a special way because of the Windows behavior.

The Windows function PlayMetaFilesets these palette entries to the foreground. You must override this default by setting them to the background palette. Use EnumMetaFileto do this. Enhanced metafiles are always recorded with the background palette so there is no need to do it manually.

Requirements

Header Oleidl.h, oleidl.idl
Library oleaut32.lib, uuid.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also