Función MessageBoxA (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 clic el usuario.

Sintaxis

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

Parámetros

[in, optional] hWnd

Tipo: HWND

Identificador de la ventana 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

El contenido y el 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: Sí y No.
MB_YESNOCANCEL 0x00000003L	El cuadro de mensaje contiene tres botones de inserción: Sí, 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 Sí .

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
	MB_ICONHAND, MB_ICONSTOP o MB_ICONERROR
	MB_ICONQUESTION
	MB_ICONEXCLAMATION o MB_ICONWARNING
	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 de MB_DEFBUTTON2 establece el foco predeterminado en el segundo botón del cuadro de mensaje, en este caso, el botón Intentar de nuevo .

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:

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

Nota

El encabezado winuser.h define MessageBox como un alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

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