Partager via


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
MB_ABORTRETRYIGNORE
0x00000002L
La boîte de message contient trois boutons d’envoi : Abandonner, Réessayer et Ignorer.
MB_CANCELTRYCONTINUE
0x00000006L
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.
MB_HELP
0x00004000L
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.
MB_OK
0x00000000L
La boîte de message contient un bouton d’envoi : OK. Il s’agit de la valeur par défaut.
MB_OKCANCEL
0x00000001L
La boîte de message contient deux boutons pousseurs : OK et Annuler.
MB_RETRYCANCEL
0x00000005L
La boîte de message contient deux boutons d’envoi : Réessayer et Annuler.
MB_YESNO
0x00000004L
La boîte de message contient deux boutons pousseurs : Oui et Non.
MB_YESNOCANCEL
0x00000003L
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.

Valeur Signification
MB_ICONEXCLAMATION
0x00000030L
Une icône de point d’exclamation s’affiche dans la boîte de message.
MB_ICONWARNING
0x00000030L
Une icône de point d’exclamation s’affiche dans la boîte de message.
MB_ICONINFORMATION
0x00000040L
Une icône composée d’une lettre minuscule i dans un cercle apparaît dans la boîte de message.
MB_ICONASTERISK
0x00000040L
Une icône composée d’une lettre minuscule i dans un cercle apparaît dans la boîte de message.
MB_ICONQUESTION
0x00000020L
Une icône de point d’interrogation s’affiche dans la boîte de message. L’icône de message en guise de point d’interrogation n’est plus recommandée, car elle ne représente pas clairement un type de message spécifique et aussi parce que la formulation d’un message sous forme de question peut s’appliquer à n’importe quel type de message. En outre, les utilisateurs peuvent confondre le symbole de point d’interrogation d’un message avec des informations d’aide. N’utilisez donc pas ce symbole de point d’interrogation dans vos boîtes de message. Le système continue à prendre en charge son inclusion uniquement pour la compatibilité descendante.
MB_ICONSTOP
0x00000010L
Une icône de signe d’arrêt s’affiche dans la boîte de message.
MB_ICONERROR
0x00000010L
Une icône de signe d’arrêt s’affiche dans la boîte de message.
MB_ICONHAND
0x00000010L
Une icône de signe d’arrêt s’affiche dans la boîte de message.
 

Pour indiquer le bouton par défaut, spécifiez l’une des valeurs suivantes.

Valeur Signification
MB_DEFBUTTON1
0x00000000L
Le premier bouton est le bouton par défaut.

MB_DEFBUTTON1 est la valeur par défaut, sauf si MB_DEFBUTTON2, MB_DEFBUTTON3 ou MB_DEFBUTTON4 est spécifié.

MB_DEFBUTTON2
0x00000100L
Le deuxième bouton est le bouton par défaut.
MB_DEFBUTTON3
0x00000200L
Le troisième bouton est le bouton par défaut.
MB_DEFBUTTON4
0x00000300L
Le quatrième bouton est le bouton par défaut.
 

Pour indiquer la modalité de la boîte de dialogue, spécifiez l’une des valeurs suivantes.

Valeur Signification
MB_APPLMODAL
0x00000000L
L’utilisateur doit répondre à la boîte de message avant de continuer à travailler dans la fenêtre identifiée par le paramètre hWnd . Toutefois, l’utilisateur peut se déplacer vers les fenêtres d’autres threads et travailler dans ces fenêtres.

Selon la hiérarchie des fenêtres dans l’application, l’utilisateur peut être en mesure de passer à d’autres fenêtres dans le thread. Toutes les fenêtres enfants du parent de la boîte de message sont automatiquement désactivées, mais pas les fenêtres contextuelles.

MB_APPLMODAL est la valeur par défaut si ni MB_SYSTEMMODAL ni MB_TASKMODAL n’est spécifié.

MB_SYSTEMMODAL
0x00001000L
Identique à MB_APPLMODAL sauf que la boîte de message a le style WS_EX_TOPMOST . Utilisez des boîtes de message modales système pour avertir l’utilisateur des erreurs graves et potentiellement dangereuses qui nécessitent une attention immédiate (par exemple, une mémoire insuffisante). Cet indicateur n’a aucun effet sur la capacité de l’utilisateur à interagir avec des fenêtres autres que celles associées à hWnd.
MB_TASKMODAL
0x00002000L
Identique à MB_APPLMODAL sauf que toutes les fenêtres de niveau supérieur appartenant au thread actuel sont désactivées si le paramètre hWnd a la valeur NULL. Utilisez cet indicateur lorsque l’application ou la bibliothèque appelante n’a pas de handle de fenêtre disponible, mais doit toujours empêcher l’entrée dans d’autres fenêtres dans le thread appelant sans interrompre d’autres threads.
 

Pour spécifier d’autres options, utilisez une ou plusieurs des valeurs suivantes.

Valeur Signification
MB_DEFAULT_DESKTOP_ONLY
0x00020000L
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.

MB_RIGHT
0x00080000L
Le texte est justifié à droite.
MB_RTLREADING
0x00100000L
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.
MB_SETFOREGROUND
0x00010000L
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.
MB_TOPMOST
0x00040000L
La boîte de message est créée avec le style de fenêtre WS_EX_TOPMOST .
MB_SERVICE_NOTIFICATION
0x00200000L
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
IDABORT
3
Le bouton Abandonner a été sélectionné.
IDCANCEL
2
Le bouton Annuler a été sélectionné.
IDCONTINUE
11
Le bouton Continuer a été sélectionné.
IDIGNORE
5
Le bouton Ignorer a été sélectionné.
IDNO
7
Le bouton Non a été sélectionné.
IDOK
1
Le bouton OK a été sélectionné.
IDRETRY
4
Le bouton Réessayer a été sélectionné.
IDTRYAGAIN
10
Le bouton Réessayer a été sélectionné.
IDYES
6
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
Icône pour MB_ICONHAND, MB_ICONSTOP et MB_ICONERROR MB_ICONHAND, MB_ICONSTOP ou MB_ICONERROR
Icône pour MB_ICONQUESTION MB_ICONQUESTION
Icône pour MB_ICONEXCLAMATION et MB_ICONWARNING MB_ICONEXCLAMATION ou MB_ICONWARNING
Icône MB_ICONASTERISK et MB_ICONINFORMATION 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 :

Boîte de message

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

Boîtes de dialogue

FlashWindow

MessageBeep

MessageBoxEx

MessageBoxIndirect

Autres ressources

Référence

SetForegroundWindow