MessageBox, fonction (winuser.h)
Affiche une boîte de dialogue modale qui contient une icône système, un ensemble de boutons et un bref message spécifique à l’application, tel que des informations de status ou d’erreur. La boîte de message retourne une valeur entière qui indique le bouton sur lequel l’utilisateur a cliqué.
Syntaxe
int MessageBox(
[in, optional] HWND hWnd,
[in, optional] LPCTSTR lpText,
[in, optional] LPCTSTR lpCaption,
[in] UINT uType
);
Paramètres
[in, optional] hWnd
Type : HWND
Handle pour la fenêtre propriétaire de la boîte de message à créer. Si ce paramètre a la valeur NULL, la zone de message n’a pas de fenêtre propriétaire.
[in, optional] lpText
Type : LPCTSTR
Message à afficher. Si la chaîne se compose de plusieurs lignes, vous pouvez séparer les lignes à l’aide d’un retour chariot et/ou d’un caractère de saut de ligne entre chaque ligne.
[in, optional] lpCaption
Type : LPCTSTR
Titre de la boîte de dialogue. Si ce paramètre a la valeur NULL, le titre par défaut est Erreur.
[in] uType
Type : UINT
Contenu et comportement de la boîte de dialogue. Ce paramètre peut être une combinaison d’indicateurs des groupes d’indicateurs suivants.
Pour indiquer les boutons affichés dans la boîte de message, spécifiez l’une des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
La boîte de message contient trois boutons d’envoi : Abandonner, Réessayer et Ignorer. |
|
La boîte de message contient trois boutons d’envoi : Annuler, Réessayer, Continuer. Utilisez ce type de boîte de message au lieu de MB_ABORTRETRYIGNORE. |
|
Ajoute un bouton Aide à la boîte de message. Lorsque l’utilisateur clique sur le bouton Aide ou appuie sur F1, le système envoie un message WM_HELP au propriétaire. |
|
La boîte de message contient un bouton d’envoi : OK. Il s’agit de la valeur par défaut. |
|
La boîte de message contient deux boutons pousseurs : OK et Annuler. |
|
La boîte de message contient deux boutons d’envoi : Réessayer et Annuler. |
|
La boîte de message contient deux boutons pousseurs : Oui et Non. |
|
La boîte de message contient trois boutons pousseurs : Oui, Non et Annuler. |
Pour afficher une icône dans la zone de message, spécifiez l’une des valeurs suivantes.
Pour indiquer le bouton par défaut, spécifiez l’une des valeurs suivantes.
Pour indiquer la modalité de la boîte de dialogue, spécifiez l’une des valeurs suivantes.
Pour spécifier d’autres options, utilisez une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Identique au bureau de la station de fenêtre interactive. Pour plus d’informations, consultez Window Stations.
Si le bureau d’entrée actuel n’est pas le bureau par défaut, MessageBox ne retourne pas jusqu’à ce que l’utilisateur bascule vers le bureau par défaut. |
|
Le texte est justifié à droite. |
|
Affiche le message et le texte légende à l’aide de l’ordre de lecture de droite à gauche sur les systèmes hébreux et arabes. |
|
La boîte de message devient la fenêtre de premier plan. En interne, le système appelle la fonction SetForegroundWindow pour la boîte de message. |
|
La boîte de message est créée avec le style de fenêtre WS_EX_TOPMOST . |
|
L’appelant est un service qui avertit l’utilisateur d’un événement. La fonction affiche une boîte de message sur le bureau actif actuel, même s’il n’y a aucun utilisateur connecté à l’ordinateur.
Terminal Services : Si le thread appelant a un jeton d’emprunt d’identité, la fonction dirige la boîte de message vers la session spécifiée dans le jeton d’emprunt d’identité. Si cet indicateur est défini, le paramètre hWnd doit être NULL. Cela permet à la boîte de message de s’afficher sur un bureau autre que le bureau correspondant au hWnd. Pour plus d’informations sur les considérations de sécurité relatives à l’utilisation de cet indicateur, consultez Services interactifs. En particulier, n’oubliez pas que cet indicateur peut produire du contenu interactif sur un bureau verrouillé et ne doit donc être utilisé que pour un ensemble très limité de scénarios, tels que l’épuisement des ressources. |
Valeur retournée
Type : int
Si une boîte de message a un bouton Annuler , la fonction retourne la valeur IDCANCEL si vous appuyez sur la touche Échap ou si le bouton Annuler est sélectionné. Si la boîte de message n’a pas de bouton Annuler , l’appui sur Échap n’a aucun effet, sauf si un bouton MB_OK est présent. Si un bouton MB_OK s’affiche et que l’utilisateur appuie sur ÉCHAP, la valeur de retour est IDOK.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Si la fonction réussit, la valeur de retour est l’une des valeurs d’élément de menu suivantes.
| Code/valeur de retour | Description |
|---|---|
|
Le bouton Abandonner a été sélectionné. |
|
Le bouton Annuler a été sélectionné. |
|
Le bouton Continuer a été sélectionné. |
|
Le bouton Ignorer a été sélectionné. |
|
Le bouton Non a été sélectionné. |
|
Le bouton OK a été sélectionné. |
|
Le bouton Réessayer a été sélectionné. |
|
Le bouton Réessayer a été sélectionné. |
|
Le bouton Oui a été sélectionné. |
Remarques
Les icônes système suivantes peuvent être utilisées dans une boîte de message en définissant le paramètre uType sur la valeur d’indicateur correspondante.
| Icône | Valeurs d’indicateur |
|---|---|
|
MB_ICONHAND, MB_ICONSTOP ou MB_ICONERROR |
|
MB_ICONQUESTION |
|
MB_ICONEXCLAMATION ou MB_ICONWARNING |
|
MB_ICONASTERISK ou MB_ICONINFORMATION |
L’ajout de deux marques de droite à gauche (RLM), représentées par le caractère de mise en forme Unicode U+200F, au début d’une chaîne d’affichage MessageBox est interprétée par le moteur de rendu MessageBox de sorte que l’ordre de lecture du MessageBox soit affiché de droite à gauche (RTL).
Lorsque vous utilisez une boîte de message modale système pour indiquer que le système manque de mémoire, les chaînes pointées par les paramètres lpText et lpCaption ne doivent pas être extraites d’un fichier de ressources, car une tentative de chargement de la ressource peut échouer.
Si vous créez une boîte de message alors qu’une boîte de dialogue est présente, utilisez un handle pour la boîte de dialogue comme paramètre hWnd . Le paramètre hWnd ne doit pas identifier une fenêtre enfant, telle qu’un contrôle dans une boîte de dialogue.
Exemples
Dans l’exemple suivant, l’application affiche une boîte de message qui invite l’utilisateur à effectuer une action après qu’une condition d’erreur s’est produite. La zone de message affiche le message qui décrit la condition d’erreur et comment la résoudre. Le style MB_CANCELTRYCONTINUE indique à MessageBox de fournir trois boutons avec lesquels l’utilisateur peut choisir la procédure à suivre. Le style MB_DEFBUTTON2 définit le focus par défaut sur le deuxième bouton de la zone de message, dans ce cas, le bouton Réessayer .
int DisplayResourceNAMessageBox()
{
int msgboxID = MessageBox(
NULL,
(LPCWSTR)L"Resource not available\nDo you want to try again?",
(LPCWSTR)L"Account Details",
MB_ICONWARNING | MB_CANCELTRYCONTINUE | MB_DEFBUTTON2
);
switch (msgboxID)
{
case IDCANCEL:
// TODO: add code
break;
case IDTRYAGAIN:
// TODO: add code
break;
case IDCONTINUE:
// TODO: add code
break;
}
return msgboxID;
}
L’image suivante montre la sortie de l’exemple de code précédent :
Pour un autre exemple de boîte de message, consultez Affichage d’une zone de message.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winuser.h (inclure Windows.h) |
| Bibliothèque | User32.lib |
| DLL | User32.dll |
| Ensemble d’API | ext-ms-win-ntuser-dialogbox-l1-1-0 (introduit dans Windows 8) |
Voir aussi
Conceptuel
Autres ressources
Référence