MessageBoxEx

The MessageBoxEx function creates and displays a window that contains an application-supplied message and caption, plus any combination of the predefined icons and push buttons. The wLanguageId parameter specifies which set of language resources is used for the predefined push buttons. See the description of the MessageBox function for full descriptions of the other parameters of MessageBoxEx.

Parameters

hwndOwner

Identifies the window that owns the message box.

lpText

Points to a null-terminated string containing the message to be displayed.

lpCaption

Points to a null-terminated character string to be used for the dialog-box caption. If the lpCaption parameter is NULL, the default caption “Error” is used.

dwType

Specifies the contents of the dialog box.

wLanguageID

Specifies the language that the text contained in the predefined push buttons is displayed in. This value must be in the form returned by the MAKELANGID macro. See the table following the Comments section for a description of the possible primary language IDs and sublanguage IDs.

Return Value

If the function fails, the return value is zero, in which case extended error information can be obtained by calling the GetLastError function.

If the function is successful, the return value is a non-zero menu-item value returned by the dialog box. Here are the values and their meanings:

If a message box has a Cancel button, the IDCANCEL value will be returned if either the ESCAPE key or Cancel button is pressed. If the message box has no Cancel button, pressing the ESCAPE key has no effect.

Comments

The MessageBoxEx function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set

When a system-modal message box is created to indicate that the system is low on memory, the strings passed as the lpText and lpCaption parameters should not be taken from a resource file, since an attempt to load the resource may fail.

When an application calls the MessageBox function and specifies the MB_ICONHAND and MB_SYSTEMMODAL flags for the dwType parameter, Windows32 will display the resulting message box regardless of available memory. When these flags are specified, Windows32 limits the length of the message-box text to one line.

If a message box is created while a dialog box is present, use the handle of the dialog box as the hwndOwner parameter. The hwndParent parameter should not identify a child window, such as a dialog-box control.

Here is a table showing the possible language IDs and sublanguage IDs, along with descriptions:

Table R.1 Primary Language IDs and Sublanguage IDs

See Also

MessageBox, MessageBeep