Adicionando uma página de propriedades (ATL Tutorial, Parte 6)

As páginas de propriedades são implementadas como objetos COM separados, que permitem que sejam compartilhadas, se necessário. Nesta etapa, você fará as seguintes tarefas para adicionar uma página de propriedades ao controle:

• Criando o recurso Página de Propriedades

• Adicionando código para criar e gerenciar a página de propriedades

• Adicionando a página de propriedades ao controle

Criando o recurso Página de Propriedades

Para adicionar uma página de propriedades ao seu controle, use o modelo ATL Property Page.

Para adicionar uma Página de Propriedades

1. No Gerenciador de Soluções, clique com o botão direito do mouse em Polygon.

2. No menu de atalho, clique em Adicionar>Novo Item.

3. Na lista de modelos, selecione ATL>ATL Property Page e clique em Add.

4. Quando o ATL Property Page Wizard for exibido, digite PolyProp como o nome curto.

5. Clique em Strings para abrir a página Strings e digite &Polygon como o Título.

   O Título da página de propriedades é a cadeia de caracteres que aparece na guia dessa página. A Doc string é uma descrição que um painel de propriedades utiliza para apresentar numa linha de estado ou numa dica de ferramenta. Observe que o quadro de propriedade padrão atualmente não usa essa cadeia de caracteres, portanto, você pode deixá-lo com o conteúdo padrão. Você não irá gerar um arquivo de Ajuda no momento, portanto, exclua a entrada nessa caixa de texto.

6. Clique em Concluir e o objeto da página de propriedades será criado.

Os três arquivos a seguir são criados:

As seguintes alterações de código também são feitas:

• A nova página de propriedades é adicionada ao mapa de entrada de objeto no Polygon.cpp.

• A PolyProp classe é adicionada ao arquivo Polygon.idl.

• O novo arquivo de script do Registro PolyProp.rgs é adicionado ao recurso do projeto.

• Um modelo de caixa de diálogo é adicionado ao recurso de projeto para a página de propriedades.

• As cadeias de caracteres de propriedade que especificou são adicionadas à tabela de cadeia de caracteres de recurso.

Agora adicione os campos que você deseja que apareçam na página de propriedades.

Para adicionar campos à Página de Propriedades

1. No Gerenciador de Soluções, clique duas vezes no arquivo de recurso Polygon.rc. Isto abrirá a Vista do Recurso.

2. No Modo de Exibição de Recurso, expanda o nó Dialog e clique duas vezes em IDD_POLYPROP. Observe que a caixa de diálogo que aparece está vazia, exceto para um rótulo que diz para inserir seus controles aqui.

3. Selecione esse rótulo e altere-o para leitura Sides: alterando o texto da legenda na janela Propriedades .

4. Redimensione a caixa de etiqueta para que se ajuste ao tamanho do texto.

5. Arraste um controle de edição da caixa de ferramentas para a direita do rótulo.

6. Finalmente, altere a ID do controlo de edição para IDC_SIDES, utilizando a janela Propriedades.

Isso conclui o processo de criação do recurso de página de propriedades.

Adicionando código para criar e gerenciar a página de propriedades

Agora que você criou o recurso de página de propriedades, você precisa escrever o código de implementação.

Primeiro, habilite a CPolyProp classe para definir o número de lados em seu objeto quando o botão Aplicar for pressionado.

Para alterar a função Apply e definir o número de lados

1. Substitua a Apply função em PolyProp.h com o seguinte código:

   STDMETHOD(Apply)(void)
   {
      USES_CONVERSION;
      ATLTRACE(_T("CPolyProp::Apply\n"));
      for (UINT i = 0; i < m_nObjects; i++)
      {
         CComQIPtr<IPolyCtl, &IID_IPolyCtl> pPoly(m_ppUnk[i]);
         short nSides = (short)GetDlgItemInt(IDC_SIDES);
         if FAILED(pPoly->put_Sides(nSides))
         {
            CComPtr<IErrorInfo> pError;
            CComBSTR strError;
            GetErrorInfo(0, &pError);
            pError->GetDescription(&strError);
            MessageBox(OLE2T(strError), _T("Error"), MB_ICONEXCLAMATION);
            return E_FAIL;
         }
      }
      m_bDirty = FALSE;
      return S_OK;
   }
   

Uma página de propriedades pode ter mais de um cliente anexado a ela ao mesmo tempo, de modo que a Apply função faz um loop e chama put_Sides cada cliente com o valor recuperado da caixa de edição. Você está a utilizar a classe CComQIPtr, que executa o QueryInterface em cada objeto para obter a interface IPolyCtl da interface IUnknown (armazenada na matriz m_ppUnk).

O código agora verifica se a configuração da Sides propriedade realmente funcionou. Se falhar, o código exibe uma caixa de mensagem exibindo detalhes de erro da IErrorInfo interface. Normalmente, um contêiner solicita um objeto para a ISupportErrorInfo interface e chama InterfaceSupportsErrorInfo primeiro, para determinar se o objeto suporta informações de erro de configuração. Você pode pular esta tarefa.

CComPtr ajuda a lidar automaticamente com a contagem de referências, para que não seja necessário invocar a interface com Release. CComBSTR ajuda-o com o processamento de BSTR, assim você não precisa fazer a chamada final SysFreeString. Você também usa uma das várias classes de conversão de cadeia de caracteres, para que você possa converter o BSTR se necessário (é por isso que a macro USES_CONVERSION está no início da função).

Você também precisa definir o sinalizador sujo da página de propriedades para indicar que o botão Aplicar deve estar ativado. Isso ocorre quando o usuário altera o valor na caixa de edição Lados .

Para manipular o botão Aplicar

1. No Modo de Exibição de Classe, clique CPolyProp com o botão direito do mouse e clique em Propriedades no menu de atalho.

2. Na janela Propriedades , clique no ícone Eventos .

3. Expanda o IDC_SIDES nó na lista de eventos.

4. Selecione EN_CHANGE, e, no menu suspenso à direita, clique em <Adicionar> OnEnChangeSides. A OnEnChangeSides declaração do manipulador será adicionada ao Polyprop.h e a implementação do manipulador ao Polyprop.cpp.

Em seguida, você modificará o manipulador.

Para modificar o método OnEnChangeSides

1. Adicione o seguinte código em Polyprop.cpp no método OnEnChangeSides (removendo qualquer código que o assistente tenha colocado lá):

   LRESULT CPolyProp::OnEnChangeSides(WORD /*wNotifyCode*/, WORD /*wID*/, 
      HWND /*hWndCtl*/, BOOL& /*bHandled*/)
   {
      SetDirty(TRUE);
   
      return 0;
   }
   

OnEnChangeSides será invocado quando uma WM_COMMAND mensagem for enviada com a EN_CHANGE notificação para o IDC_SIDES controlo. OnEnChangeSides em seguida, chama SetDirty e passa TRUE para indicar que a página de propriedades está suja e o botão Aplicar deve ser ativado.

Adicionando a página de propriedades ao controle

O modelo e o assistente ATL Property Page não adicionam a página de propriedades ao seu controle automaticamente, porque pode haver vários controles em seu projeto. Você precisará adicionar uma entrada ao mapa de propriedades do controle.

Para adicionar a página de propriedades

1. Abra PolyCtl.h e adicione estas linhas ao mapa de propriedades:

   PROP_ENTRY_TYPE("Sides", 1, CLSID_PolyProp, VT_INT)
   PROP_PAGE(CLSID_PolyProp)
   

O mapa de propriedades do controle agora tem esta aparência:

BEGIN_PROP_MAP(CPolyCtl)
   PROP_DATA_ENTRY("_cx", m_sizeExtent.cx, VT_UI4)
   PROP_DATA_ENTRY("_cy", m_sizeExtent.cy, VT_UI4)
#ifndef _WIN32_WCE
   PROP_ENTRY_TYPE("FillColor", DISPID_FILLCOLOR, CLSID_StockColorPage, VT_UI4)
#endif
   PROP_ENTRY_TYPE("Sides", 1, CLSID_PolyProp, VT_INT)
   PROP_PAGE(CLSID_PolyProp)
   // Example entries
   // PROP_ENTRY("Property Description", dispid, clsid)
   // PROP_PAGE(CLSID_StockColorPage)
END_PROP_MAP()

Você poderia ter adicionado uma macro PROP_PAGE com o CLSID da sua página de propriedade, mas se você usar a macro PROP_ENTRY como mostrado, o valor da propriedade Sides será também salvo quando o controlo for salvo.

Os três parâmetros para a macro são a descrição da propriedade, o DISPID da propriedade e o CLSID da página de propriedades que tem a propriedade nela. Isso é útil se, por exemplo, você carregar o controle no Visual Basic e definir o número de lados em tempo de design. Como o número de lados é salvo, quando você recarregar seu projeto do Visual Basic, o número de lados será restaurado.

Construindo e testando o controle

Agora crie esse controle e insira-o no Contêiner de Teste de Controle ActiveX. Em Test Container, no menu Editar , clique em PolyCtl Class Object. A página de propriedades aparece com as informações adicionadas.

O botão Aplicar está inicialmente desativado. Comece a digitar um valor na caixa Lados e o botão Aplicar será ativado. Depois de terminar de inserir o valor, clique no botão Aplicar . A exibição do controle é alterada e o botão Aplicar é desativado novamente. Tente inserir um valor inválido. Você verá uma caixa de mensagem contendo a descrição do erro que você definiu a partir da put_Sides função.

Em seguida, você colocará seu controle em uma página da Web.

Voltar ao Passo 5 | Rumo ao Passo 7

Ver também

Tutoriais