Compartilhar via

Como registrar e implementar um manipulador de folha de propriedades para um tipo de arquivo

  • Artigo

Quando o usuário clica com o botão direito do mouse em um membro de um tipo de arquivo para exibir a folha de propriedades Propriedades, o Shell chama os manipuladores de folha de propriedades registrados para o tipo de arquivo. Cada manipulador pode adicionar uma página personalizada à folha de propriedades padrão.

O que você precisa saber

Tecnologias

  • Shell

Pré-requisitos

  • Uma compreensão dos menus de atalho

Instruções

Etapa 1: registrar um manipulador de folha de propriedades para um tipo de arquivo

Além do registro normal do COM (Component Object Model), adicione uma subchave PropertySheetHandlers à subchave shellex da chave ProgID do aplicativo associado ao tipo de arquivo. Crie uma subchave de PropertySheetHandlers com o nome do manipulador e defina o valor padrão como a forma de cadeia de caracteres do GUID clsid (identificador de classe) do manipulador de folha de propriedades.

Para adicionar mais de uma página à folha de propriedades, registre um manipulador para cada página. O número máximo de páginas que uma folha de propriedades pode dar suporte é 32. Para registrar vários manipuladores, crie uma chave sob a chave shellex para cada manipulador, com o valor padrão definido como o GUID CLSID do manipulador. Não é necessário criar um objeto distinto para cada manipulador, o que significa que vários manipuladores podem ter o mesmo valor guid. As páginas serão exibidas na ordem em que suas chaves estão listadas em shellex.

O exemplo a seguir ilustra uma entrada do Registro que habilita dois manipuladores de extensão de folha de propriedades para um exemplo de tipo de arquivo .myp. Neste exemplo, um objeto separado é usado para cada página, mas um único objeto também pode ser usado para ambos.

HKEY_CLASSES_ROOT
   .myp
      (Default) = MyProgram.1
   CLSID
      {Page 1 Property Sheet Handler CLSID GUID}
         InProcServer32
            (Default) = C:\MyDir\MyPropSheet1.dll
            ThreadingModel = Apartment
      {Page 2 Property Sheet Handler CLSID GUID}
         InProcServer32
            (Default) = C:\MyDir\MyPropSheet2.dll
            ThreadingModel = Apartment
   MyProgram.1
      (Default) = MyProgram Application
      shellex
         PropertySheetHandlers
            MyPropSheet1
               (Default) = {Page1 Property Sheet Handler CLSID GUID}
            MyPropSheet2
               (Default) = {Page2 Property Sheet Handler CLSID GUID}

Etapa 2: Implementando um manipulador de folha de propriedades para um tipo de arquivo

Além da implementação geral discutida em How Property Sheet Handlers Work, um manipulador de folha de propriedades para um tipo de arquivo também deve ter uma implementação apropriada da interface IShellPropSheetExt . Somente o método IShellPropSheetExt::AddPages precisa de uma implementação nontoken. O Shell não chama IShellPropSheetExt::ReplacePage.

O método IShellPropSheetExt::AddPages permite que um manipulador de folha de propriedades adicione uma página a uma folha de propriedades. O método tem dois parâmetros de entrada. O primeiro, lpfnAddPage, é um ponteiro para uma função de retorno de chamada AddPropSheetPageProc que é usada para fornecer ao Shell as informações necessárias para adicionar a página à folha de propriedades. O segundo, lParam, é um valor definido pelo Shell que não é processado pelo manipulador. Ele é simplesmente passado de volta para o Shell quando a função de retorno de chamada é chamada.

O procedimento geral para implementar AddPages é o seguinte.

Implementando o método AddPages

  1. Atribua valores apropriados aos membros de uma estrutura PROPSHEETPAGE . Especialmente:
    • Atribua a variável que contém a contagem de referência do manipulador ao membro pcRefParent . Essa prática impede que o objeto manipulador seja descarregado enquanto a folha de propriedades ainda está sendo exibida.
    • Você também pode implementar uma função de retorno de chamada PropSheetPageProc e atribuir seu ponteiro a um membro pfnCallback . Essa função é chamada quando a página é criada e quando está prestes a ser destruída.
  2. Crie o identificador HPAGE da página passando a estrutura PROPSHEETPAGE para a função CreatePropertySheetPage .
  3. Chame a função que é apontada por lpfnAddPage. Defina seu primeiro parâmetro como o identificador HPAGE que foi criado na etapa anterior. Defina seu segundo parâmetro como o valor lParam que foi passado para AddPages pelo Shell.
  4. Todas as mensagens associadas à página serão passadas para o procedimento da caixa de diálogo que foi atribuído ao membro pfnDlgProc da estrutura PROPSHEETPAGE .
  5. Se você atribuiu uma função de retorno de chamada PropSheetPageProc ao pfnCallback, ela será chamada quando a página estiver prestes a ser destruída. Em seguida, o manipulador pode executar todas as operações de limpeza necessárias, como liberar todas as referências que ele contém.

O exemplo de código a seguir ilustra uma implementação simples do AddPages .

STDMETHODIMP CShellPropSheetExt::AddPages(LPFNADDPROPSHEETPAGE, lpfnAddPage, LPARAM lParam)
{
    PROPSHEETPAGE  psp;
    HPROPSHEETPAGE hPage;

    psp.dwSize        = sizeof(psp);
    psp.dwFlags       = PSP_USEREFPARENT | PSP_USETITLE | PSP_USECALLBACK;
    psp.hInstance     = g_hInst;
    psp.pszTemplate   = MAKEINTRESOURCE(IDD_PAGEDLG);
    psp.hIcon         = 0;
    psp.pszTitle      = TEXT("Extension Page");
    psp.pfnDlgProc    = (DLGPROC)PageDlgProc;
    psp.pcRefParent   = &g_DllRefCount;
    psp.pfnCallback   = PageCallbackProc;
    psp.lParam        = (LPARAM)this;

    hPage = CreatePropertySheetPage(&psp);
            
    if(hPage) 
    {
        if(lpfnAddPage(hPage, lParam))
        {
            this->AddRef();
            return S_OK;
        }
        else
        {
            DestroyPropertySheetPage(hPage);
        }
    }
    else
    {
        return E_OUTOFMEMORY;
    }
    return E_FAIL;
}

A variável g_hInst é o identificador de instância para a DLL e IDD_PAGEDLG é a ID do recurso do modelo da caixa de diálogo da página. A função PageDlgProc é o procedimento da caixa de diálogo que manipula as mensagens da página. A variável g_DllRefCount contém a contagem de referência do objeto. O método AddPages chama AddRef para incrementar a contagem. No entanto, a contagem de referência é liberada pela função de retorno de chamada , PageCallbackProc, quando a página está prestes a ser destruída.

Comentários

Para obter uma discussão geral sobre como registrar manipuladores de extensão do Shell, consulte Criando manipuladores de extensão do shell.

IShellPropSheetExt