Compartir a través de

Cómo registrar e implementar un controlador de hoja de propiedades para un tipo de archivo

  • Artículo

Cuando el usuario hace clic con el botón derecho en un miembro de un tipo de archivo para mostrar la hoja de propiedades Properties, shell llama a los controladores de hoja de propiedades registrados para el tipo de archivo. Cada controlador puede agregar una página personalizada a la hoja de propiedades predeterminada.

Lo que necesita saber

Tecnologías

  • Shell

Requisitos previos

  • Descripción de los menús contextuales

Instrucciones

Paso 1: Registrar un controlador de hoja de propiedades para un tipo de archivo

Además del registro normal del modelo de objetos componentes (COM), agregue una subclave PropertySheetHandlers a la subclave shellex de la clave ProgID de la aplicación asociada al tipo de archivo. Cree una subclave de PropertySheetHandlers con el nombre del controlador y establezca el valor predeterminado en la forma de cadena del GUID del identificador de clase del controlador de hoja de propiedades (CLSID).

Para agregar más de una página a la hoja de propiedades, registre un controlador para cada página. El número máximo de páginas que una hoja de propiedades puede admitir es 32. Para registrar varios controladores, cree una clave en la clave shellex para cada controlador, con el valor predeterminado establecido en el GUID CLSID del controlador. No es necesario crear un objeto distinto para cada controlador, lo que significa que varios controladores pueden tener el mismo valor GUID. Las páginas se mostrarán en el orden en que sus claves se muestran en shellex.

En el ejemplo siguiente se muestra una entrada del Registro que habilita dos controladores de extensión de hoja de propiedades para un tipo de archivo .myp de ejemplo. En este ejemplo, se usa un objeto independiente para cada página, pero también se puede usar un solo objeto 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}

Paso 2: Implementar un controlador de hoja de propiedades para un tipo de archivo

Además de la implementación general que se describe en Cómo funcionan los controladores de hojas de propiedades, un controlador de hoja de propiedades para un tipo de archivo también debe tener una implementación adecuada de la interfaz IShellPropSheetExt . Solo el método IShellPropSheetExt::AddPages necesita una implementación distinta de . Shell no llama a IShellPropSheetExt::ReplacePage.

El método IShellPropSheetExt::AddPages permite que un controlador de hoja de propiedades agregue una página a una hoja de propiedades. El método tiene dos parámetros de entrada. La primera, lpfnAddPage, es un puntero a una función de devolución de llamada AddPropSheetPageProc que se usa para proporcionar al Shell la información necesaria para agregar la página a la hoja de propiedades. El segundo, lParam, es un valor definido por Shell que el controlador no procesa. Simplemente se pasa al Shell cuando se llama a la función de devolución de llamada.

El procedimiento general para implementar AddPages es el siguiente.

Implementación del método AddPages

  1. Asigne los valores adecuados a los miembros de una estructura PROPSHEETPAGE . En concreto:
    • Asigne la variable que contiene el recuento de referencias del controlador al miembro pcRefParent . Esta práctica impide que el objeto de controlador se descargue mientras se sigue mostrando la hoja de propiedades.
    • También puede implementar una función de devolución de llamada PropSheetPageProc y asignar su puntero a un miembro pfnCallback . Se llama a esta función cuando se crea la página y cuando está a punto de destruirse.
  2. Cree el identificador HPAGE de la página pasando la estructura PROPSHEETPAGE a la función CreatePropertySheetPage .
  3. Llame a la función a la que apunta lpfnAddPage. Establezca su primer parámetro en el identificador HPAGE que se creó en el paso anterior. Establezca su segundo parámetro en el valor lParam que se pasó a AddPages por shell.
  4. Los mensajes asociados a la página se pasarán al procedimiento del cuadro de diálogo que se asignó al miembro pfnDlgProc de la estructura PROPSHEETPAGE .
  5. Si asignó una función de devolución de llamada PropSheetPageProc a pfnCallback, se llamará cuando la página esté a punto de destruirse. Después, el controlador puede realizar las operaciones de limpieza necesarias, como liberar las referencias que contenga.

En el ejemplo de código siguiente se muestra una implementación simple 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;
}

La variable g_hInst es el identificador de instancia del archivo DLL y IDD_PAGEDLG es el identificador de recurso de la plantilla del cuadro de diálogo de la página. La función PageDlgProc es el procedimiento del cuadro de diálogo que controla los mensajes de la página. La variable g_DllRefCount contiene el recuento de referencias del objeto. El método AddPages llama a AddRef para incrementar el recuento. Sin embargo, la función de devolución de llamada libera el recuento de referencias, PageCallbackProc, cuando la página está a punto de destruirse.

Comentarios

Para obtener una explicación general sobre cómo registrar controladores de extensión de Shell, consulte Creación de controladores de extensión de Shell.

IShellPropSheetExt