The simplest message box is used to display a message to the user. This type of message box is equipped with only one button, labeled OK. Here is an example:
Figure 34: A Simple Message Box
A more elaborate or detailed message box can display an icon and/or can have more than one button:
To create a message box, the Win32 library provides a global function called MessageBox. Its syntax is:
int MessageBox(HWND hWnd, LPCTSTR lpText, LPCTSTR lpCaption, UINT uType);
If you want to use this version from Win32, because it is defined outside of MFC, you should start it with the scope access operator “::” as follows:
::MessageBox(. . .);
As we will see shortly, the Win32's MessageBox() function requires a handle (not necessarily difficult to provide but still). To make the creation of a message a little easier, the MFC library provides its own version of the MessageBox() function. Its syntax is:
int MessageBox(LPCTSTR lpszText, LPCTSTR lpszCaption = NULL, UINT nType = MB_OK);
To still make it easier, the MFC framework provides the AfxMessageBox function used to create a message box. Although this function is global, its scope is limited to MFC applications. This means that you can use the Win32's global MessageBox() function with any compiler used on the Microsoft Windows operating systems but you cannot use the MFC's global AfxMessageBox() function with any compiler other Visual C++. The AfxMessageBox() function is overloaded with two versions whose syntaxes are:
int AfxMessageBox(LPCTSTR lpszText, UINT nType = MB_OK, UINT nIDHelp = 0); int AFXAPI AfxMessageBox(UINT nIDPrompt, UINT nType = MB_OK, UINT nIDHelp = (UINT) -1);
Based on the above functions, a message box can be illustrated as follows:
As seen above, you have the choice among three functions to create a message. There is no valid reason that makes one of them better than the other. They do exactly the same thing. The choice will be based on your experience and other factors.
If you decide to use the Win32's MessageBox() function, you must specify the handle to the application that created the message box. As we will learn eventually when we study controls, you can get a handle to a (CWnd-derived) control with a call to m_hWnd. For example, if a button on a dialog box initiates the message box, you can start this function as follows:
We also saw that you can get a pointer to the main window by calling the MFC's global AfxGetMainWnd() function. This function only points you to the application. To get a handle to the application, you can call the same m_hWnd member variable. In this case, the message box can be started with:
If you are creating a message but do not want a particular window to own it, pass this hWnd argument as NULL.
If you decide to call the AfxMessageBox() function, as seen previously, you have two options. You can pass a string as argument. Here is an example:
AfxMessageBox(L"Welcome to Microsoft Foundation Class Library.");
An alternative is to pass a string identifier from a resource file.
For all the message box functions, the Text argument a null-terminated string. It specifies the text that would be displayed to the user. This argument is required. Here is an example that uses the MessageBox() function:
AfxMessageBox(L"The name you entered is not in our records");
If you want to display the message on various lines, you can separate sections with the new line character '\n'. Here is an example:
AfxMessageBox(L"If you think there is a mistake,\nplease contact Human Resources");
If the message you are creating is too long to fit on one line, you can separate lines by ending each with a double-quote and starting the next line with a new double-quote. As long as you have not closed the function, the string would be considered as one entity. You can also use string editing and formatting techniques to create a more elaborate message. This means that you can use functions of the C string library to create your message.
The caption of the message box is the text that displays on its title bar. If you create a message box using the AfxMessageBox() function, it allows you to specify only one argument, namely the text to display to the user, which is the value of the Text argument. In this case, the title bar of the message box would display the name of the application that "owns" the message box.
If you want to display your own caption on the title bar, call the MessageBox() function. Specify the argument for the caption. The Caption argument is a null-terminated string that would display on the title bar of the message box. Here is an example:
MessageBox(NULL, L"Due to an unknown internal error, this application will now close.", L"Regular Warning", 0);
Although the Caption argument is optional in the MFC,s MessageBox() and the AfxMessageBox() functions, it is required for the Win32's MessageBox() function. Because it is in fact a pointer, you can pass it as NULL. Here is an example:
MessageBox(NULL, L"Due to an unknown internal error, this application will now close.", NULL, 0);
In this case, the title bar of the message box would display Error:
This caption may not be friendly on most applications and could appear frightening to the user. Therefore, unless you are in a hurry, you should strive to provide a friendly and more appropriate title.
The uType argument is used to provide some additional options to the message box. First, it is used to display one or a few buttons. The buttons depend on the value specified for the argument. If this argument is not specified, the message box displays (only) OK. Otherwise, you can display a message box with a combination of selected buttons.
To display one or more buttons, the uType argument uses a constant value that controls what button(s) to display. The values and their buttons can be specified as follows:
Here is an example:
AfxMessageBox(L"Due to an unknown internal error, this application will now close.\n" L"Do you want to save the file before closing?", MB_YESNO);
Besides the buttons, the message box can also display an icon that accompanies the message. Each icon is displayed by specifying a constant integer. The values and their buttons are as follows:
The icons are used in conjunction with the buttons constant. To combine these two flags, use the bitwise OR operator “|”. Here is an example:
AfxMessageBox(L"Due to an unknown internal error, this application will now close.\n" L"Do you want to save the file before closing?", MB_YESNO | MB_ICONWARNING);
When a message box is configured to display more than one button, the operating system is set to decide which button is the default. The default button has a thick border that sets it apart from the other button(s). If the user presses Enter, the message box would behave as if the user had clicked the default button. Fortunately, if the message box has more than one button, you can decide what button would be the default.
To specify the default button, add one of the following constants to the uType combination:
To specify the default button, use the bitwise OR operator "|" to combine the constant integer of the desired default button with the button's constant and the icon.
After using the message box, the user must close it by clicking a button on it. Clicking OK usually means that the user acknowledged the message. Clicking Cancel usually means the user is changing his or her mind about the action performed previously. Clicking Yes instead of No usually indicates that the user agrees with whatever is going on.
In reality, the message box only displays a message and one or a few buttons. The function used to create the message box returns a natural number that you can use as you see fit. The return value itself is a registered constant integer and can be one of the following: