Сохраняемость элементов управления 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, по мере необходимости. Эта переменная должна быть инициализирована в NULL перед первым вызовом PX_Blob (как правило, это можно сделать в конструкторе элемента управления). Если указан hBlobDefault , он будет использоваться в качестве значения по умолчанию свойства. Это значение используется, если по какой-либо причине процесс инициализации или сериализации элемента управления завершается сбоем.

Дескрипторы hBlob и hBlobDefault ссылаются на блок памяти, содержащий следующее:

DWORD, содержащий длину в байтах двоичных данных, за которым следует сразу же.
Блок памяти, содержащий фактические двоичные данные.

Обратите внимание, что PX_Blob выделяет память с помощью API GlobalAlloc Windows при загрузке свойств типа BLOB. Вы несете ответственность за освобождение этой памяти. Поэтому деструктор элемента управления должен вызывать GlobalFree в любом свойстве типа BLOB, чтобы освободить любую память, выделенную элементу управления.

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 , они используются для инициализации значения по умолчанию свойства при необходимости. Эти значения используются, если по какой-либо причине процесс сериализации элемента управления завершается ошибкой. Как правило, значение NULL передается для pFontDesc и окружающее значение, возвращаемое COleControl::AmbientFont pFontDispAmbient. Обратите внимание, что возвращаемый 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).

шрифт
Свойство шрифта элемента управления OLE, которое будет содержать преобразованные свойства шрифта VBX.

Возвращаемое значение

Ненулевое значение, если обмен был успешным; 0, если неудачно.

Замечания

Эта функция должна использоваться только элементом управления OLE, разработанным как прямая замена для элемента управления VBX. Когда среда разработки 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