Share via

CPropExchange Class

  • Article

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CPropExchange Class.

Supports the implementation of persistence for your OLE controls.

Syntax

class AFX_NOVTABLE CPropExchange

Members

Public Methods

Name Description
CPropExchange::ExchangeBlobProp Exchanges a binary large object (BLOB) property.
CPropExchange::ExchangeFontProp Exchanges a font property.
CPropExchange::ExchangePersistentProp Exchanges a property between a control and a file.
CPropExchange::ExchangeProp Exchanges properties of any built-in type.
CPropExchange::ExchangeVersion Exchanges the version number of an OLE control.
CPropExchange::GetVersion Retrieves the version number of an OLE control.
CPropExchange::IsAsynchronous Determines if property exchanges are done asynchronously.
CPropExchange::IsLoading Indicates whether properties are being loaded into the control or saved from it.

Remarks

CPropExchange does not have a base class.

Establishes the context and direction of a property exchange.

Persistence is the exchange of the control's state information, usually represented by its properties, between the control itself and a medium.

The framework constructs an object derived from CPropExchange when it is notified that an OLE control's properties are to be loaded from or stored to persistent storage.

The framework passes a pointer to this CPropExchange object to your control's DoPropExchange function. If you used a wizard to create the starter files for your control, your control's DoPropExchange function calls COleControl::DoPropExchange. The base-class version exchanges the control's stock properties; you modify your derived class's version to exchange properties you have added to your control.

CPropExchange can be used to serialize a control's properties or initialize a control's properties upon the load or creation of a control. The ExchangeProp and ExchangeFontProp member functions of CPropExchange are able to store properties to and load them from different media.

For more information on using CPropExchange, see the article MFC ActiveX Controls: Property Pages.

Inheritance Hierarchy

CPropExchange

Requirements

Header: afxctl.h

CPropExchange::ExchangeBlobProp

Serializes a property that stores binary large object (BLOB) data.

virtual BOOL ExchangeBlobProp(
    LPCTSTR pszPropName,  
    HGLOBAL* phBlob,  
    HGLOBAL hBlobDefault = NULL) = 0;

Parameters

pszPropName
The name of the property being exchanged.

phBlob
Pointer to a variable pointing to where the property is stored (variable is typically a member of your class).

hBlobDefault
Default value for the property.

Return Value

Nonzero if the exchange was successful; 0 if unsuccessful.

Remarks

The property's value is read from or written to, as appropriate, the variable referenced by phBlob. If hBlobDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization fails.

The functions CArchivePropExchange::ExchangeBlobProp, CResetPropExchange::ExchangeBlobProp, and CPropsetPropExchange::ExchangeBlobProp override this pure virtual function.

CPropExchange::ExchangeFontProp

Exchanges a font property between a storage medium and the control.

virtual BOOL ExchangeFontProp(
    LPCTSTR pszPropName,  
    CFontHolder& font,  
    const FONTDESC* pFontDesc,  
    LPFONTDISP pFontDispAmbient) = 0;

Parameters

pszPropName
The name of the property being exchanged.

font
A reference to a CFontHolder object that contains the font property.

pFontDesc
A pointer to a FONTDESC structure containing values for initializing the default state of the font property when pFontDispAmbient is NULL.

pFontDispAmbient
A pointer to the IFontDisp interface of a font to be used for initializing the default state of the font property.

Return Value

Nonzero if the exchange was successful; 0 if unsuccessful.

Remarks

If the font property is being loaded from the medium to the control, the font's characteristics are retrieved from the medium and the CFontHolder object referenced by font is initialized with them. If the font property is being stored, the characteristics in the font object are written to the medium.

The functions CArchivePropExchange::ExchangeFontProp, CResetPropExchange::ExchangeFontProp, and CPropsetPropExchange::ExchangeFontProp override this pure virtual function.

CPropExchange::ExchangePersistentProp

Exchanges a property between the control and a file.

virtual BOOL ExchangePersistentProp(
    LPCTSTR pszPropName,  
    LPUNKNOWN* ppUnk,  
    REFIID iid,  
    LPUNKNOWN pUnkDefault) = 0;

Parameters

pszPropName
The name of the property being exchanged.

ppUnk
A pointer to a variable containing a pointer to the property's IUnknown interface (this variable is typically a member of your class).

iid
Interface ID of the interface on the property that the control will use.

pUnkDefault
Default value for the property.

Return Value

Nonzero if the exchange was successful; 0 if unsuccessful.

Remarks

If the property is being loaded from the file to the control, the property is created and initialized from the file. If the property is being stored, its value is written to the file.

The functions CArchivePropExchange::ExchangePersistentProp, CResetPropExchange::ExchangePersistentProp, and CPropsetPropExchange::ExchangePersistentProp override this pure virtual function.

CPropExchange::ExchangeProp

Exchanges a property between a storage medium and the control.

virtual BOOL ExchangeProp(
    LPCTSTR pszPropName,  
    VARTYPE vtProp,  
    void* pvProp,  
    const void* pvDefault = NULL) = 0 ;

Parameters

pszPropName
The name of the property being exchanged.

vtProp
A symbol specifying the type of the property being exchanged. Possible values are:

Symbol Property Type
VT_I2 short
VT_I4 long
VT_BOOL BOOL
VT_BSTR CString
VT_CY CY
VT_R4 float
VT_R8 double

pvProp
A pointer to the property's value.

pvDefault
Pointer to a default value for the property.

Return Value

Nonzero if the exchange was successful; 0 if unsuccessful.

Remarks

If the property is being loaded from the medium to the control, the property's value is retrieved from the medium and stored in the object pointed to by pvProp. If the property is being stored to the medium, the value of the object pointed to by pvProp is written to the medium.

The functions CArchivePropExchange::ExchangeProp, CResetPropExchange::ExchangeProp, and CPropsetPropExchange::ExchangeProp override this pure virtual function.

CPropExchange::ExchangeVersion

Called by the framework to handle persistence of a version number.

virtual BOOL ExchangeVersion(
    DWORD& dwVersionLoaded,  
    DWORD dwVersionDefault,  
    BOOL bConvert);

Parameters

dwVersionLoaded
Reference to a variable where the version number of the persistent data being loaded will be stored.

dwVersionDefault
The current version number of the control.

bConvert
Indicates whether to convert persistent data to the current version or keep it at the same version that was loaded.

Return Value

Nonzero if the function succeeded; 0 otherwise.

CPropExchange::GetVersion

Call this function to retrieve the version number of the control.

DWORD GetVersion();

Return Value

The version number of the control.

CPropExchange::IsAsynchronous

Determines if property exchanges are done asynchronously.

BOOL IsAsynchronous();

Return Value

Returns TRUE if properties are exchanged asynchronously, otherwise FALSE.

CPropExchange::IsLoading

Call this function to determine whether properties are being loaded to the control or saved from it.

BOOL IsLoading();

Return Value

Nonzero if properties are being loaded; otherwise 0.

See Also

Hierarchy Chart
COleControl::DoPropExchange