À propos des feuilles de propriétés

Une feuille de propriétés est une fenêtre qui permet à l’utilisateur d’afficher et de modifier les propriétés d’un élément. Par exemple, une application de feuille de calcul peut utiliser une feuille de propriétés pour permettre à l’utilisateur de définir les propriétés de police et de bordure d’une cellule ou d’afficher et définir les propriétés d’un appareil, comme un lecteur de disque, une imprimante ou une souris.

Cette section traite des rubriques suivantes.

• Informations de base de la feuille de propriétés
• Boîtes de dialogue Feuille de propriétés
• Pages
• Création d’une feuille de propriétés
• Ajout et suppression de pages
• Titre de la feuille de propriétés et étiquettes de page
• Page Activation
• Bouton Aide
  • Suppression du bouton d’aide de la barre de légende
• Boutons OK, Annuler et Appliquer
• Assistants

Informations de base de la feuille de propriétés

Pour implémenter des feuilles de propriétés dans votre application, incluez le fichier d’en-tête Prsht.h dans votre projet. Prsht.h contient tous les identificateurs utilisés avec les feuilles de propriétés.

Une feuille de propriétés contient une ou plusieurs fenêtres enfants qui se chevauchent appelées pages, chacune contenant des fenêtres de contrôle pour définir un groupe de propriétés associées. Par exemple, une page peut contenir les contrôles permettant de définir les propriétés de police d’un élément, y compris le style de type, la taille de point, la couleur, etc. Chaque page a un onglet que l’utilisateur peut sélectionner pour placer la page au premier plan de la feuille de propriétés. Par exemple, l’application de panneau de configuration Date-Time affiche la feuille de propriétés suivante.

Une feuille de propriétés standard avec plusieurs pages à onglets permet à l’utilisateur d’accéder de manière aléatoire à toutes les propriétés. S’il est plus approprié d’avoir des propriétés définies dans l’ordre, vous pouvez utiliser un Assistant.

Boîtes de dialogue Feuille de propriétés

Une feuille de propriétés et les pages qu’elle contient sont en fait des boîtes de dialogue. La feuille de propriétés est une boîte de dialogue définie par le système qui gère les pages et leur fournit un conteneur commun. Une boîte de dialogue de feuille de propriétés peut être modale ou sans mode. Il comprend un cadre, une barre de titre et quatre boutons : OK, Annuler, Appliquer et (éventuellement) Aide. Les procédures de boîte de dialogue pour les pages reçoivent des codes de notification sous la forme de messages WM_NOTIFY lorsque l’utilisateur clique sur les boutons.

Notes

Toutes les informations de cette section ne s’appliquent pas aux Assistants, qui ont une apparence et un comportement quelque peu différents. Par exemple, les Assistants ont un ensemble différent de boutons et aucun onglet. Pour plus d’informations, consultez Création d’Assistants.

Chaque page d’une feuille de propriétés est une boîte de dialogue sans mode définie par l’application qui gère les fenêtres de contrôle utilisées pour afficher et modifier les propriétés d’un élément. Vous fournissez le modèle de boîte de dialogue utilisé pour créer chaque page, ainsi que la procédure de boîte de dialogue qui gère les contrôles et définit les propriétés de l’élément correspondant.

Une feuille de propriétés envoie des codes de notification à la procédure de boîte de dialogue pour une page lorsque la page obtient ou perd l’activation et lorsque l’utilisateur clique sur le bouton OK, Annuler, Appliquer ou Aide . Les notifications sont envoyées sous forme de messages WM_NOTIFY . Le paramètre lParam est l’adresse d’une structure NMHDR qui inclut le handle de fenêtre dans la boîte de dialogue feuille de propriétés.

Certains codes de notification nécessitent qu’une page retourne TRUE ou FALSE en réponse au message WM_NOTIFY . Pour ce faire, la page doit utiliser la fonction SetWindowLong pour définir la valeur DWL_MSGRESULT de la boîte de dialogue de page sur TRUE ou FALSE.

Pages

Une feuille de propriétés doit contenir au moins une page, mais elle ne peut pas contenir plus que la valeur de MAXPROPPAGES telle que définie dans les fichiers d’en-tête Windows. Chaque page a un index de base zéro que la feuille de propriétés attribue en fonction de l’ordre dans lequel la page est ajoutée à la feuille de propriétés. Les index sont utilisés dans les messages que vous envoyez à la feuille de propriétés.

Une page de propriétés peut contenir une boîte de dialogue imbriquée. Si c’est le cas, vous devez inclure le style WS_EX_CONTROLPARENT pour la boîte de dialogue de niveau supérieur et appeler la fonction IsDialogMessage avec le handle à la boîte de dialogue parente. Cela garantit que l’utilisateur peut utiliser des mnémoniques et les touches de navigation de la boîte de dialogue pour déplacer le focus vers les contrôles de la boîte de dialogue imbriquée.

Chaque page a une icône et une étiquette correspondantes. La feuille de propriétés crée un onglet pour chaque page et affiche l’icône et l’étiquette dans l’onglet. Toutes les pages de feuille de propriétés doivent utiliser une police nonbold. Pour vous assurer que la police n’est pas en gras, spécifiez le style DS_3DLOOK dans le modèle de boîte de dialogue.

La procédure de boîte de dialogue d’une page ne doit pas appeler la fonction EndDialog . Cela détruira l’intégralité de la feuille de propriétés, pas seulement la page.

La taille minimale d’une page de feuille de propriétés est de 212 unités de dialogue horizontalement et de 114 unités de dialogue verticalement. Si une boîte de dialogue de page est plus petite que celle-ci, la page est agrandie jusqu’à ce qu’elle atteigne la taille minimale. Le fichier d’en-tête Prsht.h contient trois ensembles de tailles recommandées pour les pages de feuille de propriétés, comme indiqué dans le tableau suivant.

Taille	Description
PROP_SM_CXDLG	Largeur, en unités de dialogue, d’une petite page de feuille de propriétés.
PROP_SM_CYDLG	Hauteur, en unités de dialogue, d’une petite page de feuille de propriétés.
PROP_MED_CXDLG	Largeur, en unités de dialogue, d’une page de feuille de propriétés de taille moyenne.
PROP_MED_CYDLG	Hauteur, en unités de boîte de dialogue, d’une page de feuille de propriétés de taille moyenne.
PROP_LG_CXDLG	Largeur, en unités de dialogue, d’une grande page de feuille de propriétés.
PROP_LG_CYDLG	Hauteur, en unités de boîte de dialogue, d’une grande page de feuille de propriétés.

L’utilisation de ces tailles recommandées permet de garantir la cohérence visuelle entre votre application et d’autres applications Microsoft Windows.

Dans l’éditeur de ressources Microsoft Visual Studio, vous pouvez créer une page de la taille appropriée dans la boîte de dialogue Ajouter une ressource . Développez le nœud Boîte de dialogue et sélectionnez IDD_PROPPAGE_LARGE, IDD_PROPPAGE_MEDIUM ou IDD_PROPPAGE_SMALL.

La feuille de propriétés est automatiquement dimensionnée pour prendre en charge la plus grande page.

Création d’une feuille de propriétés

Avant de créer une feuille de propriétés, vous devez définir une ou plusieurs pages. Cela implique de remplir une structure PROPSHEETPAGE avec des informations sur la page (icône, étiquette, modèle de boîte de dialogue, procédure de boîte de dialogue, etc.), puis de spécifier l’adresse de la structure dans un appel à la fonction CreatePropertySheetPage . La fonction retourne un handle au type HPROPSHEETPAGE qui identifie la page de manière unique.

Pour créer une feuille de propriétés, vous spécifiez l’adresse d’une structure PROPSHEETHEADER dans un appel à la fonction PropertySheet . La structure définit l’icône et le titre de la feuille de propriétés et inclut également l’adresse d’un tableau de handles HPROPSHEETPAGE que vous obtenez à l’aide de CreatePropertySheetPage. Lorsque PropertySheet crée la feuille de propriétés, elle inclut les pages identifiées dans le tableau. Les pages apparaissent dans la feuille de propriétés dans le même ordre qu’elles sont contenues dans le tableau.

Une autre façon d’affecter des pages à une feuille de propriétés consiste à spécifier un tableau de structures PROPSHEETPAGE au lieu d’un tableau de handles HPROPSHEETPAGE . Dans ce cas, PropertySheet crée des handles pour les pages avant de les ajouter à la feuille de propriétés.

Lorsqu’une page est créée, sa procédure de boîte de dialogue reçoit un message WM_INITDIALOG . Le paramètre lParam du message est un pointeur vers une copie de la structure PROPSHEETPAGE définie lors de la création de la page. En particulier, lorsqu’une page est créée, le membre lParam de la structure peut être utilisé pour passer des informations définies par l’application à la procédure de boîte de dialogue. À l’exception du membre lParam , cette structure doit être traitée en lecture seule. La modification d’un élément autre que lParam aura des conséquences imprévisibles.

Lorsque le système transmet par la suite une copie de la structure PROPSHEETPAGE de la page à votre application, il utilise le même pointeur. Toutes les modifications apportées à la structure seront transmises. Étant donné que le membre lParam est ignoré par le système, il peut être modifié pour envoyer des informations à d’autres parties de votre application. Vous pouvez, par instance, utiliser lParam pour transmettre des informations à la fonction de rappel PropSheetPageProc de la page.

PropertySheet définit automatiquement la taille et la position initiale d’une feuille de propriétés. La position est basée sur la position de la fenêtre propriétaire, et la taille est basée sur la plus grande page spécifiée dans le tableau de pages lors de la création de la feuille de propriétés. Si vous souhaitez que les pages correspondent à la largeur des quatre boutons en bas de la feuille de propriétés, définissez la largeur de la page la plus large sur 190 unités de boîte de dialogue.

La taille d’une feuille de propriétés est calculée à partir des propriétés width et height du modèle de boîte de dialogue dans le fichier de ressources. Pour plus d’informations, consultez Ressource DIALOG ou Ressource DIALOGEX . Notez toutefois que, pour des raisons de compatibilité, les dimensions sont calculées par rapport à la police MS Shell Dlg plutôt qu’à la police utilisée par la page. Si vous concevez une page qui utilise une autre police, vous pouvez utiliser l’une des suggestions suivantes.

• Ajustez les dimensions du modèle de boîte de dialogue pour compenser la différence de taille entre la police MS Shell Dlg et la police que la page utilise réellement. Par exemple, si vous choisissez une police deux fois plus large que MS Shell Dlg, définissez la propriété width du modèle de dialogue sur deux fois l’utilisation normale.
• Utilisez un modèle DIALOGEX et définissez le style de boîte de dialogue DS_SHELLFONT . Dans ce cas, le gestionnaire de feuilles de propriétés interprète les dimensions du modèle de dialogue par rapport à la police utilisée par le modèle de dialogue.

Ajout et suppression de pages

Après avoir créé une feuille de propriétés, une application peut ajouter une page à la fin de l’ensemble de pages existant en envoyant un message PSM_ADDPAGE . Pour insérer une page entre des pages existantes, envoyez un message PropSheet_InsertPage . Notez que la taille de la feuille de propriétés ne peut pas changer une fois qu’elle a été créée. Les pages ajoutées ou insérées ne doivent pas être plus grandes que la plus grande page actuellement dans la feuille de propriétés. Pour supprimer une page, envoyez un message PSM_REMOVEPAGE .

Lorsque vous définissez une page, vous pouvez spécifier l’adresse d’une fonction de rappel PropSheetPageProc que la feuille de propriétés appelle lorsqu’elle crée ou supprime la page. L’utilisation de PropSheetPageProc vous donne la possibilité d’effectuer des opérations d’initialisation et de nettoyage pour des pages individuelles.

Notes

Un certain nombre de messages et un appel de fonction se produisent pendant que la feuille de propriétés manipule la liste des pages. Pendant cette action, la tentative de modification de la liste des pages aura des résultats imprévisibles. N’ajoutez pas, n’insérez ou ne supprimez pas de pages dans votre implémentation de PropSheetPageProc, ni pendant que vous gérez les notifications et messages Windows suivants.

• PSN_APPLY
• PSN_KILLACTIVE
• PSN_RESET
• PSN_SETACTIVE
• PSN_WIZBACK
• PSN_WIZNEXT
• WM_INITDIALOG
• WM_DESTROY

Si vous avez besoin de modifier une page de feuille de propriétés pendant que vous gérez l’un de ces messages ou que PropSheetPageProc est en cours d’exploitation, publiez un message Windows privé. Votre application ne recevra ce message qu’une fois que le gestionnaire de feuilles de propriétés n’aura pas terminé ses tâches, auquel cas il sera en toute sécurité de modifier la liste des pages.

Lorsqu’une feuille de propriétés est détruite, elle détruit automatiquement toutes les pages qui y ont été ajoutées. Les pages sont détruites dans l’ordre inverse de celui spécifié dans le tableau utilisé pour créer les pages. Pour détruire une page créée par la fonction CreatePropertySheetPage mais qui n’a pas été ajoutée à la feuille de propriétés, utilisez la fonction DestroyPropertySheetPage .

Titre de la feuille de propriétés et étiquettes de page

Vous spécifiez le titre d’une feuille de propriétés dans la structure PROPSHEETHEADER utilisée pour créer la feuille de propriétés. Si le membre dwFlags inclut la valeur PSH_PROPTITLE , la feuille de propriétés ajoute le suffixe « Properties » ou le préfixe « Properties for », selon la version. Vous pouvez modifier le titre après la création d’une feuille de propriétés à l’aide du message PSM_SETTITLE . Dans un Assistant Aero, ce message peut être utilisé pour modifier dynamiquement le titre d’une page intérieure.

Par défaut, une feuille de propriétés utilise la chaîne de nom spécifiée dans le modèle de boîte de dialogue comme étiquette pour une page. Vous pouvez remplacer la chaîne de nom en incluant la valeur PSP_USETITLE dans le membre dwFlags de la structure PROPSHEETPAGE qui définit la page. Lorsque PSP_USETITLE est spécifié, le membre pszTitle doit contenir l’adresse de la chaîne d’étiquette pour la page.

Page Activation

Une feuille de propriétés ne peut avoir qu’une seule page active à la fois. La page qui contient l’activation se trouve au premier plan de la pile de pages qui se chevauche. L’utilisateur active une page en sélectionnant son onglet ; une application active une page à l’aide du message PSM_SETCURSEL .

La feuille de propriétés envoie le code de notification PSN_KILLACTIVE à la page qui est sur le point de perdre l’activation. En réponse, la page doit valider toutes les modifications que l’utilisateur a apportées à la page. Si la page nécessite une entrée utilisateur supplémentaire avant de perdre l’activation, utilisez la fonction SetWindowLong pour définir la valeur DWL_MSGRESULT de la page sur TRUE. En outre, la page doit afficher une boîte de message qui décrit le problème et fournit l’action recommandée. Définissez DWL_MSGRESULT sur FALSE lorsqu’il est possible de perdre l’activation.

Avant que la page qui obtient l’activation soit visible, la feuille de propriétés envoie le code de notification PSN_SETACTIVE à la page. La page doit répondre en initialisant ses fenêtres de contrôle.

Bouton Aide

Les feuilles de propriétés peuvent afficher deux boutons d’aide : un bouton d’aide de feuille de propriétés qui s’affiche en bas du cadre, en regard des boutons OK/Annuler/Appliquer, et un bouton de barre de légende standard qui fournit de l’aide contextuelle.

Le bouton Aide de la feuille de propriétés est facultatif et peut être activé page par page. Pour afficher le bouton Aide de la feuille de propriétés pour une ou plusieurs pages :

• Définissez l’indicateur PSH_HASHELP dans le membre dwFlags de la structure PROPSHEETHEADER de la feuille de propriétés.
• Pour chaque page qui affiche un bouton d’aide, définissez l’indicateur PSP_HASHELP dans le membre dwFlags de la structure PROPSHEETPAGE de la page.

Lorsque l’utilisateur clique sur le bouton Aide, la page active reçoit un code de notification PSN_HELP . La page doit répondre en affichant des informations d’aide, généralement en appelant la fonction WinHelp .

Suppression du bouton d’aide de la barre de légende

Le bouton d’aide de la barre de légende s’affiche par défaut, de sorte que l’aide contextuelle est toujours disponible pour les boutons OK/Annuler/Appliquer. Toutefois, ce bouton peut être supprimé, si nécessaire. Pour supprimer le bouton Aide de légende barre de propriétés d’une feuille de propriétés :

• Pour les versions des contrôles communs antérieurs à la version 5.80, vous devez implémenter une fonction de rappel de feuille de propriétés.
• Pour les versions 5.80 et ultérieures des contrôles communs, vous pouvez simplement définir l’indicateur PSH_NOCONTEXTHELP dans le membre dwFlags de la structure PROPSHEETHEADER de la feuille de propriétés. Toutefois, si vous avez besoin d’une compatibilité descendante avec les versions de contrôle courantes antérieures, vous devez implémenter la fonction de rappel.

Pour implémenter une fonction de rappel de feuille de propriétés qui supprime le bouton d’aide de la barre de légende :

• Définissez l’indicateur PSH_USECALLBACK dans le membre dwFlags de la structure PROPSHEETHEADER de la feuille de propriétés.
• Définissez le membre pfnCallBack de la structure PROPSHEETHEADER pour qu’il pointe vers la fonction de rappel.
• Implémentez la fonction de rappel. Lorsque cette fonction reçoit le message PSCB_PRECREATE , elle reçoit également un pointeur vers le modèle de boîte de dialogue de la feuille de propriétés. Supprimez le style DS_CONTEXTHELP de ce modèle.

L’exemple suivant montre comment implémenter une telle fonction de rappel :

int CALLBACK RemoveContextHelpProc(HWND hwnd, UINT message, LPARAM lParam)
{
    switch (message) 
    {
    case PSCB_PRECREATE:
        // Remove the DS_CONTEXTHELP style from the
        // dialog box template
        if (((LPDLGTEMPLATEEX)lParam)->signature ==    
           0xFFFF)
           {
            ((LPDLGTEMPLATEEX)lParam)->style 
            &= ~DS_CONTEXTHELP;
        }
        else {
            ((LPDLGTEMPLATE)lParam)->style 
            &= ~DS_CONTEXTHELP;
        }
        return TRUE;
    }
    return TRUE;
}

Si la structure DLGTEMPLATEEX n’est pas définie, incluez la déclaration suivante :

#include <pshpack1.h>

typedef struct DLGTEMPLATEEX
{
    WORD dlgVer;
    WORD signature;
    DWORD helpID;
    DWORD exStyle;
    DWORD style;
    WORD cDlgItems;
    short x;
    short y;
    short cx;
    short cy;
} DLGTEMPLATEEX, *LPDLGTEMPLATEEX;

#include <poppack.h>

Boutons OK, Annuler et Appliquer

Les boutons OK et Appliquer sont similaires ; les deux indiquent aux pages d’une feuille de propriétés de valider et d’appliquer les modifications apportées aux propriétés par l’utilisateur. La seule différence est que le fait de cliquer sur le bouton OK entraîne la destruction de la feuille de propriétés après l’application des modifications.

Lorsque l’utilisateur clique sur le bouton OK ou Appliquer , la feuille de propriétés envoie une notification PSN_KILLACTIVE à la page active, ce qui lui donne la possibilité de valider les modifications de l’utilisateur. Si les modifications sont valides, la page doit appeler la fonction SetWindowLong avec la valeur DWL_MSGRESULT définie sur FALSE. Si les modifications de l’utilisateur ne sont pas valides, la page doit définir DWL_MSGRESULT sur TRUE et afficher une boîte de dialogue informant l’utilisateur du problème. La page reste active jusqu’à ce qu’elle définisse DWL_MSGRESULT sur FALSE en réponse à un message PSN_KILLACTIVE.

Une fois qu’une page a répondu à une notification PSN_KILLACTIVE en définissant DWL_MSGRESULT sur FALSE, la feuille de propriétés envoie une notification PSN_APPLY à chaque page. Lorsqu’une page reçoit cette notification, elle doit appliquer les nouvelles propriétés à l’élément correspondant. Pour indiquer à la feuille de propriétés que les modifications sont valides pour la page, appelez SetWindowLong avec DWL_MSGRESULT défini sur PSNRET_NOERROR. Si les modifications ne sont pas valides pour la page, retournez une erreur. Cela empêche la destruction de la feuille de propriétés et renvoie le focus à la page qui a reçu la notification PSN_APPLY ou à la page qui avait le focus lorsque le bouton Appliquer a été appuyé. Pour retourner une erreur et indiquer la page qui recevra le focus, définissez DWL_MSGRESULT sur l’une des valeurs suivantes.

• PSNRET_INVALID. La feuille de propriétés ne sera pas détruite et le focus sera retourné à cette page.
• PSNRET_INVALID_NOCHANGEPAGE. La feuille de propriétés ne sera pas détruite et le focus sera retourné à la page qui avait le focus lorsque le bouton a été appuyé.

Une application peut utiliser le message PSM_APPLY pour simuler la sélection du bouton Appliquer .

Le bouton Appliquer est initialement désactivé lorsqu’une page devient active, ce qui indique qu’aucune modification de propriété n’est encore à appliquer. Lorsque la page reçoit une entrée via l’un de ses contrôles indiquant que l’utilisateur a modifié une propriété, la page doit envoyer le message PSM_CHANGED à la feuille de propriétés. Le message entraîne l’activation du bouton Appliquer dans la feuille de propriétés. Si l’utilisateur clique ensuite sur le bouton Appliquer ou Annuler , la page doit réinitialiser ses contrôles, puis envoyer le message PSM_UNCHANGED pour désactiver à nouveau le bouton Appliquer .

Parfois, le bouton Appliquer entraîne une modification d’une page dans une feuille de propriétés et la modification ne peut pas être annulée. Dans ce cas, la page doit envoyer le message PSM_CANCELTOCLOSE à la feuille des propriétés. Le message entraîne la modification du texte du bouton OK par « Fermer », ce qui indique que les modifications appliquées ne peuvent pas être annulées.

Parfois, une page apporte une modification à la configuration système qui nécessite le redémarrage de Windows ou le redémarrage du système avant que la modification puisse prendre effet. Une fois cette modification effectuée, une page doit envoyer le message PSM_RESTARTWINDOWS ou PSM_REBOOTSYSTEM à la feuille de propriétés. Ces messages entraînent la fonction PropertySheet à renvoyer la valeur ID_PSRESTARTWINDOWS ou ID_PSREBOOTSYSTEM après la destruction de la feuille de propriétés.

Lorsqu’un utilisateur clique sur le bouton Annuler , la feuille de propriétés envoie le code de notification PSN_RESET à toutes les pages, indiquant que la feuille de propriétés est sur le point d’être détruite. Une page doit utiliser la notification pour effectuer des opérations de nettoyage.

Assistants

Un Assistant est un type spécial de feuille de propriétés. Les Assistants sont conçus pour présenter les pages une par une dans une séquence contrôlée par l’application. Au lieu de sélectionner dans un groupe de pages en cliquant sur un onglet, les utilisateurs naviguent vers l’avant et l’arrière dans la séquence, une page à la fois, en cliquant sur des boutons. Par exemple, la capture d’écran suivante montre la page d’accueil de l’Assistant Ajout de matériel :

La capture d’écran suivante montre la première page d’un Assistant Aero, le nouveau style introduit dans Windows Vista.

Pour une présentation complète des Assistants, consultez Création d’Assistants .