Compartir a través de


Función MessageBox (winuser.h)

Muestra un cuadro de diálogo modal que contiene un icono del sistema, un conjunto de botones y un breve mensaje específico de la aplicación, como información de estado o error. El cuadro de mensaje devuelve un valor entero que indica qué botón ha hecho clic el usuario.

Sintaxis

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

Parámetros

[in, optional] hWnd

Tipo: HWND

Identificador de la ventana de propietario del cuadro de mensaje que se va a crear. Si este parámetro es NULL, el cuadro de mensaje no tiene ninguna ventana de propietario.

[in, optional] lpText

Tipo: LPCTSTR

Mensaje que se va a mostrar. Si la cadena consta de más de una línea, puede separar las líneas mediante un carácter de retorno de carro o avance de línea entre cada línea.

[in, optional] lpCaption

Tipo: LPCTSTR

Título del cuadro de diálogo. Si este parámetro es NULL, el título predeterminado es Error.

[in] uType

Tipo: UINT

Contenido y comportamiento del cuadro de diálogo. Este parámetro puede ser una combinación de marcas de los siguientes grupos de marcas.

Para indicar los botones que se muestran en el cuadro de mensaje, especifique uno de los valores siguientes.

Valor Significado
MB_ABORTRETRYIGNORE
0x00000002L
El cuadro de mensaje contiene tres botones de inserción: Anular, Reintentar e Omitir.
MB_CANCELTRYCONTINUE
0x00000006L
El cuadro de mensaje contiene tres botones de inserción: Cancelar, Intentar de nuevo, Continuar. Use este tipo de cuadro de mensaje en lugar de MB_ABORTRETRYIGNORE.
MB_HELP
0x00004000L
Agrega un botón Ayuda al cuadro de mensaje. Cuando el usuario hace clic en el botón Ayuda o presiona F1, el sistema envía un mensaje WM_HELP al propietario.
MB_OK
0x00000000L
El cuadro de mensaje contiene un botón de inserción: Aceptar. Este es el valor predeterminado.
MB_OKCANCEL
0x00000001L
El cuadro de mensaje contiene dos botones de inserción: Aceptar y Cancelar.
MB_RETRYCANCEL
0x00000005L
El cuadro de mensaje contiene dos botones de inserción: Reintentar y Cancelar.
MB_YESNO
0x00000004L
El cuadro de mensaje contiene dos botones de inserción: y No.
MB_YESNOCANCEL
0x00000003L
El cuadro de mensaje contiene tres botones de inserción: , No y Cancelar.
 

Para mostrar un icono en el cuadro de mensaje, especifique uno de los valores siguientes.

Valor Significado
MB_ICONEXCLAMATION
0x00000030L
Aparece un icono de signo de exclamación en el cuadro de mensaje.
MB_ICONWARNING
0x00000030L
Aparece un icono de signo de exclamación en el cuadro de mensaje.
MB_ICONINFORMATION
0x00000040L
Un icono que consta de una letra minúscula i en un círculo aparece en el cuadro de mensaje.
MB_ICONASTERISK
0x00000040L
Un icono que consta de una letra minúscula i en un círculo aparece en el cuadro de mensaje.
MB_ICONQUESTION
0x00000020L
Aparece un icono de signo de interrogación en el cuadro de mensaje. Ya no se recomienda el icono de mensaje con el signo de interrogación, porque no representa claramente un tipo específico de mensaje y porque la formulación de un mensaje como una pregunta podría aplicarse a cualquier tipo de mensaje. Además, los usuarios pueden confundir el signo de interrogación del mensaje con la información de ayuda. Por lo tanto, no use este símbolo de mensaje con el signo de interrogación en los cuadros de mensaje. El sistema sigue permitiendo que se incluya únicamente por cuestiones de compatibilidad con versiones anteriores.
MB_ICONSTOP
0x00000010L
Aparece un icono de signo de detención en el cuadro de mensaje.
MB_ICONERROR
0x00000010L
Aparece un icono de signo de detención en el cuadro de mensaje.
MB_ICONHAND
0x00000010L
Aparece un icono de signo de detención en el cuadro de mensaje.
 

Para indicar el botón predeterminado, especifique uno de los valores siguientes.

Valor Significado
MB_DEFBUTTON1
0x00000000L
El primer botón es el predeterminado.

MB_DEFBUTTON1 es el valor predeterminado a menos que se especifique MB_DEFBUTTON2, MB_DEFBUTTON3 o MB_DEFBUTTON4 .

MB_DEFBUTTON2
0x00000100L
El segundo botón es el predeterminado.
MB_DEFBUTTON3
0x00000200L
El tercer botón es el predeterminado.
MB_DEFBUTTON4
0x00000300L
El cuarto botón es el predeterminado.
 

Para indicar la modalidad del cuadro de diálogo, especifique uno de los valores siguientes.

Valor Significado
MB_APPLMODAL
0x00000000L
El usuario debe responder al cuadro de mensaje antes de continuar trabajando en la ventana identificada por el parámetro hWnd . Sin embargo, el usuario puede pasar a las ventanas de otros subprocesos y trabajar en esas ventanas.

Según la jerarquía de ventanas de la aplicación, es posible que el usuario pueda moverse a otras ventanas del subproceso. Todas las ventanas secundarias del elemento primario del cuadro de mensaje se deshabilitan automáticamente, pero las ventanas emergentes no.

MB_APPLMODAL es el valor predeterminado si no se especifica ni MB_SYSTEMMODALni MB_TASKMODAL .

MB_SYSTEMMODAL
0x00001000L
Igual que MB_APPLMODAL excepto que el cuadro de mensaje tiene el estilo WS_EX_TOPMOST . Use cuadros de mensaje modales del sistema para notificar al usuario si hay errores graves y potencialmente perjudiciales que requieren atención inmediata (por ejemplo, quedarse sin memoria). Esta marca no tiene ningún efecto en la capacidad del usuario de interactuar con ventanas distintas de las asociadas a hWnd.
MB_TASKMODAL
0x00002000L
Igual que MB_APPLMODAL excepto que todas las ventanas de nivel superior que pertenecen al subproceso actual están deshabilitadas si el parámetro hWnd es NULL. Use esta marca cuando la aplicación o biblioteca que realiza la llamada no tenga disponible un identificador de ventana, pero debe evitar la entrada a otras ventanas del subproceso que realiza la llamada sin suspender otros subprocesos.
 

Para especificar otras opciones, use uno o varios de los valores siguientes.

Valor Significado
MB_DEFAULT_DESKTOP_ONLY
0x00020000L
Igual que el escritorio de la estación de ventana interactiva. Para obtener más información, vea Estaciones de ventana.

Si el escritorio de entrada actual no es el escritorio predeterminado, MessageBox no devuelve hasta que el usuario cambia al escritorio predeterminado.

MB_RIGHT
0x00080000L
El texto está justificado a la derecha.
MB_RTLREADING
0x00100000L
Muestra el mensaje y subtítulo texto mediante el orden de lectura de derecha a izquierda en los sistemas hebreo y árabe.
MB_SETFOREGROUND
0x00010000L
El cuadro de mensaje se convierte en la ventana de primer plano. Internamente, el sistema llama a la función SetForegroundWindow para el cuadro de mensaje.
MB_TOPMOST
0x00040000L
El cuadro de mensaje se crea con el estilo de ventana WS_EX_TOPMOST .
MB_SERVICE_NOTIFICATION
0x00200000L
El autor de llamada es un servicio que notifica al usuario sobre un evento. La función muestra un cuadro de mensaje en el escritorio activo actual, incluso si no hay ningún usuario que haya iniciado sesión en el equipo.

Terminal Services: Si el subproceso que llama tiene un token de suplantación, la función dirige el cuadro de mensaje a la sesión especificada en el token de suplantación.

Si se establece esta marca, el parámetro hWnd debe ser NULL. Esto es para que el cuadro de mensaje pueda aparecer en un escritorio distinto del escritorio correspondiente al hWnd.

Para obtener información sobre las consideraciones de seguridad relacionadas con el uso de esta marca, consulte Interactive Services. En concreto, tenga en cuenta que esta marca puede producir contenido interactivo en un escritorio bloqueado y, por lo tanto, debe usarse solo para un conjunto muy limitado de escenarios, como el agotamiento de recursos.

Valor devuelto

Tipo: int

Si un cuadro de mensaje tiene un botón Cancelar , la función devuelve el valor IDCANCEL si se presiona la tecla ESC o se selecciona el botón Cancelar . Si el cuadro de mensaje no tiene ningún botón Cancelar , presionar ESC no tendrá ningún efecto, a menos que haya un botón MB_OK presente. Si se muestra un botón de MB_OK y el usuario presiona ESC, el valor devuelto será IDOK.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Si la función se ejecuta correctamente, el valor devuelto es uno de los siguientes valores de elemento de menú.

Código o valor devuelto Descripción
IDABORT
3
Se ha seleccionado el botón Anular .
IDCANCEL
2
Se ha seleccionado el botón Cancelar .
IDCONTINUE
11
Se ha seleccionado el botón Continuar .
IDIGNORE
5
Se ha seleccionado el botón Omitir .
IDNO
7
Se ha seleccionado el botón No .
IDOK
1
Se ha seleccionado el botón Aceptar .
IDRETRY
4
Se ha seleccionado el botón Reintentar .
IDTRYAGAIN
10
Se ha seleccionado el botón Probar de nuevo .
IDYES
6
Se ha seleccionado el botón .

Comentarios

Los siguientes iconos del sistema se pueden usar en un cuadro de mensaje estableciendo el parámetro uType en el valor de marca correspondiente.

Icono Valores de marca
Icono de MB_ICONHAND, MB_ICONSTOP y MB_ICONERROR MB_ICONHAND, MB_ICONSTOP o MB_ICONERROR
Icono de MB_ICONQUESTION MB_ICONQUESTION
Icono de MB_ICONEXCLAMATION y MB_ICONWARNING MB_ICONEXCLAMATION o MB_ICONWARNING
Icono de MB_ICONASTERISK y MB_ICONINFORMATION MB_ICONASTERISK o MB_ICONINFORMATION
 

La adición de dos marcas de derecha a izquierda (RLM), representadas por el carácter de formato Unicode U+200F, al principio de una cadena de presentación del Cuadro de mensajes se interpreta mediante el motor de representación cuadro de mensajes para que el orden de lectura del cuadro de mensajes se represente como de derecha a izquierda (RTL).

Cuando se usa un cuadro de mensaje modal del sistema para indicar que el sistema tiene poca memoria, las cadenas a las que apuntan los parámetros lpText y lpCaption no se deben tomar de un archivo de recursos porque se puede producir un error al intentar cargar el recurso.

Si crea un cuadro de mensaje mientras un cuadro de diálogo está presente, use un identificador para el cuadro de diálogo como parámetro hWnd . El parámetro hWnd no debe identificar una ventana secundaria, como un control en un cuadro de diálogo.

Ejemplos

En el ejemplo siguiente, la aplicación muestra un cuadro de mensaje que solicita al usuario una acción después de que se haya producido una condición de error. El cuadro de mensaje muestra el mensaje que describe la condición de error y cómo resolverla. El estilo MB_CANCELTRYCONTINUE dirige MessageBox para proporcionar tres botones con los que el usuario puede elegir cómo continuar. El estilo MB_DEFBUTTON2 establece el foco predeterminado en el segundo botón del cuadro de mensaje, en este caso, el botón Volver a intentar .

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

En la imagen siguiente se muestra la salida del ejemplo de código anterior:

Cuadro de mensaje

Para ver otro ejemplo de cuadro de mensaje, vea Mostrar un cuadro de mensaje.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado winuser.h (incluya Windows.h)
Library User32.lib
Archivo DLL User32.dll
Conjunto de API ext-ms-win-ntuser-dialogbox-l1-1-0 (introducido en Windows 8)

Consulte también

Conceptual

Cuadros de diálogo

FlashWindow

MessageBeep

MessageBoxEx

MessageBoxIndirect

Otros recursos

Referencia

SetForegroundWindow