Fonction SHMessageBoxCheckW (shlwapi.h)

[SHMessageBoxCheck est disponible pour une utilisation dans les systèmes d’exploitation spécifiés dans la section Configuration requise. Il peut être modifié ou indisponible dans les versions suivantes.]

Affiche une zone de message qui donne à l’utilisateur la possibilité de supprimer d’autres occurrences. Si l’utilisateur a déjà choisi de supprimer la boîte de message, la fonction n’affiche pas de boîte de dialogue et retourne simplement la valeur par défaut.

Syntaxe

int SHMessageBoxCheckW(
  [in, optional] HWND    hwnd,
  [in]           LPCWSTR pszText,
  [in]           LPCWSTR pszCaption,
                 UINT    uType,
                 int     iDefault,
  [in]           LPCWSTR pszRegVal
);

Paramètres

[in, optional] hwnd

Type : HWND

Handle de fenêtre au propriétaire de la boîte de message. Cette valeur peut être NULL.

[in] pszText

Type : LPCTSTR

Pointeur vers une chaîne terminée par null qui contient le message à afficher.

[in] pszCaption

Type : LPCTSTR

Pointeur vers une chaîne terminée par null qui contient le titre de la zone de message. Si ce paramètre a la valeur NULL, le titre est défini sur Error !.

uType

Type : UINT

Indicateurs qui spécifient le contenu et le comportement de la zone de message. Cette fonction prend uniquement en charge un sous-ensemble des indicateurs pris en charge par MessageBox. Si vous utilisez des indicateurs qui ne sont pas répertoriés ci-dessous, le comportement de la fonction n’est pas défini.

Vous devez spécifier les boutons à afficher en définissant un seul des indicateurs suivants.

MB_OKCANCEL

Affichez une zone de message avec les boutons OK et Annuler .

MB_YESNO

Affichez une zone de message avec les boutons Oui et Non .

MB_OK

Affichez une zone de message avec un bouton OK .

Vous pouvez afficher une icône facultative en définissant un et un seul des indicateurs suivants.

MB_ICONHAND

Affichez une icône de signe d’arrêt.

MB_ICONQUESTION

Affichez une icône de point d’interrogation.

MB_ICONEXCLAMATION

Affichez une icône de point d’exclamation.

MB_ICONINFORMATION

Affichez une icône avec un « i » en minuscules dans un cercle.

iDefault

Type : int

Valeur que la fonction retourne lorsque l’utilisateur a choisi de ne pas afficher à nouveau la boîte de message. Si l’utilisateur n’a pas choisi de supprimer la zone de message, celle-ci s’affiche et la fonction ignore iDefault.

[in] pszRegVal

Type : LPCTSTR

Pointeur vers une chaîne terminée par null qui contient une valeur de chaîne unique à associer à ce message. Pour éviter les collisions avec les valeurs utilisées par Microsoft, cette chaîne doit inclure un GUID. Cette chaîne ne doit pas dépasser REGSTR_MAX_VALUE_LENGTH caractères, y compris le caractère null de fin.

Valeur retournée

Type : int

Si l’utilisateur a déjà choisi de supprimer la zone de message, la fonction retourne immédiatement la valeur affectée à iDefault.

Si l’utilisateur clique sur le bouton OK, Annuler, Oui ou Non , la fonction retourne RESPECTIVEment IDOK, IDCANCEL, IDYES ou IDNO.

Si l’utilisateur ferme la boîte de message en cliquant sur le bouton X dans le légende, la fonction retourne IDCANCEL. Cette valeur est retournée dans ce cas même si l’indicateur MB_OKCANCEL n’a pas été défini.

Si une erreur se produit, la valeur de retour est normalement -1. Toutefois, dans certaines conditions de mémoire faible, la fonction peut retourner iDefault.

Remarques

Avertissement de sécurité : N’effectuez aucune action dangereuse si la fonction retourne –1 ou iDefault. Si une erreur se produit lors de la tentative d’affichage de la boîte de message, SHMessageBoxCheck retourne –1 ou, dans certains cas, iDefault. Ces erreurs peuvent être causées par une mémoire ou des ressources insuffisantes. Si vous obtenez l’une de ces valeurs de retour, vous devez savoir que l’utilisateur n’a pas nécessairement vu la boîte de dialogue et n’a donc pas accepté positivement une action.

Ne confondez pas « Ne pas afficher cette boîte de dialogue » avec « Mémoriser cette réponse ». SHMessageBoxCheck ne fournit pas la fonctionnalité « Mémoriser cette réponse ». Si l’utilisateur choisit de supprimer à nouveau la zone de message, la fonction ne conserve pas le bouton sur lequel il a cliqué. Au lieu de cela, les appels suivants de SHMessageBoxCheck retournent simplement la valeur spécifiée par iDefault. Considérez l'exemple suivant.

int iResult = SHMessageBoxCheck(hwnd, 
                                TEXT("Do you want to exit without saving?"),
                                TEXT("Warning"), 
                                MB_YESNO, 
                                IDNO,
                                TEXT("{d9108ba3-9a61-4398-bfbc-b02102c77e8a}");

Si l’utilisateur sélectionne Dans le futur, ne m’affichez pas cette boîte de dialogue et cliquez sur le bouton Oui , SHMessageBoxCheck retourne IDYES. Toutefois, la prochaine fois que ce code est exécuté, SHMessageBoxCheck ne retourne pas IDYES, même si l’utilisateur a sélectionné Oui à l’origine. Au lieu de cela, il retourne IDNO, car il s’agit de la valeur spécifiée par iDefault.

Le bouton par défaut affiché par la boîte de message doit être d’accord avec votre valeur iDefault . L’absence de prise en charge de l’indicateur MB_DEFBUTTON2 signifie qu’iDefault doit être défini sur IDOK si vous avez spécifié l’indicateur MB_OK ou MB_OKCANCEL. La valeur iDefault doit être définie sur IDYES si vous avez défini l’indicateur MB_YESNO.

SHMessageBoxCheck enregistre les zones de message que l’utilisateur a choisi de supprimer sous la clé de Registre suivante.

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  LowRegistry
                     DontShowMeThisDialogAgain

Notes

L’en-tête shlwapi.h définit SHMessageBoxCheck comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shlwapi.h
DLL	Shlwapi.dll (version 5.0 ou ultérieure)