Fonction SHMessageBoxCheckA (shlwapi.h)

[SHMessageBoxCheck peut être utilisé 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 boîte 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 SHMessageBoxCheckA(
  [in, optional] HWND   hwnd,
  [in]           LPCSTR pszText,
  [in]           LPCSTR pszCaption,
                 UINT   uType,
                 int    iDefault,
  [in]           LPCSTR 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 est défini sur NULL, le titre est défini sur Erreur!.

uType

Type : UINT

Indicateurs qui spécifient le contenu et le comportement de la boîte de message. Cette fonction prend en charge uniquement 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 et un seul des indicateurs suivants.

MB_OKCANCEL

Affichez une boîte de message avec les boutons OK et Annuler .

MB_YESNO

Affichez une boîte de message avec les boutons Oui et Non .

MB_OK

Affichez une boîte de message avec un bouton OK .

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

MB_ICONHAND

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

MB_ICONQUESTION

Afficher une icône de point d’interrogation.

MB_ICONEXCLAMATION

Afficher une icône de point d’exclamation.

MB_ICONINFORMATION

Affiche une icône avec un « i » minuscule 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 boîte 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 boîte 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 insuffisante, 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 renvoie –1 ou, dans certains cas, iDefault. Ces erreurs peuvent être provoqué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 toute 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 boîte de message, la fonction ne conserve pas le bouton sur lequel il a cliqué. Au lieu de cela, les appels ultérieurs 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 renvoie 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, elle 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 correspondre à votre valeur iDefault . L’absence de prise en charge de l’indicateur MB_DEFBUTTON2 signifie que 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
                  DontShowMeThisDialogAgain

Notes

L’en-tête shlwapi.h définit SHMessageBoxCheck en tant qu’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. La combinaison 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

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)