Partilhar via

Controles ActiveX MFC: adicionando propriedades personalizadas

  • Artigo

As propriedades personalizadas diferem das propriedades padrão no sentido de que as propriedades personalizadas ainda não são implementadas pela classe COleControl. Uma propriedade personalizada é usada para expor um determinado estado ou aparência de um controle ActiveX a um programador usando o controle.

Este artigo descreve como adicionar uma propriedade personalizada ao controle ActiveX usando o Assistente para Adicionar Propriedade e explica as modificações de código resultantes. Os tópicos incluem:

As propriedades personalizadas vêm em quatro variedades de implementação: Variável de Membro, Variável de Membro com Notificação, Métodos Get/Set e Parametrizadas.

  • Implementação de variável de membro

    Essa implementação representa o estado da propriedade como uma variável membro na classe de controle. Use a implementação da Variável de Membro quando não for importante saber quando o valor da propriedade é alterado. Dos três tipos, essa implementação cria a menor quantidade de código de suporte para a propriedade. A macro de entrada do mapa de expedição para implementação de variável membro é DISP_PROPERTY.

  • Variável de membro com implementação de notificação

    Essa implementação consiste em uma variável membro e uma função de notificação criada pelo Assistente para Adicionar Propriedade. A função de notificação é chamada automaticamente pela estrutura depois que o valor da propriedade é alterado. Use a variável de membro com implementação de notificação quando precisar ser notificado depois que um valor da propriedade for alterado. Essa implementação requer mais tempo porque requer uma chamada de função. A macro de entrada do mapa de expedição para essa implementação é DISP_PROPERTY_NOTIFY.

  • Implementação de métodos get/set

    Essa implementação consiste em um par de funções de membro na classe de controle. A implementação dos métodos Get/Set chama automaticamente a função de membro Get quando o usuário do controle solicita o valor atual da propriedade e a função Definir membro quando o usuário do controle solicita que a propriedade seja alterada. Use essa implementação quando precisar computar o valor de uma propriedade durante o tempo de execução, validar um valor passado pelo usuário do controle antes de alterar a propriedade real ou implementar um tipo de propriedade somente leitura ou somente gravação. A macro de entrada do mapa de expedição para essa implementação é DISP_PROPERTY_EX. A seção a seguir, Como usar o assistente Adicionar Propriedade para adicionar uma propriedade personalizada, usa a propriedade personalizada CircleOffset para demonstrar essa implementação.

  • Implementação parametrizada

    A implementação parametrizada é compatível com o assistente Adicionar Propriedade. Uma propriedade parametrizada (às vezes chamada de matriz de propriedades) pode ser usada para acessar um conjunto de valores por meio de uma só propriedade do controle. A macro de entrada do mapa de expedição para essa implementação é DISP_PROPERTY_PARAM. Para mais informações sobre como implementar esse tipo, confira Como implementar uma propriedade parametrizada no artigo Controles ActiveX: tópicos avançados.

Como usar o assistente Adicionar Propriedade para adicionar uma propriedade personalizada

O procedimento a seguir demonstra a adição de uma propriedade personalizada, CircleOffset, que usa a implementação dos métodos Get/Set. A propriedade personalizada CircleOffset permite que o usuário do controle compense o círculo do centro do retângulo delimitador do controle. O procedimento para adicionar propriedades personalizadas com uma implementação diferente de Métodos Get/Set é muito semelhante.

Esse mesmo procedimento também pode ser usado para adicionar outras propriedades personalizadas desejadas. Substitua o nome da propriedade personalizada pelo nome e parâmetros da propriedade CircleOffset.

Para adicionar a propriedade personalizada CircleOffset usando o assistente Adicionar Propriedade

  1. Carregue o projeto do controle.

  2. No Modo de Exibição de Classe, expanda o nó de biblioteca do controle.

  3. Clique com o botão direito do mouse no nó de interface do controle (o segundo nó do nó da biblioteca) para abrir o menu de atalho.

  4. No menu de atalho, clique em Adicionar e, em seguida, em Adicionar Propriedade.

    Isso abre o Assistente para Adicionar Propriedade.

  5. Na caixa Nome da Propriedade, digite CircleOffset.

  6. Para o Tipo de Implementação, clique em Métodos Get/Set.

  7. Na caixa Tipo de propriedade, selecione short.

  8. Digite nomes exclusivos para obter e definir funções ou aceite os nomes padrão.

  9. Clique em Concluir.

Adicionar alterações do Assistente de Propriedade para Propriedades Personalizadas

Quando você adiciona a propriedade personalizada CircleOffset, o assistente Adicionar Propriedade faz alterações aos arquivos de cabeçalho (.H) e a implementação (.CPP) da classe de controle.

As seguintes linhas são adicionadas ao arquivo .H para declarar duas funções chamadas GetCircleOffset e SetCircleOffset:

SHORT GetCircleOffset(void);
void SetCircleOffset(SHORT newVal);

A seguinte linha é adicionada ao arquivo .IDL do controle:

[id(2), helpstring("property CircleOffset")] SHORT CircleOffset;
[id(3), helpstring("property MyProperty")] SHORT MyProperty;

Essa linha atribui à propriedade CircleOffset um número de ID específico, obtido da posição do método na lista de métodos e propriedades do assistente Adicionar Propriedade.

Além disso, a seguinte linha é adicionada ao mapa de expedição (no arquivo .CPP da classe de controle) para mapear a propriedade CircleOffset para as duas funções de manipulador do controle:

DISP_PROPERTY_EX_ID(CMyAxUICtrl, "CircleOffset", dispidCircleOffset, GetCircleOffset, SetCircleOffset, VT_I2)

Por fim, as implementações das funções GetCircleOffset e SetCircleOffset são adicionadas ao final do arquivo .CPP de controle. Na maioria dos casos, você modificará a função Get para retornar o valor da propriedade. A função Set geralmente conterá código que deve ser executado antes ou depois das alterações da propriedade.

void CMyAxUICtrl::SetCircleOffset(SHORT /*newVal*/)
{
   AFX_MANAGE_STATE(AfxGetStaticModuleState());

   // TODO: Add your property handler code here

   SetModifiedFlag();
}

Observe que o assistente Adicionar Propriedade adiciona automaticamente uma chamada, SetModifiedFlag, ao corpo da função Set. Chamar essa função marca o controle como modificado. Se um controle tiver sido modificado, seu novo estado será salvo quando o contêiner for salvo. Essa função deve ser chamada sempre que uma propriedade, salva como parte do estado persistente do controle, muda de valor.

Confira também

Controles ActiveX do MFC
Controles ActiveX do MFC: propriedades
Controles ActiveX do MFC: métodos
Classe COleControl