IOleObject::SetExtent
Informs an
object of how much display space its container has assigned it.
HRESULT SetExtent(
|
DWORD dwDrawAspect, |
//DVASPECT value |
|
SIZEL *psizel |
//Pointer to size limit for object |
|
); |
|
Parameters
dwDrawAspect
[in] DWORD
that describes which form, or aspect, of an object is to be displayed. The
object s container obtains this value from the enumeration DVASPECT (refer to the FORMATETC enumeration). The most
common aspect is DVASPECT_CONTENT, which specifies a full rendering of the
object within its container. An object can also be rendered as an icon, a
thumbnail version for display in a browsing tool, or a print version, which
displays the object as it would be rendered using the File Print command.
psizel
[in] Pointer
to the size limit for the object.
Return Values
This method
supports the standard return value E_FAIL, as well as the following:
S_OK
The object
has resized successfully.
OLE_E_NOTRUNNING
The object is
not running.
Remarks
A container
calls IOleObject::SetExtent when it needs to dictate to an embedded
object the size at which it will be displayed. Often, this call occurs in
response to an end user resizing the object window. Upon receiving the call, the
object, if possible, should recompose itself gracefully to fit the new window.
Whenever
possible, a container seeks to display an object at its finest resolution,
sometimes called the object s native size. All objects, however, have a
default display size specified by their applications, and in the absence of
other constraints, this is the size they will use to display themselves. Since
an object knows its optimum display size better than does its container, the
latter normally requests that size from a running object by calling IOleObject::GetExtent. Only in cases where the
container cannot accommodate the value returned by the object does it override
the object s preference by calling IOleObject::SetExtent.
Notes to Callers
You can call SetExtent
on an object only when the object is running. If a container resizes an object
while an object is not running, the container should keep track of the object s
new size but defer calling IOleObject::SetExtent until a user activates
the object. If the OLEMISC_RECOMPOSEONRESIZE bit is set on an object, its
container should force the object to run before calling OleObject::SetExtent.
As noted
above, a container may want to delegate responsibility for setting the size of
an object s display site to the object itself, by calling IOleObject::GetExtent.
Notes to Implementers
You may want
to implement this method so that your object rescales itself to match as
closely as possible the maximum space available to it in its container.
If an
object s size is fixed, that is, if it cannot be set by its container, OleObject::SetExtent
should return E_FAIL. This is always the case with linked objects, whose sizes
are set by their link sources, not by their containers.
See Also