IConsole::MessageBox

[This is preliminary documentation and subject to change.]

Displays a message box.

HRESULT MessageBox(
  LPCWSTR lpszText,  // Pointer to the text to be displayed
  LPCWSTR lpszTitle, // Pointer to the title of the box
  UINT fuStyle,      // Style of the message box
  int * piRetval     // Pointer to the return value
);

Parameter

lpszText

[in] Pointer to a null-terminated string containing the message to be displayed.

lpszTitle

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

fuStyle

[in] Specifies a set of bit flags that determine the contents and behavior of the message box. This parameter can be a combination of flags from the following groups of flags taken from the documentation for the Win32 MessageBox function in the Platform SDK, under the uType parameter.

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

Flag Meaning

MB_ABORTRETRYIGNORE The message box contains three buttons: Abort, Retry, and Ignore.

MB_OK The message box contains one button: OK. This is the default.

MB_OKCANCEL The message box contains two buttons: OK and Cancel.

MB_RETRYCANCEL The message box contains two buttons: Retry and Cancel.

MB_YESNO The message box contains two buttons: Yes and No.

MB_YESNOCANCEL The message box contains three push buttons: Yes, No, and Cancel.

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

Specify one of the following flags to indicate which icon appears in the message box:

Flag Meaning

MB_ICONEXCLAMATION, MB_ICONWARNING An exclamation-point icon appears in the message box.

MB_ICONINFORMATION, MB_ICONASTERISK An icon consisting of an "I" in 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.

Flag	Meaning
MB_ICONEXCLAMATION, MB_ICONWARNING	An exclamation-point icon appears in the message box.
MB_ICONINFORMATION, MB_ICONASTERISK	An icon consisting of an "I" in 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:

Flag Meaning

MB_DEFBUTTON1 The first button is the default button unless one of the other flags in this group is specified as the default.

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.

Flag	Meaning
MB_DEFBUTTON1	The first button is the default button unless one of the other flags in this group is specified as the default.
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.

Specify one of the following flags to indicate the modality of the dialog box:

Flag Meaning

MB_APPLMODAL The User must respond to the message box before continuing work in the current window. However, the user can move to the windows of other applications and work in those windows. The default is MB_APPLMODAL if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified.

MB_SYSTEMMODAL All applications are suspended until the user responds to the message box. System-modal message boxes are used to notify the user of serious, potentially damaging errors that require immediate attention and should be used sparingly.

MB_TASKMODAL Similar to MB_APPLMODAL, but not useful within a Microsoft Foundation class application. This flag is reserved for a calling application or library that does not have a window handle available.

Flag	Meaning
MB_APPLMODAL	The User must respond to the message box before continuing work in the current window. However, the user can move to the windows of other applications and work in those windows. The default is MB_APPLMODAL if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified.
MB_SYSTEMMODAL	All applications are suspended until the user responds to the message box. System-modal message boxes are used to notify the user of serious, potentially damaging errors that require immediate attention and should be used sparingly.
MB_TASKMODAL	Similar to MB_APPLMODAL, but not useful within a Microsoft Foundation class application. This flag is reserved for a calling application or library that does not have a window handle available.

In addition, you can specify the following flags:

Flag Meaning

MB_DEFAULT_DESKTOP_ONLY The desktop currently receiving input must be a default desktop; otherwise, the function fails. A default desktop is one an application runs on after the user has logged on.

MB_HELP Adds a Help button to the message box. Choosing the Help button or pressing F1 generates a Help event.

MB_RIGHT The text is right-justified.

MB_RTLREADING Displays message and caption text using right-to-left reading order on Hebrew and Arabic systems.

MB_SETFOREGROUND The message box becomes the foreground window. Internally, the operating system calls the Win32 SetForegroundWindow function for the message box.

MB_TOPMOST The message box is created with the WS_EX_TOPMOST window style.

MB_SERVICE_NOTIFICATION TBD

MB_SERVICE_NOTIFICATION_NT3x TBD

piRetval

[out] Pointer to the return value.

Flag	Meaning
MB_DEFAULT_DESKTOP_ONLY	The desktop currently receiving input must be a default desktop; otherwise, the function fails. A default desktop is one an application runs on after the user has logged on.
MB_HELP	Adds a Help button to the message box. Choosing the Help button or pressing F1 generates a Help event.
MB_RIGHT	The text is right-justified.
MB_RTLREADING	Displays message and caption text using right-to-left reading order on Hebrew and Arabic systems.
MB_SETFOREGROUND	The message box becomes the foreground window. Internally, the operating system calls the Win32 SetForegroundWindow function for the message box.
MB_TOPMOST	The message box is created with the WS_EX_TOPMOST window style.
MB_SERVICE_NOTIFICATION	TBD
MB_SERVICE_NOTIFICATION_NT3x	TBD

Return Values

S_OK: The header was successfully set.
E_UNEXPECTED: An unexpected error occurred.
E_INVALIDARG: The parameter is invalid. This may indicate a NULL pointer.