Partilhar via

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

Quando o utilizador clica com o botão direito do rato num membro de um tipo de ficheiro para exibir a ficha de propriedades, o Shell chama os manipuladores de ficha de propriedades registados para o tipo de ficheiro. Cada manipulador pode adicionar uma página personalizada à folha de propriedades padrão.

O que precisa de saber

Tecnologias

  • Concha

Pré-requisitos

  • Uma compreensão dos menus de atalho

Instruções

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

Além do registo normal do Component Object Model (COM), adicione uma subchave PropertySheetHandlers à subchave shellex da chave ProgID do aplicativo associado ao tipo de ficheiro. Crie uma subchave de PropertySheetHandlers com o nome do manipulador e defina o valor padrão para a forma de cadeia de caracteres do GUID do identificador de classe (CLSID) 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 suportar é 32. Para registar múltiplos manipuladores, crie uma chave sob a chave shellex para cada manipulador, com o valor predefinido definido no CLSID GUID 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 tipo de arquivo .myp de exemplo. 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 interfaceIShellPropSheetExt. Somente o método IShellPropSheetExt::AddPages precisa de uma implementação não token. O Shell não invoca 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 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. Em especial:
    • 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. Esta função é chamada quando a página é criada e quando está prestes a ser destruída.
  2. Crie o identificador HPAGE da página ao passar a estrutura PROPSHEETPAGE para a função CreatePropertySheetPage .
  3. Chame a função apontada por lpfnAddPage. Defina seu primeiro parâmetro para o identificador HPAGE que foi criado na etapa anterior. Defina seu segundo parâmetro para o lParam valor 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 chamadaPropSheetPageProc a pfnCallback, ela será chamada quando a página estiver prestes a ser destruída. O gestor pode então executar quaisquer operações de limpeza necessárias, como liberar as referências que ele mantenha.

O exemplo de código a seguir ilustra uma implementação simples de 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 de caixa de diálogo da página. A função PageDlgProc é o procedimento de caixa de diálogo que lida com 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

 

 

  • Last updated on