MSDN / Documentation / Windows / API Reference / Win32 Functions / Shell32 / MessageBox

MessageBox

Displays a modal dialog box that can display an application-defined icon, a set of buttons, and a set of additional controls.

Syntax

int MessageBox(
    HWND    hWnd,
    LPCTSTR lpText,
    LPCTSTR lpCaption,
    UINT    uType
);

Parameters

Parameter Description
hWnd Handle to the owner window of the dialog box. If this parameter is NULL, the message box has no owner window.
lpText Pointer to a null-terminated string that is displayed as the message.
lpCaption Pointer to a null-terminated string that is displayed in the caption bar of the dialog box. If this parameter is NULL, the application name is used as the caption bar.
uType The contents and behavior of the dialog box. This parameter can be a combination of flags that control the number of buttons, the icon displayed, the default button, and modality. See MessageBox Styles for a full list of flags.

Return Value

Value Description
IDOK, IDCANCEL, IDABORT, IDRETRY, IDIGNORE, IDYES, IDNO The return value indicates which of the buttons the user clicked.
IDTRYAGAIN Returned by MessageBoxTimeout.
IDCONTINUE Returned by MessageBoxTimeout.

Remarks

The MessageBox function creates, displays, and operates a message box. A message box is a dialog box that displays a specified amount of information to the user, and obtains a response from the user.

The uType parameter can specify various combinations of the following:

  • Button Styles: MB_OK, MB_OKCANCEL, MB_YESNO, MB_YESNOCANCEL, etc.
  • Icon Styles: MB_ICONERROR, MB_ICONQUESTION, MB_ICONWARNING, MB_ICONINFORMATION.
  • Default Button Styles: MB_DEFBUTTON1, MB_DEFBUTTON2, etc.
  • Modality Styles: MB_APPLMODAL, MB_SYSTEMMODAL.

For example, to display a critical error message with OK and Cancel buttons:

int msgBoxResult = MessageBox(
    NULL,
    TEXT("An error occurred. Do you want to try again?"),
    TEXT("Application Error"),
    MB_ICONERROR | MB_RETRYCANCEL
);

if (msgBoxResult == IDRETRY) {
    // Retry logic
} else {
    // Handle cancel or other response
}

Requirements

Description
SDK Header: winuser.h, Library: User32.lib
Minimum supported client Windows 2000 Professional
Minimum supported server Windows 2000 Server
Header winuser.h (include Windows.h)
Library User32.lib
DLL User32.dll

Example Code

A simple example demonstrating the use of MessageBox to display an informational message:

#include <windows.h>

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
{
    MessageBox(
        NULL,                               // No owner window
        TEXT("This is an informational message from your application."), // Message text
        TEXT("Information"),                // Caption bar text
        MB_OK | MB_ICONINFORMATION          // OK button and information icon
    );
    return 0;
}

Note

It's generally recommended to use MessageBoxEx for more advanced customization, or to use the appropriate Unicode (MessageBoxW) or ANSI (MessageBoxA) versions directly depending on your project's character set.

Related Topics