The message box consists of a message and a simple dialog with the user.

This function behaves in a similar way to WinDlgBox, and the remarks concerning modality which are documented under that call, and also under the WinLoadDlg and WinProcessDlg functions, also apply here.

This function should not be used while pointing device capture is set (see WinSetCapture).

If the keyboard is used to cycle from one window to the next, the message box and its parent window are considered to be next to each other in the sequence.

If a message box is created as part of the processing of a dialog window, where the dialog window has not been dismissed, the dialog window should be made the owner of the message box window.

If a system modal message box is created to indicate to the user that the system is running out of memory, the strings passed into this call must not be taken from a resource file, as an attempt to load the resource file could fail because of the lack of memory. However, such a message box can safely use the hand icon because this icon is always memory-resident.

The size of the message box is determined as follows:

• The minimum width of a message box is enough to display 40 characters of average width.

• The minimum height of a message box is enough to display 2 lines.

• The text of a message box is word-wrapped by default. If more than two lines are required to display the text, the height of the message box is increased up to a maximum of two thirds of the screen height. The height of a message box can never exceed this value.

• If necessary, the width of a message box is increased to allow room to display the title.

Text is wrapped at word boundaries (spaces). If a word is too big to fit on one line, the start of the word is not wrapped to the next line, but stays adjacent to the text it follows, and the word is split at the box boundary.

The message box is centered on the screen.

If a message box window has a CANCEL button, the MBID_CANCEL value is returned if either the Escape key is pressed or the Cancel button is selected. If the message box window has no CANCEL button, pressing the Escape key has no effect.

Note: If a dialog box or a message box is up for a window, and the parent or owner of that window is destroyed, the code following the WinDlgBox or WinMessageBox call is executed even though the parent/owner window no longer exists. This can result in accessing data that no longer exists; especially data referenced in the window words. Therefore, it is extremely important to determine the state of your child-window procedure after this function returns. The most straightforward method for doing this is to call WinQueryWindowPtr to get a pointer to the window words. If the returned pointer is NULL, then you should exit immediately. Should this be the case, the bottom-up rule (that is, the child window gets WM_DESTROY messages first, then the parent window) still applies, and it becomes the child window procedure's responsibility to exit gracefully.