Share via

Comment inscrire et implémenter un gestionnaire de feuille de propriétés pour un type de fichier

  • Article

Lorsque l’utilisateur clique avec le bouton droit sur un membre d’un type de fichier pour afficher la feuille de propriétés, l’interpréteur de commandes appelle les gestionnaires de feuille de propriétés inscrits pour le type de fichier. Chaque gestionnaire peut ajouter une page personnalisée à la feuille de propriétés par défaut.

Bon à savoir

Technologies

  • Shell

Prérequis

  • Compréhension des menus contextuels

Instructions

Étape 1 : Inscription d’un gestionnaire de feuilles de propriétés pour un type de fichier

En plus de l’inscription com (Component Object Model) normale, ajoutez une sous-clé PropertySheetHandlers à la sous-clé shellex de la clé ProgID de l’application associée au type de fichier. Créez une sous-clé de PropertySheetHandlers avec le nom du gestionnaire et définissez la valeur par défaut sur la forme de chaîne du GUID CLSID (Identificateur de classe) du gestionnaire de feuilles de propriétés.

Pour ajouter plusieurs pages à la feuille de propriétés, inscrivez un gestionnaire pour chaque page. Le nombre maximal de pages qu’une feuille de propriétés peut prendre en charge est de 32. Pour inscrire plusieurs gestionnaires, créez une clé sous la clé shellex pour chaque gestionnaire, avec la valeur par défaut définie sur le GUID CLSID du gestionnaire. Il n’est pas nécessaire de créer un objet distinct pour chaque gestionnaire, ce qui signifie que plusieurs gestionnaires peuvent tous avoir la même valeur GUID. Les pages s’affichent dans l’ordre dans lequel leurs clés sont répertoriées sous shellex.

L’exemple suivant illustre une entrée de Registre qui active deux gestionnaires d’extension de feuille de propriétés pour un exemple de type de fichier .myp. Dans cet exemple, un objet distinct est utilisé pour chaque page, mais un seul objet peut également être utilisé pour les deux.

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}

Étape 2 : Implémentation d’un gestionnaire de feuilles de propriétés pour un type de fichier

En plus de l’implémentation générale décrite dans Fonctionnement des gestionnaires de feuilles de propriétés, un gestionnaire de feuilles de propriétés pour un type de fichier doit également disposer d’une implémentation appropriée de l’interface IShellPropSheetExt . Seule la méthode IShellPropSheetExt::AddPages a besoin d’une implémentation non automatique. L’interpréteur de commandes n’appelle pas IShellPropSheetExt::ReplacePage.

La méthode IShellPropSheetExt::AddPages permet à un gestionnaire de feuille de propriétés d’ajouter une page à une feuille de propriétés. La méthode a deux paramètres d’entrée. Le premier, lpfnAddPage, est un pointeur vers une fonction de rappel AddPropSheetPageProc utilisée pour fournir à l’interpréteur de commandes les informations nécessaires pour ajouter la page à la feuille de propriétés. La deuxième, lParam, est une valeur définie par l’interpréteur de commandes qui n’est pas traitée par le gestionnaire. Elle est simplement renvoyée à l’interpréteur de commandes lorsque la fonction de rappel est appelée.

La procédure générale d’implémentation d’AddPages est la suivante.

Implémentation de la méthode AddPages

  1. Affectez les valeurs appropriées aux membres d’une structure PROPSHEETPAGE . En particulier :
    • Attribuez la variable qui contient le nombre de références du gestionnaire au membre pcRefParent . Cette pratique empêche le déchargement de l’objet gestionnaire pendant que la feuille de propriétés est toujours affichée.
    • Vous pouvez également implémenter une fonction de rappel PropSheetPageProc et affecter son pointeur à un membre pfnCallback . Cette fonction est appelée lorsque la page est créée et qu’elle est sur le point d’être détruite.
  2. Créez le handle HPAGE de la page en passant la structure PROPSHEETPAGE à la fonction CreatePropertySheetPage .
  3. Appelez la fonction vers laquelle est pointé lpfnAddPage. Définissez son premier paramètre sur le handle HPAGE qui a été créé à l’étape précédente. Définissez son deuxième paramètre sur la valeur lParam qui a été transmise à AddPages par l’interpréteur de commandes.
  4. Tous les messages associés à la page seront passés à la procédure de boîte de dialogue qui a été affectée au membre pfnDlgProc de la structure PROPSHEETPAGE .
  5. Si vous avez affecté une fonction de rappel PropSheetPageProc à pfnCallback, elle sera appelée lorsque la page est sur le point d’être détruite. Votre gestionnaire peut ensuite effectuer toutes les opérations de nettoyage nécessaires, telles que la libération des références qu’il contient.

L’exemple de code suivant illustre une implémentation AddPages simple.

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 est le handle instance de la DLL, et IDD_PAGEDLG est l’ID de ressource du modèle de boîte de dialogue de la page. La fonction PageDlgProc est la procédure de boîte de dialogue qui gère les messages de la page. La variable g_DllRefCount contient le nombre de références de l’objet. La méthode AddPages appelle AddRef pour incrémenter le nombre. Toutefois, le nombre de références est libéré par la fonction de rappel PageCallbackProc lorsque la page est sur le point d’être détruite.

Notes

Pour une présentation générale de l’inscription des gestionnaires d’extensions Shell, consultez Création de gestionnaires d’extensions Shell.

IShellPropSheetExt