Persistence of OLE Controls
One capability of OLE controls is property persistence (or serialization), which allows the OLE control to read or write property values to and from a file or stream. A container application can use serialization to store a control's property values even after the application has destroyed the control. The property values of the OLE control can then be read from the file or stream when a new instance of the control is created at a later time.
Persistence of OLE Controls
| Name | Description |
|---|---|
| PX_Blob | Exchanges a control property that stores binary large object (BLOB) data. |
| PX_Bool | Exchanges a control property of type BOOL. |
| PX_Color | Exchanges a color property of a control. |
| PX_Currency | Exchanges a control property of type CY. |
| PX_DataPath | Exchanges a control property of type CDataPathProperty. |
| PX_Double | Exchanges a control property of type double. |
| PX_Font | Exchanges a font property of a control. |
| PX_Float | Exchanges a control property of type float. |
| PX_IUnknown | Exchanges a control property of undefined type. |
| PX_Long | Exchanges a control property of type long. |
| PX_Picture | Exchanges a picture property of a control. |
| PX_Short | Exchanges a control property of type short. |
| PX_ULong | Exchanges a control property of type ULONG. |
| PX_UShort | Exchanges a control property of type USHORT. |
| PXstring | Exchanges a character string control property. |
| PX_VBXFontConvert | Exchanges a VBX control's font-related properties into an OLE control font property. |
In addition, the AfxOleTypeMatchGuid global function is provided to test for a match between a TYPEDESC and a given GUID.
PX_Blob
Call this function within your control's DoPropExchange member function to serialize or initialize a property that stores binary large object (BLOB) data.
BOOL PX_Blob(
CPropExchange* pPX,
LPCTSTR pszPropName,
HGLOBAL& hBlob,
HGLOBAL hBlobDefault = NULL);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
hBlob
Reference to the variable where the property is stored (typically a member variable 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 will be read from or written to the variable referenced by hBlob, as appropriate. This variable should be initialized to NULL before initially calling PX_Blob for the first time (typically, this can be done in the control's constructor). 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 initialization or serialization process fails.
The handles hBlob and hBlobDefault refer to a block of memory which contains the following:
A DWORD which contains the length, in bytes, of the binary data that follows, followed immediately by
A block of memory containing the actual binary data.
Note that PX_Blob will allocate memory, using the Windows GlobalAlloc API, when loading BLOB-type properties. You are responsible for freeing this memory. Therefore, the destructor of your control should call GlobalFree on any BLOB-type property handles to free up any memory allocated to your control.
PX_Bool
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type BOOL.
BOOL PX_Bool(
CPropExchange* pPX,
LPCTSTR pszPropName,
BOOL& bValue);
BOOL PX_Bool(
CPropExchange* pPX,
LPCTSTR pszPropName,
BOOL& bValue,
BOOL bDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
bValue
Reference to the variable where the property is stored (typically a member variable of your class).
bDefault
Default value for the property.
Return Value
Nonzero if the exchange was successful; 0 if unsuccessful.
Remarks
The property's value will be read from or written to the variable referenced by bValue, as appropriate. If bDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_Color
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type OLE_COLOR.
BOOL PX_Color(
CPropExchange* pPX,
LPCTSTR pszPropName,
OLE_COLOR& clrValue);
BOOL PX_Color(
CPropExchange* pPX,
LPCTSTR pszPropName,
OLE_COLOR& clrValue,
OLE_COLOR clrDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
clrValue
Reference to the variable where the property is stored (typically a member variable of your class).
clrDefault
Default value for the property, as defined by the control developer.
Return Value
Nonzero if the exchange was successful; 0 if unsuccessful.
Remarks
The property's value will be read from or written to the variable referenced by clrValue, as appropriate. If clrDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_Currency
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type currency.
BOOL PX_Currency(
CPropExchange* pPX,
LPCTSTR pszPropName,
CY& cyValue);
BOOL PX_Currency(
CPropExchange* pPX,
LPCTSTR pszPropName,
CY& cyValue,
CY cyDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
cyValue
Reference to the variable where the property is stored (typically a member variable of your class).
cyDefault
Default value for the property.
Return Value
Nonzero if the exchange was successful; 0 if unsuccessful.
Remarks
The property's value will be read from or written to the variable referenced by cyValue, as appropriate. If cyDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_DataPath
Call this function within your control's DoPropExchange member function to serialize or initialize a data path property of type CDataPathProperty.
BOOL PX_DataPath(
CPropExchange* pPX,
LPCTSTR pszPropName,
CDataPathProperty& dataPathProperty);
BOOL PX_DataPath(
CPropExchange* pPX,
CDataPathProperty& dataPathProperty);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
dataPathProperty
Reference to the variable where the property is stored (typically a member variable of your class).
Return Value
Nonzero if the exchange was successful; 0 if unsuccessful.
Remarks
Data path properties implement asynchronous control properties. The property's value will be read from or written to the variable referenced by dataPathProperty, as appropriate.
PX_Double
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type double.
BOOL PX_Double(
CPropExchange* pPX,
LPCTSTR pszPropName,
double& doubleValue);
BOOL PX_Double(
CPropExchange* pPX,
LPCTSTR pszPropName,
double& doubleValue,
double doubleDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
doubleValue
Reference to the variable where the property is stored (typically a member variable of your class).
doubleDefault
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 the variable referenced by doubleValue, as appropriate. If doubleDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_Font
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type font.
BOOL PX_Font(
CPropExchange* pPX,
LPCTSTR pszPropName,
CFontHolder& font,
const FONTDESC FAR* pFontDesc = NULL,
LPFONTDISP pFontDispAmbient = NULL);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
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 the values to use in initializing the default state of the font property, in the case where pFontDispAmbient is NULL.
pFontDispAmbient
A pointer to the IFontDisp interface of a font to use in initializing the default state of the font property.
Return Value
Nonzero if the exchange was successful; 0 if unsuccessful.
Remarks
The property's value is read from or written to font, a CFontHolder reference, when appropriate. If pFontDesc and pFontDispAmbient are specified, they are used for initializing the property's default value, when needed. These values are used if, for any reason, the control's serialization process fails. Typically, you pass NULL for pFontDesc and the ambient value returned by COleControl::AmbientFont for pFontDispAmbient. Note that the font object returned by COleControl::AmbientFont must be released by a call to the IFontDisp::Release member function.
PX_Float
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type float.
BOOL PX_Float(
CPropExchange* pPX,
LPCTSTR pszPropName,
float& floatValue);
BOOL PX_Float(
CPropExchange* pPX,
LPCTSTR pszPropName,
float& floatValue,
float floatDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
floatValue
Reference to the variable where the property is stored (typically a member variable of your class).
floatDefault
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 the variable referenced by floatValue, as appropriate. If floatDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_IUnknown
Call this function within your control's DoPropExchange member function to serialize or initialize a property represented by an object having an IUnknown-derived interface.
BOOL PX_IUnknown(
CPropExchange* pPX,
LPCTSTR pszPropName,
LPUNKNOWN& pUnk,
REFIID iid,
LPUNKNOWN pUnkDefault = NULL);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
pUnk
Reference to a variable containing the interface of the object that represents the value of the property.
iid
An interface ID indicating which interface of the property object is used by the control.
pUnkDefault
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 the variable referenced by pUnk, as appropriate. If pUnkDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_Long
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type long.
BOOL PX_Long(
CPropExchange* pPX,
LPCTSTR pszPropName,
long& lValue);
BOOL PX_Long(
CPropExchange* pPX,
LPCTSTR pszPropName,
long& lValue,
long lDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
lValue
Reference to the variable where the property is stored (typically a member variable of your class).
lDefault
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 the variable referenced by lValue, as appropriate. If lDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_Picture
Call this function within your control's DoPropExchange member function to serialize or initialize a picture property of your control.
BOOL PX_Picture(
CPropExchange* pPX,
LPCTSTR pszPropName,
CPictureHolder& pict);
BOOL PX_Picture(
CPropExchange* pPX,
LPCTSTR pszPropName,
CPictureHolder& pict,
CPictureHolder& pictDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
pict
Reference to a CPictureHolder object where the property is stored (typically a member variable of your class).
pictDefault
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 the variable referenced by pict, as appropriate. If pictDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_Short
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type short.
BOOL PX_Short(
CPropExchange* pPX,
LPCTSTR pszPropName,
short& sValue);
BOOL PX_Short(
CPropExchange* pPX,
LPCTSTR pszPropName,
short& sValue,
short sDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
sValue
Reference to the variable where the property is stored (typically a member variable of your class).
sDefault
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 the variable referenced by sValue, as appropriate. If sDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_ULong
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type ULONG.
BOOL PX_ULong(
CPropExchange* pPX,
LPCTSTR pszPropName,
ULONG& ulValue);
BOOL PX_ULong(
CPropExchange* pPX,
LPCTSTR pszPropName,
ULONG& ulValue,
long ulDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
Name of the property being exchanged.
ulValue
Reference to the variable where the property is stored (typically a member variable of your class).
ulDefault
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 the variable referenced by ulValue, as appropriate. If ulDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_UShort
Call this function within your control's DoPropExchange member function to serialize or initialize a property of type unsigned short.
BOOL PX_UShort(
CPropExchange* pPX,
LPCTSTR pszPropName,
USHORT& usValue);
BOOL PX_UShort(
CPropExchange* pPX,
LPCTSTR pszPropName,
USHORT& usValue,
USHORT usDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
Name of the property being exchanged.
usValue
Reference to the variable where the property is stored (typically a member variable of your class).
usDefault
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 the variable referenced by usValue, as appropriate. If usDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PXstring
Call this function within your control's DoPropExchange member function to serialize or initialize a character string property.
BOOL PXstring(
CPropExchange* pPX,
LPCTSTR pszPropName,
CString& strValue);
BOOL PXstring(
CPropExchange* pPX,
LPCTSTR pszPropName,
CString& strValue,
CString strDefault);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
pszPropName
The name of the property being exchanged.
strValue
Reference to the variable where the property is stored (typically a member variable of your class).
strDefault
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 the variable referenced by strValue, as appropriate. If strDefault is specified, it will be used as the property's default value. This value is used if, for any reason, the control's serialization process fails.
PX_VBXFontConvert
Call this function within your control's DoPropExchange member function to initialize a font property by converting a VBX control's font-related properties.
BOOL PX_VBXFontConvert(
CPropExchange* pPX,
CFontHolder& font);
Parameters
pPX
Pointer to the CPropExchange object (typically passed as a parameter to DoPropExchange).
font
The font property of the OLE control that will contain the converted VBX font-related properties.
Return Value
Nonzero if the exchange was successful; 0 if unsuccessful.
Remarks
This function should be used only by an OLE control that is designed as a direct replacement for a VBX control. When the Visual Basic development environment converts a form containing a VBX control to use the corresponding replacement OLE control, it will call the control's IDataObject::SetData function, passing in a property set that contains the VBX control's property data. This operation, in turn, causes the control's DoPropExchange function to be invoked. DoPropExchange can call PX_VBXFontConvert to convert the VBX control's font-related properties (for example, "FontName," "FontSize," and so on) into the corresponding components of the OLE control's font property.
PX_VBXFontConvert should only be called when the control is actually being converted from a VBX form application. For example:
void CMFCActiveXControlCtrl::DoPropExchange(CPropExchange* pPX)
{
ExchangeVersion(pPX, MAKELONG(_wVerMinor, _wVerMajor));
COleControl::DoPropExchange(pPX);
if (IsConvertingVBX())
PX_VBXFontConvert(pPX, InternalGetFont());
}