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 provides sizing hints from the container for the object to use as the user resizes it.

Syntax

HRESULT GetNaturalExtent(
  DWORD 
dwAspect,
  LONG 
lindex,
  DVTARGETDEVICE* 
ptd,
  HDC 
hicTargetDev,
  DVEXTENTINFO* 
pExtentInfo,
  LPSIZEL 
pSizel
);

Parameters

dwAspect

[in] Requested drawing aspect. It can be any of the values from the DVASPECTenumeration.

lindex

[in] Portion of the object that is of interest for the draw operation. Its interpretation varies depending on the value in the dwAspectparameter. See the DVASPECTenumeration for more information.

ptd

[in] Pointer 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 the hicTargetDevand hdcDrawparameters.

For example, if hdcDrawspecifies a printer as the device context, the ptdparameter points to a structure describing that printer device. The data can actually be printed if hicTargetDevis a valid value or it can 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.

pExtentInfo

[in] Pointer to DVEXTENTINFOstructure that specifies the sizing data.

pSizel

[out] Pointer to sizing data returned by the object.

The returned sizing data is set to -1 for any dimension that was not adjusted.

That is, if cx is –1, the width was not adjusted; if cy is –1, the height was not adjusted.

If E_FAIL is returned indicating no size was adjusted, pSizelmay be NULL.

Return Value

The following table shows the return values for this method.

Value Description

S_OK

The sizing hints were successfully returned.

E_FAIL

This method is not implemented for the specified dwAspect, or the size was not adjusted.

E_NOTIMPL

This method is not implemented.

Remarks

There are two general approaches to sizing a control.

The first approach gives the control responsibility for sizing itself; the second approach gives the container responsibility for sizing the control. The first approach is called autosizing.

There are two alternatives involved in the second approach: content sizing and integral sizing.

The IViewObjectEx::GetNaturalExtentmethod supports both content and integral sizing.

In content sizing, the container passes the DVEXTENTINFOstructure to the object into which the object returns a suggested size.

In integral sizing, the container passes a preferred size to the object in DVEXTENTINFOand the object actually adjusts its height. Integral sizing is used when the user rubberbands a new size in design mode.

Autosizing typically occurs with objects such as the Label control, which resizes if the autosize property was enabled and the associated text changed. Autosizing is handled differently depending on the state of the object.

If the object is inactive, the following occurs:

  1. The object calls the IOleClientSite::RequestNewObjectLayoutmethod.

  2. The container calls the IOleObject::GetExtentmethod and retrieves the new extents.

  3. The container calls the IOleObject::SetExtentmethod and adjusts the new extents.

If the object is active, the following occurs:

  1. The object calls the IOleInPlaceSite::OnPosRectChangemethod to specify that it requires resizing.

  2. The container calls the IOleInPlaceObject::SetObjectRectsmethod and specifies the new size.

The following table shows the possible values for the dwAspectparameter.

Value Description

DVASPECT_CONTENT

Provide a representation of the control so it can be displayed as an embedded object inside of a container.

This value is typically specified for compound document objects.

The presentation can be provided for the screen or printer.

DVASPECT_DOCPRINT

Provide a representation of the control on the screen as though it were printed to a printer using the Printcommand from the Filemenu.

The described data can represent a sequence of pages.

DVASPECT_ICON

Provide an iconic representation of the control.

DVASPECT_THUMBNAIL

Provide a thumbnail representation of an object so it can be displayed in a browsing tool.

The thumbnail is approximately a 120 by 120 pixel, 16-color (recommended) device-independent bitmap potentially wrapped in a metafile.

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

Requirements

Header ocidl.h, ocidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also