Controles ActiveX do MFC: adicionando propriedades personalizadas

As propriedades personalizadas diferem das propriedades de estoque em que as propriedades personalizadas ainda não são implementadas pela COleControl classe. 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:

• Usando o Assistente para Adicionar Propriedades para incluir uma propriedade personalizada

• Adicionar alterações do Assistente de Propriedade para propriedades personalizadas

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 de 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 de Métodos Get/Set chama automaticamente a função Get member 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 calcular 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 gravação. A macro de entrada do mapa de despacho 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 única propriedade do controle. A macro de entrada do mapa de expedição para essa implementação é DISP_PROPERTY_PARAM. Para obter mais informações sobre como implementar esse tipo, consulte Implementando uma propriedade parametrizada no artigo Controles ActiveX: Tópicos Avançados.

Usando o Assistente de Adição de Propriedade para adicionar uma Propriedade Customizada

O procedimento a seguir demonstra a adição de uma propriedade personalizada, CircleOffset, que usa a implementação Get/Set Methods. A propriedade personalizada CircleOffset permite que o usuário do controle desloque o círculo a partir 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 clique 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 Obter/Definir Métodos.

7. Na caixa Tipo de Propriedade , selecione short.

8. Digite nomes exclusivos para suas funções Get e Set ou aceite os nomes padrão.

9. Clique em Concluir.

Adicionar alterações no Assistente de Propriedades 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 linhas a seguir 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 seu 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, extraído da posição do método na lista de métodos e propriedades do Assistente para 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 do 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 de propriedade.

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

   // TODO: Add your property handler code here

   SetModifiedFlag();
}

Observe que o Assistente para Adicionar Propriedade adiciona automaticamente uma chamada, a 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, altera o valor.

Consulte também

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