IViewObject::Freeze

Article
06/30/2006

This method freezes a certain aspect of the objects presentation so that it does not change until the IViewObject::Unfreeze method is called.

HRESULT Freeze( 
DWORD dwAspect, 
LONG lindex, 
void *pvAspect, 
DWORD *pdwFreeze);

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.
lindex
[in] Portion of the object that is of interest for the draw operation. Its interpretation varies with dwAspect. For more information, see the DVASPECT enumeration.
pvAspect
[in] Pointer to additional information about the view of the object specified in dwAspect. Because 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

One of the values described in the following table is returned.

Value	Description
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.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Oleidl.h

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

DVASPECT

Last updated on Tuesday, July 13, 2004

IViewObject::Freeze

Additional resources