Persistência de controles OLE

Artigo
08/04/2024

Uma funcionalidade dos controles OLE é a persistência (ou serialização) da propriedade, que permite que o controle OLE leia ou grave valores de propriedade em um arquivo ou fluxo. Um aplicativo de contêiner pode usar a serialização para armazenar os valores de propriedade de um controle, mesmo depois que o aplicativo tiver destruído o controle. Os valores de propriedade do controle OLE podem ser lidos no arquivo ou do fluxo, quando uma nova instância do controle é criada posteriormente.

Persistência de controles OLE

Nome	Descrição
PX_Blob	Troca uma propriedade que armazena dados de BLOB (objeto binário grande).
PX_Bool	Troca uma propriedade de controle do tipo BOOL.
PX_Color	Troca uma propriedade de cor de um controle.
PX_Currency	Troca uma propriedade de controle do tipo CY.
PX_DataPath	Troca uma propriedade de controle do tipo `CDataPathProperty`.
PX_Double	Troca uma propriedade de controle do tipo `double`.
PX_Font	Troca uma propriedade de fonte de um controle.
PX_Float	Troca uma propriedade de controle do tipo `float`.
PX_IUnknown	Troca uma propriedade de controle de tipo indefinido.
PX_Long	Troca uma propriedade de controle do tipo `long`.
PX_Picture	Troca uma propriedade de imagem de um controle.
PX_Short	Troca uma propriedade de controle do tipo `short`.
PX_ULong	Troca uma propriedade de controle do tipo ULONG.
PX_UShort	Troca uma propriedade de controle do tipo USHORT.
PXstring	Troca uma propriedade de controle da cadeia de caracteres.
PX_VBXFontConvert	Troca as propriedades relacionadas à fonte de um controle VBX em uma propriedade de fonte de controle OLE.

Além disso, a função global AfxOleTypeMatchGuid é fornecida para testar uma correspondência entre um TYPEDESC e um GUID fornecido.

PX_Blob

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade que armazena dados de BLOB (objeto binário grande).

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

hBlob
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

hBlobDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade será lido ou gravado para a variável referenciada por phBlob, conforme apropriado. Essa variável deve ser inicializada para NULL, antes de chamar PX_Blob inicialmente pela primeira vez (normalmente, isso pode ser feito no construtor do controle). Se hBlobDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por qualquer motivo, o processo de inicialização ou serialização do controle falhar.

Os identificadores hBlob e hBlobDefault se referem a um bloco de memória que contém o seguinte:

Um DWORD que contém o comprimento, em bytes, dos dados binários a seguir, seguidos imediatamente por
Um bloco de memória que contém os dados binários reais.

Observe que PX_Blob alocará a memória usando a API GlobalAlloc do Windows, ao carregar propriedades do tipo BLOB. Você é responsável por liberar essa memória. Portanto, o destruidor do controle deve chamar GlobalFree em qualquer identificador de propriedade do tipo BLOB, para liberar a memória alocada para o controle.

PX_Bool

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo BOOL.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

bValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

bDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade será lido ou gravado para a variável referenciada por bValue, conforme apropriado. Se bDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_Color

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo 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);

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

clrValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

clrDefault
Valor padrão da propriedade, conforme definido pelo desenvolvedor de controle.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade será lido ou gravado para a variável referenciada por clrValue, conforme apropriado. Se clrDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_Currency

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo currency.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

cyValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

cyDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade será lido ou gravado para a variável referenciada por cyValue, conforme apropriado. Se cyDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_DataPath

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do caminho de dados do tipo CDataPathProperty.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

dataPathProperty
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

As propriedades do caminho de dados implementam as propriedades de controle assíncronas. O valor da propriedade será lido ou gravado para a variável referenciada por dataPathProperty, conforme apropriado.

PX_Double

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo double.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

doubleValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

doubleDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado para a variável referida por doubleValue, conforme apropriado. Se doubleDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_Font

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo font.

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

font
Uma referência a um objeto CFontHolder que contém a propriedade de fonte.

pFontDesc
Um ponteiro para uma estrutura FONTDESC que contém os valores a serem usados na inicialização do estado padrão da propriedade font. Nesse caso, pFontDispAmbient é NULL.

pFontDispAmbient
Um ponteiro para a interface IFontDisp de uma fonte a ser usada para inicializar o estado padrão da propriedade de fonte.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado em font, uma referência de CFontHolder, quando apropriado. Se pFontDesc e pFontDispAmbient forem especificados, serão usados para inicializar o valor padrão da propriedade, quando necessário. Esses valores serão usados se, por algum motivo, o processo de serialização do controle falhar. Normalmente, você passa NULL para pFontDesc e o valor de ambiente retornado por COleControl::AmbientFont para pFontDispAmbient. Observe que o objeto de fonte retornado por COleControl::AmbientFont deve ser liberado por uma chamada à função de membro IFontDisp::Release.

PX_Float

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo float.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

floatValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

floatDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado para a variável referida por floatValue, conforme apropriado. Se floatDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_IUnknown

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade representada por um objeto com uma interface derivada de IUnknown.

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

pUnk
Referência a uma variável que contém a interface do objeto, que representa o valor da propriedade.

iid
Uma ID de interface que indica qual interface do objeto de propriedade é usada pelo controle.

pUnkDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado para a variável referida por pUnk, conforme apropriado. Se pUnkDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_Long

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo long.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

lValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

lDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado para a variável referida por lValue, conforme apropriado. Se lDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_Picture

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade de imagem do controle.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

pict
Referência a um objeto CPictureHolder em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

pictDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado para a variável referida por pict, conforme apropriado. Se pictDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_Short

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo short.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

sValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

sDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado para a variável referida por sValue, conforme apropriado. Se sDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_ULong

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo ULONG.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
Nome da propriedade que está sendo trocada.

ulValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

ulDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado para a variável referida por ulValue, conforme apropriado. Se ulDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_UShort

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade do tipo unsigned short.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
Nome da propriedade que está sendo trocada.

usValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

usDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado para a variável referida por usValue, conforme apropriado. Se usDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PXstring

Chame essa função na função de membro DoPropExchange do controle, para serializar ou inicializar uma propriedade da cadeia de caracteres.

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

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

pszPropName
O nome da propriedade que está sendo trocada.

strValue
Referência à variável em que a propriedade é armazenada (normalmente uma variável membro da sua classe).

strDefault
Valor padrão da propriedade.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

O valor da propriedade é lido ou gravado para a variável referida por strValue, conforme apropriado. Se strDefault for especificado, ele será usado como o valor padrão da propriedade. Esse valor será usado se, por algum motivo, o processo de serialização do controle falhar.

PX_VBXFontConvert

Chame essa função na função de membro DoPropExchange do controle, para inicializar uma propriedade de fonte convertendo as propriedades relacionadas à fonte de um controle VBX.

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

Parâmetros

pPX
Ponteiro para o objeto CPropExchange (normalmente passado como parâmetro para DoPropExchange).

font
A propriedade de fonte do controle OLE que conterá as propriedades convertidas relacionadas à fonte VBX.

Valor de retorno

Um valor diferente de zero, se a troca tiver êxito. Caso contrário, 0.

Comentários

Essa função deve ser usada apenas por um controle OLE criado como substituição direta para um controle VBX. Quando o ambiente de desenvolvimento do Visual Basic converter um formulário que contém um controle VB,X para usar o controle OLE de substituição correspondente, chamará a função IDataObject::SetData do controle, passando um conjunto de propriedades que contém os dados de propriedade do controle VBX. Essa operação, por sua vez, faz com que a função DoPropExchange do controle seja invocada. DoPropExchange pode chamar PX_VBXFontConvert para converter as propriedades relacionadas à fonte do controle VBX (por exemplo, "FontName", "FontSize" e assim por diante) nos componentes correspondentes da propriedade de fonte do controle OLE.

PX_VBXFontConvert só deve ser chamado quando o controle estiver realmente sendo convertido de um aplicativo de formulário VBX. Por exemplo:

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

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

Confira também

Macros e Globais

Compartilhar via

Persistência de controles OLE