MessageBoxA, 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 les informations d’état ou d’erreur. La zone de message retourne une valeur entière qui indique le bouton sur lequel l’utilisateur a cliqué.

Syntaxe

int MessageBoxA(
  [in, optional] HWND   hWnd,
  [in, optional] LPCSTR lpText,
  [in, optional] LPCSTR lpCaption,
  [in]           UINT   uType
);

Paramètres

[in, optional] hWnd

Type : HWND

Handle vers la fenêtre propriétaire de la boîte de message à créer. Si ce paramètre est 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 flux de lignes entre chaque ligne.

[in, optional] lpCaption

Type : LPCTSTR

Titre de la boîte de dialogue. Si ce paramètre est 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 à partir 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 push : abandonner, réessayeret Ignorer.
MB_CANCELTRYCONTINUE 0x0000006L	La boîte de message contient trois boutons push : Annuler, réessayer, Continuer. Utilisez ce type de zone 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 push : OK. Il s’agit de la valeur par défaut.
MB_OKCANCEL 0x00000001L	La boîte de message contient deux boutons push : OK et Annuler.
MB_RETRYCANCEL 0x00000005L	La boîte de message contient deux boutons push : réessayer et Annuler.
MB_YESNO 0x00000004L	La boîte de message contient deux boutons push : Oui et Non.
MB_YESNOCANCEL 0x00000003L	La boîte de message contient trois boutons push : Oui, Nonet 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 de point d’interrogation n’est plus recommandée, car elle ne représente pas clairement un type spécifique de message et parce que la formulation d’un message en tant que question peut s’appliquer à n’importe quel type de message. En outre, les utilisateurs peuvent confondre le point d’interrogation du symbole de message avec les informations d’aide. Par conséquent, n’utilisez pas ce symbole de message de point d’interrogation dans vos boîtes de message. Le système continue de prendre en charge son inclusion uniquement pour la compatibilité descendante.
MB_ICONSTOP 0x00000010L	Une icône de signature d’arrêt s’affiche dans la boîte de message.
MB_ICONERROR 0x00000010L	Une icône de signature d’arrêt s’affiche dans la boîte de message.
MB_ICONHAND 0x00000010L	Une icône de signature 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_DEFBUTTON3ou 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 poursuivre le travail dans la fenêtre identifiée par le paramètre hWnd. Toutefois, l’utilisateur peut passer aux fenêtres d’autres threads et travailler dans ces fenêtres. Selon la hiérarchie des fenêtres de l’application, l’utilisateur peut être en mesure de se déplacer vers d’autres fenêtres au sein du thread. Toutes les fenêtres enfants du parent de la boîte de message sont automatiquement désactivées, mais les fenêtres contextuelles ne le sont pas. 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 informer l’utilisateur d’erreurs graves et potentiellement dangereuses qui nécessitent une attention immédiate (par exemple, un manque de mémoire). Cet indicateur n’a aucun effet sur la capacité de l’utilisateur à interagir avec les 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 est 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 du 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 Windows Stations. Si le bureau d’entrée actuel n’est pas le bureau par défaut, MessageBox ne retourne pas tant que l’utilisateur ne passe pas au bureau par défaut.
MB_RIGHT 0x00080000L	Le texte est justifié avec le droit.
MB_RTLREADING 0x00100000L	Affiche le texte de message et de légende à l’aide de l’ordre de lecture de droite à gauche sur les systèmes hébreu et arabe.
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 informe 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. Services Terminal : 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. Il s’agit de sorte que la boîte de message puisse apparaître 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 Interactive Services. En particulier, sachez que cet indicateur peut produire du contenu interactif sur un bureau verrouillé et doit donc être utilisé uniquement pour un ensemble très limité de scénarios, tels que l’épuisement des ressources.

Valeur de retour

Type : int

Si une boîte de message a un bouton Annuler, la fonction renvoie la valeur IDCANCEL si la touche ÉCHAP est enfoncée ou si le bouton Annuler est sélectionné. Si la boîte de message n’a aucun bouton Annuler, l’appui sur Échap n’a aucun effet, sauf si un bouton MB_OK est présent. Si un bouton MB_OK est affiché 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’erreur étendues, appelez GetLastError.

Si la fonction réussit, la valeur de retour est l’une des valeurs d’élément de menu suivantes.

Retourner le code/la valeur	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 Aucun 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	MB_ICONHAND, MB_ICONSTOPou MB_ICONERROR
Icône	MB_ICONQUESTION
Icône	MB_ICONEXCLAMATION ou MB_ICONWARNING
Icône	MB_ICONASTERISK ou MB_ICONINFORMATION

 

L’ajout de deux marques de droite à gauche (RLMs), 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 afin de provoquer le rendu de l’ordre de lecture du MessageBox comme étant de droite à gauche (RTL).

Lorsque vous utilisez une boîte de message modale système pour indiquer que le système est faible en mémoire, les chaînes pointées par l'lpText et paramètres lpCaption ne doivent pas être extraits d’un fichier de ressources, car une tentative de chargement de la ressource peut échouer.

Si vous créez une boîte de message pendant qu’une boîte de dialogue est présente, utilisez un handle pour la boîte de dialogue en tant que 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 à entrer une action après qu’une condition d’erreur s’est produite. La boîte de message affiche le message qui décrit la condition d’erreur et comment le résoudre. Le style MB_CANCELTRYCONTINUE dirige MessageBox pour fournir trois boutons avec lesquels l’utilisateur peut choisir comment continuer. 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 obtenir un autre exemple de boîte de message, consultez Affichage d’une zone de message.

Note

L’en-tête winuser.h définit MessageBox 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 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winuser.h (include 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

conceptuelle

boîtes de dialogue

FlashWindow

messageBeep

MessageBoxEx

MessageBoxIndirect

autres ressources

de référence

SetForegroundWindow