winuser.h


MessageBox

La función MessageBox crea, muestra y ejecuta un cuadro de mensaje. El cuadro de mensaje contiene un mensaje definido por la aplicación y un título, y además cualquier combinación de iconos predefinidos y botones.

Sintaxis

int MessageBox(
    HWND hWnd,          // manipulador de la ventana propietaria
    LPCTSTR lpText,     // dirección del texto del mensaje
    LPCTSTR lpCaption,  // dirección del texto del título
    UINT uType          // estilo del cuadro de mensaje
   );

Parámetros:

hWnd: identifica a la ventana propietaria del cuadro de mensaje a crear. Si este parámetro es NULL, el cuadro de mensaje no tendrá ventana propietaria.

lpText: apunta a una cadena terminada en cero que contiene el mensaje a mostrar.

lpCaption: apunta a una cadena terminada en cero usada como título para el cuadro de diálogo. Si este parámetro es NULL, se usará el título por defecto de Error.

uType: especifica el contenido y comportamiento del cuadro de diálogo. Este parámetro puede ser una combinación de los siguientes valores:

Valor Significado
MB_ABORTRETRYIGNORE El cuadro de mensaje contiene tres botones: Anular, Reintentar e Omitir.
MB_APPLMODAL El usuario debe responder al cuadro de diálogo antes de continuar trabajando en la ventana identificada por el parámetro hWnd. Sin embargo, el usuario puede trasladarse a ventanas de otras aplicaciones y trabajar en sus ventanas.
Dependiendo de la jerarquía de ventanas de la aplicación, el usuario puede estar capacitado para moverse a otras ventanas dentro de la misma aplicación. Todas las ventanas hija de la ventana padre del cuadro de mensaje serán automáticamente deshabilitadas, pero las ventanas popup no.
MB_APPLMODAL es el valor por defecto si no se especifica MB_SYSTEMMODAL ni MB_TASKMODAL.
MB_DEFAULT_DESKTOP_ONLY El escritorio que actualmente recibe la entrada debe ser el escritorio por defecto; en otro caso, la función falla. Un escritorio por defecto es aquel en que una aplicación se ejecuta después de que el usuario ha hecho logon.
MB_DEFBUTTON1 El primer botón es el botón por defecto. Observa que el primer botón es siempre el botón por defecto salvo que se especifique MB_DEFBUTTON2, MB_DEFBUTTON3 o MB_DEFBUTTON4.
MB_DEFBUTTON2 El segundo botón es el botón por defecto.
MB_DEFBUTTON3 El tercer botón es el botón por defecto.
MB_DEFBUTTON4 El cuarto botón es el botón por defecto.
MB_HELP Windows 95: añade un botón de ayuda al cuadro de mensaje. Pulsando el botón de ayuda o la tecla F1 se genera un evento de ayuda.
MB_ICONASTERISK Igual que MB_ICONINFORMATION.
MB_ICONERROR Windows 95: igual que MB_ICONHAND.
MB_ICONEXCLAMATION Se mostrará un icono de exclamación.
MB_ICONHAND Lo mismo que MB_ICONSTOP.
MB_ICONINFORMATION Se mostrará un icono que consiste en una 'i' minúscula en in bocadillo
MB_ICONQUESTION Se mostrará un icono con una interrogación.
MB_ICONSTOP Se mostrará un icono con un signo de stop.
MB_ICONWARNING Windows 95: igual que MB_ICONEXCLAMATION.
MB_OK El cuadro de mensaje contiene un único botón de Aceptar.
MB_OKCANCEL El cuadro de mensaje contiene dos botones: Aceptar y Cancelar.
MB_RETRYCANCEL El cuadro de mensaje contiene dos botones: Reintentar y Cancelar.
MB_RIGHT Windows 95: El texto estará justificado a la derecha.
MB_RTLREADING Windows 95: Muestra el mensaje y el título usando el sentido de lectura de derecha a izquierda en sistemas Hebreos y árabes.
MB_SERVICE_NOTIFICATION Windows NT: el proceso que llama al cuadro de mensaje es un servicio que informa al usuario de un evento. La función muestra un cuadro de mensaje en el escritorio activo aunque no exista ningún usuario activo en el ordenador.
Si este flag está activo, el parámetro hWnd debe ser NULL. Este el cuadro de mensaje también puede aparecer en un escritorio diferente del correspondiente al de hWnd.
MB_SETFOREGROUND El cuadro de mensaje se convierte en la ventana de primer plano. Internamente, Windows calla a la función SetForegroundWindow para el cuadro de mensaje.
MB_SYSTEMMODAL Todas las aplicaciones son suspendidas hasta que el usuario responda al cuadro de mensaje. A no ser que la aplicación especifique MB_ICONHAND, el cuadro de mensaje no se hace modal hasta después de creado; consecuentemente, la ventana propietaria y otras ventanas continúan recibiendo mensajes resultantes de su activación. Usar cuadros de mensaje system-modal para notificar al usuario de serios y errores que potencialmente puedan dañar y requieran atención inmediata (por ejemplo, ejecución sin memoria).
MB_TASKMODAL Lo mismo que MB_APPLMODAL excepto que todas las ventanas de mayor nivel pertenecientes al proceso (task) actual serán deshabilitadas si el parámetro hWnd es NULL. Usar este flag cuando la aplicación o biblioteca que la llama no tiene un manipulador de ventana disponible pero necesita impedir una entrada a otras ventanas de la aplicación actual sin suspender otras aplicaciones.
MB_YESNO El cuadro de mensaje contiene dos botones: Sí y No.
MB_YESNOCANCEL El cuadro de mensaje contiene tres botones: Sí, No y Cancelar.

Valor de retorno

El valor de retorno es cero si no ha suficiente memoria para crear el cuadro de mensaje.

Si la función tiene éxito, el valor de retorno es uno de los siguientes valores de ítem de menú devueltos por el cuadro de diálogo:

Valor Significado
IDABORT Se seleccionó el botón de Anular.
IDCANCEL Se seleccionó el botón de Cancelar.
IDIGNORE Se seleccionó el botón de Omitir.
IDNO Se seleccionó el botón de No.
IDOK Se seleccionó el botón de Aceptar.
IDRETRY Se seleccionó el botón de Reintentar.
IDYES Se seleccionó el botón de Sí.

Si un cuadro de mensaje contiene un botón de Cancelar, la función devuelve el valor IDCANCEL tanto si se pulsa la tecla ESC como si se pulsa el botón de Cancelar. Si el cuadro de mensaje no tiene el botón de Cancelar, presionar ESC no tiene efecto.

Observaciones

Cuando uses un cuadro de mensaje de tipo para indicar que el sistema está bajo de memoria, las cadenas apuntadas por los parámetros lpText y lpCaption no deben ser tomados desde un fichero de recursos, porque un intento de cargar un recurso podría fallar.

Cuando una aplicación llama a MessageBox y especifica los flags MB_ICONHAND y MB_SYSTEMMODAL para el parámetro uType, Windows muestra el cuadro de mensaje resultante independientemente de la memoria disponible. Cuando esos flags son especificados, Windows limita la longitud del texto del mensaje a tres líneas. Windows no rompe automáticamente las líneas para que quepan en el cuadro de mensaje, así que la cadena del mensaje debe contener retornos de línea para separar las líneas en los lugares apropiados.

Si creas un cuadro de mensaje mientras un cuadro de diálogo está abierto, usa el manipulador del cuadro de diálogo como parámetro para hWnd. El parámetro hWnd no debe identificar a una ventana hija como por ejemplo un control de un cuadro de diálogo.

Sólo en Windows 95: el sistema puede soportar un máximo de 16,364 manipuladores de ventana.