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 コントロールのフォントプロパティに交換します。

さらに、 AfxOleTypeMatchGuid TYPEDESC と特定の GUID の間の一致をテストするグローバル関数が用意されています。

PX_Blob

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

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
実際のバイナリデータを含むメモリブロック。

PX_Blob 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プロパティをシリアル化または初期化します。

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

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

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 プロパティを CFontHolder 含むオブジェクトへの参照。

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

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

戻り値

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

解説

必要に応じて、プロパティの値が参照から読み取られたり、参照にfontCFontHolder書き込まれたりします。 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 メンバー関数内でこの関数を呼び出して、-derived インターフェイスを持つ 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として渡されます)。

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

戻り値

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

解説

この関数は、VBX コントロールの直接の置換として設計された OLE コントロールでのみ使用する必要があります。 Visual Basic 開発環境は、対応する置換 OLE コントロールを使用するように VBX コントロールを含むフォームを変換するときに、VBX コントロールの IDataObject::SetData プロパティデータを含むプロパティセットを渡して、コントロールの関数を呼び出します。この操作により、コントロールの 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 コントロールの永続化