Funzione MessageBox (winuser.h)

Visualizza una finestra di dialogo modale contenente un'icona di sistema, un set di pulsanti e un breve messaggio specifico dell'applicazione, ad esempio informazioni sullo stato o sugli errori. La finestra di messaggio restituisce un valore intero che indica il pulsante selezionato dall'utente.

Sintassi

int MessageBox(
  [in, optional] HWND    hWnd,
  [in, optional] LPCTSTR lpText,
  [in, optional] LPCTSTR lpCaption,
  [in]           UINT    uType
);

Parametri

[in, optional] hWnd

Tipo: HWND

Handle per la finestra del proprietario della finestra di messaggio da creare. Se questo parametro è NULL, la finestra di messaggio non ha una finestra di proprietario.

[in, optional] lpText

Tipo: LPCTSTR

Messaggio da visualizzare. Se la stringa è costituita da più righe, è possibile separare le righe utilizzando un ritorno a capo e/o un carattere di avanzamento riga tra ogni riga.

[in, optional] lpCaption

Tipo: LPCTSTR

Titolo della finestra di dialogo. Se questo parametro è NULL, il titolo predefinito è Error.

[in] uType

Tipo: UINT

Contenuto e comportamento della finestra di dialogo. Questo parametro può essere una combinazione di flag dai gruppi di flag seguenti.

Per indicare i pulsanti visualizzati nella finestra di messaggio, specificare uno dei valori seguenti.

Valore	Significato
MB_ABORTRETRYIGNORE 0x00000002L	La finestra di messaggio contiene tre pulsanti push: Interruzione, Riprova e Ignora.
MB_CANCELTRYCONTINUE 0x00000006L	La finestra di messaggio contiene tre pulsanti push: Annulla, Riprova, Continua. Utilizzare questo tipo di messaggio anziché MB_ABORTRETRYIGNORE.
MB_HELP 0x00004000L	Aggiunge un pulsante Della Guida alla finestra di messaggio. Quando l'utente fa clic sul pulsante ? o preme F1, il sistema invia un messaggio di WM_HELP al proprietario.
MB_OK 0x0000000L	La finestra di messaggio contiene un pulsante di selezione: OK. Questo è il valore predefinito.
MB_OKCANCEL 0x00000001L	La finestra di messaggio contiene due pulsanti push: OK e Annulla.
MB_RETRYCANCEL 0x00000005L	La finestra di messaggio contiene due pulsanti push: Riprova e Annulla.
MB_YESNO 0x00000004L	La finestra di messaggio contiene due pulsanti push: Sì e No.
MB_YESNOCANCEL 0x00000003L	La finestra di messaggio contiene tre pulsanti push: Sì, No e Annulla.

 

Per visualizzare un'icona nella finestra di messaggio, specificare uno dei valori seguenti.

Valore	Significato
MB_ICONEXCLAMATION 0x0000030L	Nella finestra di messaggio viene visualizzata un'icona punto esclamativo.
MB_ICONWARNING 0x0000030L	Nella finestra di messaggio viene visualizzata un'icona punto esclamativo.
MB_ICONINFORMATION 0x0000040L	Nella finestra di messaggio viene visualizzata un'icona costituita da una lettera minuscola i in un cerchio.
MB_ICONASTERISK 0x0000040L	Nella finestra di messaggio viene visualizzata un'icona costituita da una lettera minuscola i in un cerchio.
MB_ICONQUESTION 0x00000020L	Nella finestra di messaggio viene visualizzata un'icona del punto interrogativo. L’icona di messaggio costituita da un punto interrogativo non è più consigliata perché non rappresenta chiaramente un tipo specifico di messaggio e la formulazione di un messaggio sotto forma di domanda può essere applicata a qualsiasi tipo di messaggio. Inoltre, gli utenti possono confondere il simbolo di messaggio costituito da un punto interrogativo con le informazioni della Guida. Non usare quindi il simbolo di messaggio costituito da un punto interrogativo nelle caselle di messaggio. Il sistema continua a supportarne l'inclusione solo per compatibilità con le versioni precedenti.
MB_ICONSTOP 0x00000010L	Nella finestra di messaggio viene visualizzata un'icona di segno di arresto.
MB_ICONERROR 0x00000010L	Nella finestra di messaggio viene visualizzata un'icona di segno di arresto.
MB_ICONHAND 0x00000010L	Nella finestra di messaggio viene visualizzata un'icona di segno di arresto.

 

Per indicare il pulsante predefinito, specificare uno dei valori seguenti.

Valore	Significato
MB_DEFBUTTON1 0x0000000L	Il primo pulsante è il pulsante predefinito. MB_DEFBUTTON1 è l'impostazione predefinita, a meno che non sia specificato MB_DEFBUTTON2, MB_DEFBUTTON3 o MB_DEFBUTTON4 .
MB_DEFBUTTON2 0x00000100L	Il secondo pulsante è il pulsante predefinito.
MB_DEFBUTTON3 0x00000200L	Il terzo pulsante è il pulsante predefinito.
MB_DEFBUTTON4 0x0000300L	Il quarto pulsante è il pulsante predefinito.

 

Per indicare la modalità della finestra di dialogo, specificare uno dei valori seguenti.

Valore	Significato
MB_APPLMODAL 0x00000000L	L'utente deve rispondere alla finestra di messaggio prima di continuare il lavoro nella finestra identificata dal parametro hWnd . Tuttavia, l'utente può passare alle finestre di altri thread e lavorare in tali finestre. A seconda della gerarchia di finestre nell'applicazione, l'utente può essere in grado di passare ad altre finestre all'interno del thread. Tutte le finestre figlio dell'elemento padre della finestra di messaggio vengono disabilitate automaticamente, ma le finestre popup non sono. MB_APPLMODAL è il valore predefinito se non viene specificato né MB_SYSTEMMODAL né MB_TASKMODAL .
MB_SYSTEMMODAL 0x00001000L	Uguale a MB_APPLMODAL, ad eccezione del fatto che la finestra di messaggio ha lo stile WS_EX_TOPMOST . Usare le caselle di messaggio modali di sistema per informare l'utente di errori gravi e potenzialmente dannosi che richiedono un'attenzione immediata (ad esempio, l'esaurimento della memoria). Questo flag non ha alcun effetto sulla capacità dell'utente di interagire con finestre diverse da quelle associate a hWnd.
MB_TASKMODAL 0x00002000L	Uguale a MB_APPLMODAL tranne che tutte le finestre di primo livello appartenenti al thread corrente sono disabilitate se il parametro hWnd è NULL. Usare questo flag quando l'applicazione chiamante o la libreria non dispone di un handle di finestra disponibile, ma deve comunque impedire l'input ad altre finestre nel thread chiamante senza sospendere altri thread.

 

Per specificare altre opzioni, usare uno o più dei valori seguenti.

Valore	Significato
MB_DEFAULT_DESKTOP_ONLY 0x0002000L	Uguale a desktop della stazione finestra interattiva. Per altre informazioni, vedere Stazioni finestra. Se il desktop di input corrente non è il desktop predefinito, MessageBox non restituisce finché l'utente passa al desktop predefinito.
MB_RIGHT 0x00080000L	Il testo è giustificato correttamente.
MB_RTLREADING 0x0010000L	Visualizza il messaggio e didascalia testo usando l'ordine di lettura da destra a sinistra nei sistemi ebrei e arabi.
MB_SETFOREGROUND 0x00010000L	La finestra di messaggio diventa la finestra di primo piano. Internamente, il sistema chiama la funzione SetForegroundWindow per la finestra di messaggio.
MB_TOPMOST 0x00040000L	La finestra di messaggio viene creata con lo stile della finestra WS_EX_TOPMOST .
MB_SERVICE_NOTIFICATION 0x0020000L	Il chiamante è un servizio che notifica un evento all'utente. La funzione visualizza una finestra di messaggio sul desktop attivo corrente, anche se non è presente alcun utente connesso al computer. Servizi terminal: Se il thread chiamante ha un token di rappresentazione, la funzione indirizza la casella di messaggio alla sessione specificata nel token di rappresentazione. Se questo flag è impostato, il parametro hWnd deve essere NULL. In questo modo la finestra di messaggio può essere visualizzata in un desktop diverso dal desktop corrispondente all'hWnd. Per informazioni sulle considerazioni sulla sicurezza relative all'uso di questo flag, vedere Servizi interattivi. In particolare, tenere presente che questo flag può produrre contenuto interattivo in un desktop bloccato e pertanto deve essere usato solo per un set molto limitato di scenari, ad esempio l'esaurimento delle risorse.

Valore restituito

Tipo: int

Se una finestra di messaggio ha un pulsante Annulla , la funzione restituisce il valore IDCANCEL se il tasto ESC viene premuto o viene selezionato il pulsante Annulla . Se la finestra di messaggio non ha alcun pulsante Annulla , premere ESC non avrà effetto, a meno che non sia presente un pulsante MB_OK. Se viene visualizzato un pulsante MB_OK e l'utente preme ESC, il valore restituito sarà IDOK.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Se la funzione ha esito positivo, il valore restituito è uno dei valori della voce di menu seguenti.

Codice/valore restituito	Descrizione
IDABORT 3	È stato selezionato il pulsante Di interruzione .
IDCANCEL 2	È stato selezionato il pulsante Annulla .
IDCONTINUE 11	È stato selezionato il pulsante Continua .
IDIGNORE 5	È stato selezionato il pulsante Ignora .
IDNO 7	È stato selezionato il pulsante No .
IDOK 1	È stato selezionato il pulsante OK .
IDRETRY 4	È stato selezionato il pulsante Riprova .
IDTRYAGAIN 10	È stato selezionato il pulsante Riprova .
IDYES 6	È stato selezionato il pulsante Sì .

Commenti

Le icone di sistema seguenti possono essere usate in una finestra di messaggio impostando il parametro uType sul valore del flag corrispondente.

Icona	Contrassegno dei valori
	MB_ICONHAND, MB_ICONSTOP o MB_ICONERROR
	MB_ICONQUESTION
	MB_ICONEXCLAMATION o MB_ICONWARNING
	MB_ICONASTERISK o MB_ICONINFORMATION

 

L'aggiunta di due contrassegni da destra a sinistra (RLMs), rappresentati dal carattere di formattazione Unicode U+200F, all'inizio di una stringa di visualizzazione MessageBox viene interpretata dal motore di rendering MessageBox in modo da causare il rendering dell'ordine di lettura di MessageBox come RTL (right-to-left).

Quando si usa una finestra di messaggio modale di sistema per indicare che il sistema è basso in memoria, le stringhe puntate dai parametri lpText e lpCaption non devono essere prese da un file di risorse perché un tentativo di caricamento della risorsa potrebbe non riuscire.

Se si crea una finestra di messaggio mentre è presente una finestra di dialogo, usare un handle per la finestra di dialogo come parametro hWnd . Il parametro hWnd non deve identificare una finestra figlio, ad esempio un controllo in una finestra di dialogo.

Esempio

Nell'esempio seguente l'applicazione visualizza una finestra di messaggio che richiede all'utente un'azione dopo che si è verificata una condizione di errore. La finestra di messaggio visualizza il messaggio che descrive la condizione di errore e come risolverlo. Lo stile MB_CANCELTRYCONTINUE indirizza MessageBox per fornire tre pulsanti con cui l'utente può scegliere come procedere. Lo stile MB_DEFBUTTON2 imposta lo stato attivo predefinito sul secondo pulsante della finestra di messaggio, in questo caso, il pulsante Riprova .

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'immagine seguente mostra l'output dell'esempio di codice precedente:

Per un altro esempio di finestra di messaggio, vedere Visualizzazione di una finestra di messaggio.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-ntuser-dialogbox-l1-1-0 (introdotto in Windows 8)

Vedi anche

Informazioni concettuali

Finestre di dialogo

Flashwindow

MessageBeep

MessageBoxEx

MessageBoxIndirect

Altre risorse

Riferimento

SetForegroundWindow