SHMessageBoxCheckA, fonction (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 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 zone de message. Cette fonction ne prend en charge qu’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 l’un des indicateurs suivants.
MB_OKCANCEL
Affichez une boîte de message avec OK et bouton Annuler.
MB_YESNO
Affichez une boîte de message avec 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 une et une seule 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
Afficher une icône de point d’exclamation.
MB_ICONINFORMATION
Affichez une icône avec une minuscule « i » dans un cercle.
iDefault
Type : int
Valeur retournée par la fonction 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, la boîte de message 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 de longueur, y compris le caractère null de fin.
Valeur de retour
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 leOK
Si l’utilisateur ferme la boîte de message en cliquant sur le bouton X dans la légende, la fonction retourne IDCANCEL. Cette valeur est retournée dans ce cas même si l’indicateur de 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 provoquées par une mémoire ou des ressources insuffisantes. Si vous obtenez l’une de ces valeurs de retour, sachez 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 suivants de SHMessageBoxCheck retournent simplement la valeur spécifiée par iDefault. Prenons 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 À l’avenir, 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 initialement. 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 convenir de votre valeur iDefault
SHMessageBoxCheck enregistre les boîtes de message que l’utilisateur a choisi de supprimer sous la clé de Registre suivante :
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer DontShowMeThisDialogAgain
Note
L’en-tête shlwapi.h définit SHMessageBoxCheck comme 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | shlwapi.h |
| DLL | Shlwapi.dll (version 5.0 ou ultérieure) |