IViewObject::Freeze
Freezes a
certain aspect of the object s presentation
so that it does not change until the IViewObject::Unfreeze method is called. The most
common use of this method is for banded printing.
HRESULT Freeze(
|
DWORD dwAspect, |
//How the
object is to be represented |
|
LONG lindex, |
//Part of
the object of interest in the draw operation |
|
void * pvAspect, |
//Always
NULL |
|
DWORD * pdwFreeze |
//Points to
location containing an identifying key |
|
); |
|
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] Portion
of the object that is of interest for the draw operation. Its interpretation
varies with dwAspect. See the DVASPECT enumeration for more
information.
pvAspect
[in] Pointer
to additional information about the view of the object specified in dwAspect.
Since none of the current aspects support additional information, pvAspect
must always be NULL.
pdwFreeze
[out] Pointer
to where an identifying DWORD key is returned. This unique key is later used to
cancel the freeze by calling IViewObject::Unfreeze. This key is an index that
the default cache uses to keep track of which object is frozen.
Return Values
S_OK
The
presentation was successfully frozen.
VIEW_S_ALREADYFROZEN
Presentation
has already been frozen. The value of pdwFreeze is the identifying key
of the already frozen object.
OLE_E_BLANK
Presentation
not in cache.
DV_E_LINDEX
Invalid value
for lindex; currently; only -1 is supported.
DV_E_DVASPECT
Invalid value
for dwAspect.
Remarks
The IViewObject::Freeze
method causes the view object to freeze its drawn representation until a
subsequent call to IViewObject::Unfreeze releases it. After calling IViewObject::Freeze,
successive calls to IViewObject::Draw with the same parameters produce the same
picture until IViewObject::Unfreeze is called.
IViewObject::Freeze is not part of the persistent state of the object and
does not continue across unloads and reloads of the object.
The most
common use of this method is for banded printing.
While in a
frozen state, view notifications are not sent. Pending view notifications are
deferred to the subsequent call to IViewObject::Unfreeze.
See Also