OLE 控制項的持續性

發行項
10/12/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，其中包含後續二進位資料的長度，以位元組為單位，緊接著
包含實際二進位資料的記憶體區塊。

請注意， PX_Blob 載入 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 的成員函式內呼叫此函式，以序列化或初始化貨幣 類型的 屬性。

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 的成員函式中呼叫此函式，以序列化或初始化類型字型的屬性。

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

參數

pPX
CPropExchange 物件的指標（通常傳遞為參數至 DoPropExchange ）。

pszPropName
要交換之屬性的名稱。

字體
包含字型屬性之物件的參考 CFontHolder 。

pFontDesc
結構的指標 FONTDESC ，其中包含初始化字型屬性的預設狀態時所要使用的值，在 pFontDispAmbient 為 Null 的情況下。

pFontDispAmbient
字型介面的 IFontDisp 指標，用於初始化字型屬性的預設狀態。

傳回值

如果交換成功，則為非零;如果失敗，則為 0。

備註

屬性的值會在適當時從讀取或寫入至 font ， CFontHolder 參考。如果 指定 pFontDesc 和 pFontDispAmbient ，則會在需要時用來初始化屬性的預設值。如果控制項的序列化程式失敗，則會使用這些值。一般而言，您會針對 pFontDesc 傳遞 Null，以及 pFontDispAmbient 所 COleControl::AmbientFont 傳回的環境值。請注意，所 COleControl::AmbientFont 傳回的字型物件必須由成員函式的呼叫 IFontDisp::Release 釋放。

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
要交換之屬性的名稱。

朋克
包含物件介面的變數參考，該介面表示屬性的值。

Iid
介面識別碼，指出控制項會使用屬性物件的介面。

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 ）。

字體
將包含已轉換之 VBX 字型相關屬性之 OLE 控制項的字型屬性。

傳回值

如果交換成功，則為非零;如果失敗，則為 0。

備註

此函式只能由設計為直接取代 VBX 控制項的 OLE 控制項使用。當 Visual Basic 開發環境轉換包含 VBX 控制項的表單以使用對應的取代 OLE 控制項時，它會呼叫控制項的 IDataObject::SetData 函式，並傳入包含 VBX 控制項屬性資料的屬性集。接著，這項作業會導致叫用控制項的 DoPropExchange 函式。 DoPropExchange 可以呼叫 PX_VBXFontConvert ，將 VBX 控制項的字型相關屬性（例如「FontName」、「FontSize」等）轉換成 OLE 控制項字型屬性的對應元件。

PX_VBXFontConvert 只有當控制項實際上是從 VBX 表單應用程式轉換時，才應該呼叫。例如：

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

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

另請參閱

宏和全域

共用方式為

OLE 控制項的持續性