OLE 控件的持久性

项目
10/16/2023

OLE 控件的一项功能是属性持久化（或称为“序列化”），它允许 OLE 控件在文件或流中读取或写入属性值。即使在容器应用程序销毁该控件之后，该应用程序仍可以使用序列化来存储控件的属性值。之后，当创建控件的新实例时，OLE 控件的属性值可从文件或流中读取。

OLE 控件的持久性

名称	描述
PX_Blob	交换存储二进制大型对象 (BLOB) 数据的控件属性。
PX_Bool	交换 BOOL 类型的控件属性。
PX_Color	交换控件的颜色属性。
PX_Currency	交换 CY 类型的控件属性。
PX_DataPath	交换 `CDataPathProperty` 类型的控件属性。
PX_Double	交换 `double` 类型的控件属性。
PX_Font	交换控件的字体属性。
PX_Float	交换 `float` 类型的控件属性。
PX_IUnknown	交换未定义类型的控件属性。
PX_Long	交换 `long` 类型的控件属性。
PX_Picture	交换控件的图片属性。
PX_Short	交换 `short` 类型的控件属性。
PX_ULong	交换 ULONG 类型的控件属性。
PX_UShort	交换 USHORT 类型的控件属性。
PXstring	交换字符字符串控件属性。
PX_VBXFontConvert	将 VBX 控件的字体相关属性交换到 OLE 控件字体属性中。

此外，还提供了 AfxOleTypeMatchGuid 全局函数来测试 TYPEDESC 与给定 GUID 是否匹配。

PX_Blob

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化存储二进制大型对象 (BLOB) 数据的属性。

BOOL PX_Blob(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    HGLOBAL& hBlob,
    HGLOBAL hBlobDefault = NULL);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

hBlob
对存储属性的变量的引用（通常是类的成员变量）。

hBlobDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

注解

将根据需要在 hBlob 引用的变量中读取或写入该属性的值。此变量应在首次调用 PX_Blob 之前初始化为 NULL（通常可以在控件的构造函数中完成）。如果指定了 hBlobDefault，它将用作属性的默认值。如果控件的初始化或序列化过程出于任何原因失败，则使用此值。

句柄 hBlob 和 hBlobDefault 是指包含以下内容的内存块：

一个 DWORD，它包含后面的二进制数据的长度（以字节为单位），其后紧跟
包含实际二进制数据的内存块。

请注意，在加载 BLOB 类型的属性时，PX_Blob 将使用 Windows GlobalAlloc API 分配内存。你负责释放此内存。因此，控件的析构函数应在任何 BLOB 类型的属性句柄上调用 GlobalFree，以释放分配给控件的任何内存。

PX_Bool

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 BOOL 类型的属性。

BOOL PX_Bool(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    BOOL& bValue);

BOOL PX_Bool(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    BOOL& bValue,
    BOOL bDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

bValue
对存储属性的变量的引用（通常是类的成员变量）。

bDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

将根据需要在 bValue 引用的变量中读取或写入该属性的值。如果指定了 bDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_Color

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 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);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

clrValue
对存储属性的变量的引用（通常是类的成员变量）。

clrDefault
由控件开发人员定义的属性默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

将根据需要在 clrValue 引用的变量中读取或写入该属性的值。如果指定了 clrDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_Currency

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 currency 类型的属性。

BOOL PX_Currency(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    CY& cyValue);

BOOL PX_Currency(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    CY& cyValue,
    CY cyDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

cyValue
对存储属性的变量的引用（通常是类的成员变量）。

cyDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

将根据需要在 cyValue 引用的变量中读取或写入该属性的值。如果指定了 cyDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_DataPath

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 CDataPathProperty 类型的数据路径属性。

BOOL PX_DataPath(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    CDataPathProperty& dataPathProperty);

BOOL PX_DataPath(
    CPropExchange* pPX,
    CDataPathProperty& dataPathProperty);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

dataPathProperty
对存储属性的变量的引用（通常是类的成员变量）。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

数据路径属性实现异步控制属性。将根据需要在 dataPathProperty 引用的变量中读取或写入该属性的值。

PX_Double

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 double 类型的属性。

BOOL PX_Double(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    double& doubleValue);

BOOL PX_Double(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    double& doubleValue,
    double doubleDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

doubleValue
对存储属性的变量的引用（通常是类的成员变量）。

doubleDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

根据需要在 doubleValue 引用的变量中读取或写入该属性的值。如果指定了 doubleDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_Font

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 font 类型的属性。

BOOL PX_Font(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    CFontHolder& font,
    const FONTDESC FAR* pFontDesc = NULL,
    LPFONTDISP pFontDispAmbient = NULL);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

font
对包含 font 属性的 CFontHolder 对象的引用。

pFontDesc
在 pFontDispAmbient 为 NULL 的情况下，指向 FONTDESC 结构的指针，该结构包含用于初始化 font 属性的默认状态的值。

pFontDispAmbient
指向字体的 IFontDisp 接口的指针，该字体用于初始化 font 属性的默认状态。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

根据需要在 font（一个 CFontHolder 引用）中读取或写入该属性的值。如果指定了 pFontDesc 和 pFontDispAmbient，则它们用于根据需要初始化属性的默认值。如果控件的序列化过程出于任何原因失败，则使用这些值。通常，为 pFontDesc 传递 NULL，为 pFontDispAmbient 传递由 COleControl::AmbientFont 返回的环境值。请注意，必须通过调用 IFontDisp::Release 成员函数来释放 COleControl::AmbientFont 返回的字体对象。

PX_Float

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 float 类型的属性。

BOOL PX_Float(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    float& floatValue);

BOOL PX_Float(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    float& floatValue,
    float floatDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

floatValue
对存储属性的变量的引用（通常是类的成员变量）。

floatDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

注解

根据需要在 floatValue 引用的变量中读取或写入该属性的值。如果指定了 floatDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_IUnknown

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化由具有 IUnknown 派生接口的对象表示的属性。

BOOL PX_IUnknown(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    LPUNKNOWN& pUnk,
    REFIID iid,
    LPUNKNOWN pUnkDefault = NULL);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

pUnk
对包含表示属性值的对象接口的变量的引用。

iid
一个接口 ID，指示控件使用的属性对象的接口。

pUnkDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

根据需要在 pUnk 引用的变量中读取或写入该属性的值。如果指定了 pUnkDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_Long

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 long 类型的属性。

BOOL PX_Long(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    long& lValue);

BOOL PX_Long(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    long& lValue,
    long lDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

lValue
对存储属性的变量的引用（通常是类的成员变量）。

lDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

注解

根据需要在 lValue 引用的变量中读取或写入该属性的值。如果指定了 lDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_Picture

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化控件的图片属性。

BOOL PX_Picture(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    CPictureHolder& pict);

BOOL PX_Picture(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    CPictureHolder& pict,
    CPictureHolder& pictDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

pict
对存储属性的 CPictureHolder 对象的引用（通常是类的成员变量）。

pictDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

根据需要在 pict 引用的变量中读取或写入该属性的值。如果指定了 pictDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_Short

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 short 类型的属性。

BOOL PX_Short(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    short& sValue);

BOOL PX_Short(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    short& sValue,
    short sDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

sValue
对存储属性的变量的引用（通常是类的成员变量）。

sDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

根据需要在 sValue 引用的变量中读取或写入该属性的值。如果指定了 sDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_ULong

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 ULONG 类型的属性。

BOOL PX_ULong(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    ULONG& ulValue);

BOOL PX_ULong(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    ULONG& ulValue,
    long ulDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

ulValue
对存储属性的变量的引用（通常是类的成员变量）。

ulDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

根据需要在 ulValue 引用的变量中读取或写入该属性的值。如果指定了 ulDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_UShort

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化 unsigned short 类型的属性。

BOOL PX_UShort(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    USHORT& usValue);

BOOL PX_UShort(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    USHORT& usValue,
    USHORT usDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

usValue
对存储属性的变量的引用（通常是类的成员变量）。

usDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

根据需要在 usValue 引用的变量中读取或写入该属性的值。如果指定了 usDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PXstring

在控件的 DoPropExchange 成员函数中调用此函数，以序列化或初始化字符串属性。

BOOL PXstring(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    CString& strValue);

BOOL PXstring(
    CPropExchange* pPX,
    LPCTSTR pszPropName,
    CString& strValue,
    CString strDefault);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

pszPropName
要交换的属性的名称。

strValue
对存储属性的变量的引用（通常是类的成员变量）。

strDefault
该属性的默认值。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

根据需要在 strValue 引用的变量中读取或写入该属性的值。如果指定了 strDefault，它将用作该属性的默认值。如果控件的序列化过程出于任何原因失败，则使用此值。

PX_VBXFontConvert

在控件的 DoPropExchange 成员函数中调用此函数，通过转换 VBX 控件的字体相关属性来初始化字体属性。

BOOL PX_VBXFontConvert(
    CPropExchange* pPX,
    CFontHolder& font);

参数

pPX
指向 CPropExchange 对象的指针（通常作为参数传递给 DoPropExchange）。

font
将包含转换后的 VBX 字体相关属性的 OLE 控件的字体属性。

返回值

如果交换成功，则为非零值；如果失败，则为 0。

备注

此函数只能由设计用于直接替换 VBX 控件的 OLE 控件使用。当 Visual Basic 开发环境将包含 VBX 控件的窗体转换为使用相应的替换 OLE 控件时，它将调用控件的 IDataObject::SetData 函数，传入包含 VBX 控件属性数据的属性集。而此操作又会导致调用控件的 DoPropExchange 函数。 DoPropExchange 可以调用 PX_VBXFontConvert，以将 VBX 控件的字体相关属性（例如“FontName”、“FontSize”等）转换为 OLE 控件的字体属性的相应组件。

仅当控件实际从 VBX 窗体应用程序转换时，才应调用 PX_VBXFontConvert。例如：

void CMFCActiveXControlCtrl::DoPropExchange(CPropExchange* pPX)
{
   ExchangeVersion(pPX, MAKELONG(_wVerMinor, _wVerMajor));
   COleControl::DoPropExchange(pPX);

   if (IsConvertingVBX())
      PX_VBXFontConvert(pPX, InternalGetFont());

另请参阅

宏和全局函数

OLE 控件的持久性