Registrieren und Implementieren eines Eigenschaftenblatthandlers für einen Dateityp

  • Artikel

Wenn der Benutzer mit der rechten Maustaste auf ein Element eines Dateityps klickt, um das Eigenschaftenfenster Eigenschaften anzuzeigen, ruft die Shell die Eigenschaftenblatthandler auf, die für den Dateityp registriert sind. Jeder Handler kann dem Standardeigenschaftenblatt eine benutzerdefinierte Seite hinzufügen.

Wichtige Informationen

Technologien

  • Shell

Voraussetzungen

  • Verständnis von Kontextmenüs

Anweisungen

Schritt 1: Registrieren eines Eigenschaftenblatthandlers für einen Dateityp

Fügen Sie zusätzlich zur normalen COM-Registrierung (Component Object Model) dem Unterschlüssel shellex des ProgID-Schlüssels der anwendung, die dem Dateityp zugeordnet ist, einen PropertySheetHandlers-Unterschlüssel hinzu. Erstellen Sie einen Unterschlüssel von PropertySheetHandlers mit dem Namen des Handlers, und legen Sie den Standardwert auf die Zeichenfolgenform der CLSID-GUID (Class Identifier) des Eigenschaftenblatthandlers fest.

Um dem Eigenschaftenblatt mehrere Seiten hinzuzufügen, registrieren Sie einen Handler für jede Seite. Die maximale Anzahl von Seiten, die ein Eigenschaftenblatt unterstützen kann, ist 32. Um mehrere Handler zu registrieren, erstellen Sie einen Schlüssel unter dem shellex-Schlüssel für jeden Handler, wobei der Standardwert auf die CLSID-GUID des Handlers festgelegt ist. Es ist nicht erforderlich, für jeden Handler ein eigenes Objekt zu erstellen, was bedeutet, dass mehrere Handler den gleichen GUID-Wert aufweisen können. Die Seiten werden in der Reihenfolge angezeigt, in der ihre Schlüssel unter shellex aufgeführt sind.

Im folgenden Beispiel wird ein Registrierungseintrag veranschaulicht, der zwei Eigenschaftenblatterweiterungshandler für einen Beispiel-MYP-Dateityp aktiviert. In diesem Beispiel wird für jede Seite ein separates Objekt verwendet, aber auch ein einzelnes Objekt kann für beides verwendet werden.

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}

Schritt 2: Implementieren eines Eigenschaftenblatthandlers für einen Dateityp

Zusätzlich zur allgemeinen Implementierung, die unter Funktionsweise von Eigenschaftenblatthandlern erläutert wird, muss ein Eigenschaftenblatthandler für einen Dateityp auch über eine geeignete Implementierung der IShellPropSheetExt-Schnittstelle verfügen. Nur die IShellPropSheetExt::AddPages-Methode benötigt eine Nichttokenimplementierung. IShellPropSheetExt::ReplacePage wird von der Shell nicht aufgerufen.

Die IShellPropSheetExt::AddPages-Methode ermöglicht einem Eigenschaftenblatthandler das Hinzufügen einer Seite zu einem Eigenschaftenblatt. Die -Methode verfügt über zwei Eingabeparameter. Die erste, lpfnAddPage, ist ein Zeiger auf eine AddPropSheetPageProc-Rückruffunktion , die verwendet wird, um der Shell die Informationen bereitzustellen, die zum Hinzufügen der Seite zum Eigenschaftenblatt erforderlich sind. Der zweite Wert, lParam, ist ein shelldefinierter Wert, der vom Handler nicht verarbeitet wird. Sie wird einfach an die Shell zurückgegeben, wenn die Rückruffunktion aufgerufen wird.

Das allgemeine Verfahren für die Implementierung von AddPages sieht wie folgt aus.

Implementieren der AddPages-Methode

  1. Weisen Sie den Membern einer PROPSHEETPAGE-Struktur geeignete Werte zu. Dies gilt insbesondere für:
    • Weisen Sie dem pcRefParent-Member die Variable zu, die die Verweisanzahl des Handlers enthält. Diese Vorgehensweise verhindert, dass das Handlerobjekt entladen wird, während das Eigenschaftenblatt weiterhin angezeigt wird.
    • Sie können auch eine PropSheetPageProc-Rückruffunktion implementieren und ihren Zeiger einem pfnCallback-Member zuweisen. Diese Funktion wird aufgerufen, wenn die Seite erstellt wird und wenn sie zerstört werden soll.
  2. Erstellen Sie das HPAGE-Handle der Seite, indem Sie die PROPSHEETPAGE-Struktur an die CreatePropertySheetPage-Funktion übergeben.
  3. Rufen Sie die Funktion auf, auf die von lpfnAddPage verwiesen wird. Legen Sie den ersten Parameter auf das HPAGE-Handle fest, das im vorherigen Schritt erstellt wurde. Legen Sie den zweiten Parameter auf den lParam-Wert fest, der von der Shell an AddPages übergeben wurde.
  4. Alle der Seite zugeordneten Nachrichten werden an die Dialogfeldprozedur übergeben, die dem element pfnDlgProc der PROPSHEETPAGE-Struktur zugewiesen wurde.
  5. Wenn Sie pfnCallback eine PropSheetPageProc-Rückruffunktion zugewiesen haben, wird sie aufgerufen, wenn die Seite im Begriff ist, zerstört zu werden. Ihr Handler kann dann alle erforderlichen Bereinigungsvorgänge ausführen, z. B. das Freigeben aller darin enthaltenen Verweise.

Das folgende Codebeispiel veranschaulicht eine einfache AddPages-Implementierung .

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;
}

Die g_hInst Variable ist das instance-Handle für die DLL, und IDD_PAGEDLG ist die Ressourcen-ID der Dialogfeldvorlage der Seite. Die PageDlgProc-Funktion ist die Dialogfeldprozedur, die die Nachrichten der Seite verarbeitet. Die g_DllRefCount Variable enthält die Verweisanzahl des Objekts. Die AddPages-Methode ruft AddRef auf, um die Anzahl zu erhöhen. Die Verweisanzahl wird jedoch von der Rückruffunktion PageCallbackProc freigegeben, wenn die Seite gerade zerstört wird.

Bemerkungen

Eine allgemeine Erläuterung zum Registrieren von Shell-Erweiterungshandlern finden Sie unter Erstellen von Shell-Erweiterungshandlern.

IShellPropSheetExt