Come registrare e implementare un gestore della finestra delle proprietà per un tipo di file

Quando si fa clic con il tasto destro su un membro di un tipo di file per visualizzare la finestra delle proprietà, la Shell chiama i gestori del foglio delle proprietà registrati per il tipo di file. Ogni gestore può aggiungere una pagina personalizzata alla finestra delle proprietà predefinita.

Cosa è necessario sapere

Tecnologie

• Shell

Prerequisiti

• Conoscenza dei menu di scelta rapida

Disposizioni

Passaggio 1: Registrazione di un gestore della finestra delle proprietà per un tipo di file

Oltre alla normale registrazione COM (Component Object Model), aggiungere una sottochiave PropertySheetHandlers alla sottochiave shellex della chiave ProgID dell'applicazione associata al tipo di file. Creare una sottochiave di PropertySheetHandlers con il nome del gestore e impostare il valore predefinito sul formato stringa dell'identificatore di classe (CLSID) GUID del gestore delle proprietà.

Per aggiungere più pagine alla finestra delle proprietà, registrare un gestore per ogni pagina. Il numero massimo di pagine supportate da una finestra delle proprietà è 32. Per registrare più gestori, creare una chiave sotto la chiave shellex per ogni gestore, con il valore predefinito impostato sul GUID CLSID del gestore. Non è necessario creare un oggetto distinto per ogni gestore, il che significa che più gestori possono avere lo stesso valore GUID. Le pagine verranno visualizzate nell'ordine in cui le relative chiavi sono elencate in shellex.

Nell'esempio seguente viene illustrata una voce del Registro di sistema che abilita due gestori di estensione della finestra delle proprietà per un tipo di file myp di esempio. In questo esempio viene usato un oggetto separato per ogni pagina, ma un singolo oggetto può essere usato anche per entrambi.

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}

Passaggio 2: Implementazione di un gestore della finestra delle proprietà per un tipo di file

Oltre all'implementazione generale descritta in Come funzionano i gestori delle finestre delle proprietà, un gestore della finestra delle proprietà per un tipo di file deve avere anche un'implementazione appropriata dell'interfaccia di IShellPropSheetExt. Solo il metodo IShellPropSheetExt::AddPages richiede un'implementazione non token. Lo Shell non chiama IShellPropSheetExt::ReplacePage.

Il metodo IShellPropSheetExt::AddPages consente a un gestore della finestra delle proprietà di aggiungere una pagina a una finestra delle proprietà. Il metodo ha due parametri di input. Il primo, lpfnAddPage, è un puntatore a una funzione di callback AddPropSheetPageProc utilizzata per fornire alla Shell le informazioni necessarie per aggiungere la pagina alla finestra delle proprietà. Il secondo, lParam, è un valore definito dalla shell che non viene elaborato dal gestore. Viene semplicemente passato alla shell quando viene chiamata la funzione di callback.

La procedura generale per l'implementazione di AddPages è la seguente.

Implementazione del metodo AddPages

1. Assegnare valori appropriati ai membri di una struttura PROPSHEETPAGE. Soprattutto:
   • Assegnare la variabile che contiene il conteggio dei riferimenti del gestore al membro pcRefParent. Questa procedura impedisce che l'oggetto gestore venga scaricato mentre la finestra delle proprietà è ancora visualizzata.
   • È anche possibile implementare un PropSheetPageProc funzione di callback e assegnarne il puntatore a un membro pfnCallback. Questa funzione viene chiamata quando viene creata la pagina e quando sta per essere eliminata definitivamente.
2. Creare l'handle HPAGE della pagina passando la struttura PROPSHEETPAGE alla funzione CreatePropertySheetPage.
3. Chiamate la funzione indicata da lpfnAddPage. Impostare il primo parametro sull'handle HPAGE creato nel passaggio precedente. Impostare il secondo parametro sul valore lParam passato a AddPages da Shell.
4. Tutti i messaggi associati alla pagina verranno passati alla routine della finestra di dialogo assegnata al membro pfnDlgProc della struttura PROPSHEETPAGE.
5. Se è stata assegnata una PropSheetPageProc funzione di callback a pfnCallback, verrà chiamata quando la pagina sta per essere distrutta. Il gestore può quindi eseguire qualsiasi operazione di pulizia necessaria, ad esempio rilasciando tutti i riferimenti contenuti.

L'esempio di codice seguente illustra una semplice implementazione di 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 variabile g_hInst è l'handle di istanza della DLL e IDD_PAGEDLG è l'ID della risorsa del modello di finestra di dialogo della pagina. La funzione PageDlgProc è la routine della finestra di dialogo che gestisce i messaggi della pagina. La variabile g_DllRefCount contiene il conteggio dei riferimenti dell'oggetto. Il metodo AddPages chiama AddRef per incrementare il conteggio. Tuttavia, il conteggio dei riferimenti viene rilasciato dalla funzione di callback, PageCallbackProc, quando la pagina sta per essere eliminata definitivamente.

Osservazioni

Per una discussione generale su come registrare i gestori di estensione shell, vedere Creazione di gestori estensione shell.

Argomenti correlati

IShellPropSheetExt