MessageBox

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons.

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

Parameters

hWnd

[in] Handle to the owner window of the message box to be created. If this parameter is NULL, the message box has no owner window.

lpText

[in] Long pointer to a null-terminated string that contains the message to be displayed.

lpCaption

[in] Long pointer to a null-terminated string used for the dialog box title. If this parameter is NULL, the default title "Error" is used.

uType

[in] Specifies a set of bit flags that determine the contents and behavior of the dialog box. This parameter can be a combination of flags from the following groups of flags.

Specify one of the following flags to indicate the buttons contained in the message box:

Value	Description
MB_ABORTRETRYIGNORE	The message box contains three push buttons: Abort, Retry, and Ignore.
MB_OK	The message box contains one push button: OK. This is the default.
MB_OKCANCEL	The message box contains two push buttons: OKand Cancel.
MB_RETRYCANCEL	The message box contains two push buttons: Retryand Cancel.
MB_YESNO	The message box contains two push buttons: Yesand No.
MB_YESNOCANCEL	The message box contains three push buttons: Yes, No, and Cancel.

Specify one of the following flags to display an icon in the message box:

Value	Description
MB_ICONEXCLAMATION, MB_ICONWARNING	An exclamation-point icon appears in the message box.
MB_ICONINFORMATION, MB_ICONASTERISK	An icon consisting of a lowercase letter iin a circle appears in the message box.
MB_ICONQUESTION	A question-mark icon appears in the message box.
MB_ICONSTOP, MB_ICONERROR, MB_ICONHAND	A stop-sign icon appears in the message box.

Specify one of the following flags to indicate the default button:

Value	Description
MB_DEFBUTTON1	The first button is the default button. MB_DEFBUTTON1 is the default unless MB_DEFBUTTON2, MB_DEFBUTTON3, or MB_DEFBUTTON4 is specified.
MB_DEFBUTTON2	The second button is the default button.
MB_DEFBUTTON3	The third button is the default button.
MB_DEFBUTTON4	The fourth button is the default button.

The following flag is the default modality of the dialog box:

Value	Description
MB_APPLMODAL	The user must respond to the message box before continuing work in the window identified by the hWndparameter. However, the user can move to the windows of other threads and work in those windows. Depending on the hierarchy of windows in the application, the user may be able to move to other windows within the thread. All child windows of the parent of the message box are automatically disabled, but popup windows are not.

Value

Description

MB_APPLMODAL

The user must respond to the message box before continuing work in the window identified by the hWndparameter. However, the user can move to the windows of other threads and work in those windows.

Depending on the hierarchy of windows in the application, the user may be able to move to other windows within the thread. All child windows of the parent of the message box are automatically disabled, but popup windows are not.

In addition, you can specify the following flags:

Value	Description
MB_SETFOREGROUND	The message box becomes the foreground window. Internally, the system calls the SetForegroundWindowfunction for the message box.
MB_TOPMOST	The message box is created with the WS_EX_TOPMOST window style.

Return Values

Zero indicates that there is not enough memory to create the message box.

Upon success, one of the values described in the following table is returned.

Value	Description
IDABORT	Abortbutton was selected.
IDCANCEL	Cancelbutton was selected.
IDIGNORE	Ignorebutton was selected.
IDNO	Nobutton was selected.
IDOK	OKbutton was selected.
IDRETRY	Retrybutton was selected.
IDYES	Yesbutton was selected.

If a message box has a Cancelbutton, the function returns the IDCANCEL value if either the ESC key is pressed or the Cancelbutton is selected. If the message box has no Cancelbutton, pressing ESC has no effect.

Remarks

If you create a message box while a dialog box is present, use the handle of the dialog box as the hWndparameter. The hWndparameter should not identify a child window, such as a control in a dialog box.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	1.0 and later	Winuser.h		Msgbox.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

MessageBeep, SetForegroundWindow