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
	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

Boîtes de dialogue

FlashWindow

MessageBeep

MessageBoxEx

MessageBoxIndirect

Autres ressources

Référence

SetForegroundWindow