OLE コントロールの永続化

[アーティクル]
06/16/2023

OLE コントロールの 1 つの機能は、プロパティの永続化 (またはシリアル化) です。これにより、OLE コントロールはファイルまたはストリームとの間でプロパティ値の読み取りまたは書き込みを行えます。コンテナーアプリケーションでは、シリアル化を使用して、アプリケーションがコントロールを破棄した後でも、コントロールのプロパティ値を格納できます。 OLE コントロールのプロパティ値は、後でコントロールの新しいインスタンスが作成されるときに、ファイルまたはストリームから読み取ることができます。

OLE コントロールの永続化

名前	説明
PX_Blob	バイナリラージオブジェクト (BLOB) データを格納するコントロールプロパティを交換します。
PX_Bool	BOOL 型のコントロールプロパティを交換します。
PX_Color	コントロールの color プロパティを交換します。
PX_Currency	CY 型のコントロールプロパティを交換します。
PX_DataPath	`CDataPathProperty`型のコントロールプロパティを交換します。
PX_Double	`double`型のコントロールプロパティを交換します。
PX_Font	コントロールの font プロパティを交換します。
PX_Float	`float`型のコントロールプロパティを交換します。
PX_IUnknown	未定義の型のコントロールプロパティを交換します。
PX_Long	`long`型のコントロールプロパティを交換します。
PX_Picture	コントロールの picture プロパティを交換します。
PX_Short	`short`型のコントロールプロパティを交換します。
PX_ULong	ULONG 型のコントロールプロパティを交換します。
PX_UShort	USHORT 型のコントロールプロパティを交換します。
PXstring	文字列コントロールプロパティを交換します。
PX_VBXFontConvert	VBX コントロールのフォント関連プロパティを OLE コントロールのフォントプロパティに交換します。

さらに、typeDESC と特定の GUID の間の一致をテストするために、 AfxOleTypeMatchGuid グローバル関数が提供されます。

PX_Blob

コントロールの DoPropExchange メンバー関数内でこの関数を呼び出して、バイナリラージオブジェクト (BLOB) データを格納するプロパティをシリアル化または初期化します。

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

パラメーター

pPX
CPropExchange オブジェクトへのポインター (通常、DoPropExchangeのパラメーターとして渡されます)。

pszPropName
交換するプロパティの名前。

hBlob
プロパティが格納されている変数への参照 (通常はクラスのメンバー変数)。

hBlobDefault
プロパティの既定値。

戻り値

交換が成功した場合は 0 以外。失敗した場合は 0。

解説

プロパティの値は、必要に応じて、 hBlob によって参照される変数から読み取られるか、変数に書き込まれます。この変数は、最初に PX_Blob を初めて呼び出す前に NULL に初期化する必要があります (通常、これはコントロールのコンストラクターで実行できます)。 hBlobDefault を指定すると、プロパティの既定値として使用されます。この値は、何らかの理由でコントロールの初期化またはシリアル化プロセスが失敗した場合に使用されます。

ハンドル hBlob と hBlobDefault は、次を含むメモリブロックを参照します。

後に続くバイナリデータの長さをバイト単位で格納し、その直後に続く DWORD
実際のバイナリデータを含むメモリブロック。

は、BLOB 型のプロパティを読み込むときに、Windows GlobalAlloc API を使用してメモリを割り当てることに注意してください。このメモリを解放する必要があります。そのため、コントロールのデストラクターは、任意の BLOB 型プロパティハンドルで GlobalFree を呼び出して、コントロールに割り当てられているメモリを解放する必要があります。

PX_Bool

BOOL 型のプロパティをシリアル化または初期化するには、コントロールの DoPropExchange メンバー関数内でこの関数を呼び出します。

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 以外。失敗した場合は 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 以外。失敗した場合は 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 以外。失敗した場合は 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 以外。失敗した場合は 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 以外。失敗した場合は 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
交換するプロパティの名前。

font
font プロパティを含む CFontHolder オブジェクトへの参照。

pFontDesc
フォントプロパティの既定の状態の初期化に使用する値を含む FONTDESC 構造体へのポインター ( pFontDispAmbient が NULL の場合)。

pFontDispAmbient
font プロパティの既定の状態の初期化に使用するフォントの IFontDisp インターフェイスへのポインター。

戻り値

交換が成功した場合は 0 以外。失敗した場合は 0。

解説

プロパティの値は、必要に応じて、CFontHolder参照であるfontから読み取られたり書き込まれたりします。 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 以外。失敗した場合は 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 以外。失敗した場合は 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 以外。失敗した場合は 0。

解説

プロパティの値は、必要に応じて、 lValue によって参照される変数から読み取られたり、変数に書き込まれたりします。 lDefaultを指定すると、プロパティの既定値として使用されます。この値は、何らかの理由でコントロールのシリアル化プロセスが失敗した場合に使用されます。

PX_Picture

コントロールの 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 以外。失敗した場合は 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 以外。失敗した場合は 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 以外。失敗した場合は 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 以外。失敗した場合は 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 以外。失敗した場合は 0。

解説

プロパティの値は、必要に応じて、 strValue によって参照される変数から読み取られたり、変数に書き込まれたりします。 strDefault を指定すると、プロパティの既定値として使用されます。この値は、何らかの理由でコントロールのシリアル化プロセスが失敗した場合に使用されます。

PX_VBXFontConvert

VBX コントロールのフォント関連プロパティを変換してフォントプロパティを初期化するには、コントロールの DoPropExchange メンバー関数内でこの関数を呼び出します。

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

パラメーター

pPX
CPropExchange オブジェクトへのポインター (通常、DoPropExchangeのパラメーターとして渡されます)。

font
変換された VBX フォント関連のプロパティを格納する OLE コントロールの font プロパティ。

戻り値

交換が成功した場合は 0 以外。失敗した場合は 0。

解説

この関数は、VBX コントロールの直接の置換として設計された OLE コントロールでのみ使用する必要があります。 Visual Basic 開発環境は、対応する置換 OLE コントロールを使用するように VBX コントロールを含むフォームを変換するときに、コントロールの IDataObject::SetData 関数を呼び出し、VBX コントロールのプロパティデータを含むプロパティセットを渡します。この操作により、コントロールの DoPropExchange 関数が呼び出されます。 DoPropExchange では、 PX_VBXFontConvert を呼び出して、VBX コントロールのフォント関連プロパティ ("FontName"、"FontSize" など) を OLE コントロールの font プロパティの対応するコンポーネントに変換できます。

PX_VBXFontConvert は、コントロールが実際に VBX フォームアプリケーションから変換されている場合にのみ呼び出す必要があります。次に例を示します。

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

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

次の方法で共有

OLE コントロールの永続化