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

  • Artigo

Observação

O assistente de Provedor OLE DB da ATL não está disponível no Visual Studio 2019 e posteriores.

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

  • Criação do recurso de página de propriedades

  • Adição de código para criar e gerenciar a página de propriedades

  • Adição da página de propriedades ao controle

Criação do recurso de página de propriedades

Para adicionar uma página de propriedades ao seu controle, use o modelo Página de Propriedades da ATL.

Adição de 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>Página de Propriedades da ATL e clique em Adicionar.

  4. Quando o Assistente de Página de Propriedades da ATL for exibido, insira PolyProp como o nome curto.

  5. Clique em Cadeias de Caracteres para abrir a página Cadeias de Caracteres e insira &Polígono como o Título.

    O Título da página de propriedades é a cadeia de caracteres que aparece na guia para essa página. O Doc string é uma descrição que um quadro de propriedades usa para colocar uma dica de ferramenta ou linha de status. Observe que o quadro de propriedades padrão atualmente não usa essa cadeia de caracteres, portanto, você pode deixá-lo com o conteúdo padrão. Você não vai gerar um arquivo de Ajuda no momento, por isso, 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 seguintes são criados:

Arquivo Descrição
PolyProp.h Contém a classe C++ CPolyProp, que implementa a página de propriedades.
PolyProp.cpp Inclui o arquivo PolyProp.h.
PolyProp.rgs O script de registro que registra o objeto da página de propriedades.

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

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

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

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

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

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

Agora adicione os campos que você quer que apareça 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. Isso abrirá o Modo de Exibição de Recursos.

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

  3. Selecione esse rótulo e altere-o para Sides:, mudando o texto Legenda na janela Propriedades.

  4. Redimensione a caixa de rótulo para que o texto caiba nela.

  5. Arraste um Controle de Edição da Caixa de Ferramentas para a direita do rótulo.

  6. Por fim, altere a ID do controle de edição para IDC_SIDES usando a janela Propriedades.

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

Adição de código para criar e gerenciar a página de propriedades

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

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

Para modificar a função Aplicar para definir o número de lados

  1. Substitua a função Apply em PolyProp.h pelo 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 conectado a ela ao mesmo tempo, portanto, a função Apply executa loops e chama put_Sides em cada cliente com o valor recuperado da caixa de edição. Você está usando a classe CComQIPtr, que executa QueryInterface em cada objeto para obter a interface IPolyCtl da interface IUnknown (armazenada na matriz m_ppUnk).

O código agora verifica que a configuração da propriedade Sides funcionou. Em caso de falha, o código exibe uma caixa de mensagem mostrando detalhes do erro na interface IErrorInfo. Normalmente, um contêiner solicita um objeto para a interface ISupportErrorInfo e chama InterfaceSupportsErrorInfo primeiro, de modo a determinar se o objeto é compatível com a configuração de informações de erro. Você pode ignorar essa tarefa.

CComPtr ajuda você tratando automaticamente da contagem de referência, de modo que não seja preciso chamar Release na interface. CComBSTR ajuda com o processamento de BSTR, para que você não precise executar a chamada final a SysFreeString. Use também 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 anormal da página de propriedades para indicar que o botão Aplicar deve ser habilitado. Isso ocorre quando o usuário altera o valor na caixa de edição Lados.

Manipulação do botão Aplicar

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

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

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

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

Em seguida, você modificará o manipulador.

Modificação do método OnEnChangeSides

  1. Adicione o seguinte código em Polyprop.cpp ao método OnEnChangeSides (excluindo qualquer código colocado pelo assistente):

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

   return 0;
}

OnEnChangeSides será chamado quando uma mensagem WM_COMMAND for enviada com a notificação EN_CHANGE para o controle IDC_SIDES. Então, OnEnChangeSides chama SetDirty e passa TRUE para indicar que a página de propriedades agora está suja e o botão Aplicar deve ser habilitado.

Adição da página de propriedades ao controle

O modelo Página de Propriedades da ATL e o assistente não adicionam a página de propriedades ao controle para você automaticamente, pois pode haver vários controles em seu projeto. Você precisará adicionar uma entrada ao mapa de propriedade do controle.

Para adicionar a página de propriedades

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

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

O mapa de propriedade do controle agora se parece com isto:

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 a CLSID da sua página de propriedades, mas se usasse a macro PROP_ENTRY conforme mostrado, o valor da propriedade Sides também seria salvo quando o controle fosse salvo.

Os três parâmetros para a macro são a descrição da propriedade, a DISPID da propriedade e a CLSID da página de propriedades que tem a propriedade nela. Isso será ú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.

Compilação e teste do controle

Agora compile esse controle e insira-o no Contêiner de Teste do Controle ActiveX. No Contêiner de Teste, no menu Editar, clique em Objeto da Classe PolyCtl. A página de propriedades é exibida com as informações que você adicionou.

O botão Aplicar está inicialmente desabilitado. Comece a digitar um valor na caixa Lados e o botão Aplicar será habilitado. Depois de terminar de inserir o valor, clique no botão Aplicar. A exibição do controle muda, e o botão Aplicar volta a ficar desabilitado. Tente inserir um valor inválido. Você verá uma caixa de mensagem contendo a descrição do erro definida na função put_Sides.

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

Voltar para etapa 5 | Na etapa 7

Confira também

Tutorial