Fundamental Message Boxes

Introduction

To support message boxes, the Win32 library provides a function named MessageBox(). Its syntax is:

int __fastcall MessageBox(const char * Message,
	                  const char * Caption,
	                  int Flags);

The MessageBox() function takes three arguments. The first argument, Message, is a null-terminated string representing the message that the user would read. The Message string could be a static sentence. It could be constructed from another control. Or it could be a combination of different strings appended using C/C++ string functions and operations.

You can create a simple message box similar to one implemented using the ShowMessage() function to display a simple message with an OK button. In this case, you would provide only the Message argument. Passed the other two arguments as NULL. Here is an example:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
	Application->MessageBox("This operation can only be "
				"performed by an administrator.",
				 NULL, NULL);
	return 0;
}
//---------------------------------------------------------------------------

The second argument, also a string, is the caption that would display on the title bar of the dialog box. You can also set it when creating the message box or you can build it from what would be available at runtime. If you do not have a caption, you can set the value of this argument as NULL. In that case the title bar would display Error. For example, the above code would produce:

Therefore, to create a less boring message box, provide the Caption argument. Here is an example:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
	Application->MessageBox("Make sure the music is playing.",
				"CD PLayer Instructions",
				NULL);
	return 0;
}
//---------------------------------------------------------------------------

This would produce:

The third argument specifies the flags that would display on the dialog box: one or more buttons and an optional picture. Besides, or apart from, the OK button, if you want to display other buttons, you can pass the third argument with one of the following constants:

Constant	Buttons
MB_OK
MB_OKCANCEL
MB_ABORTRETRYIGNORE
MB_YESNOCANCEL
MB_YESNO
MB_RETRYCANCEL
MB_HELP

You can create a simple message box with OK as the only button. In that case, set the third argument as MB_OK. Here is an example:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
	Application->MessageBox("Make sure the music is playing.",
				"CD PLayer Instructions", MB_OK);
	return 0;
}
//---------------------------------------------------------------------------

This would produce:

To create a message box that displays the Yes and No buttons, you could write:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
	Application->MessageBox("Do you hear any music now or any sound at all?",
				"CD Player Instructions", MB_YESNO);
	return 0;
}
//---------------------------------------------------------------------------

This would produce:

If you provide the MB_HELP as the only button, the message box would display with an OK and a Help buttons.

To enhance a dialog box and accentuate its message, you can display an icon using one of the Win32 defined integer constants. Although you can use any icon with any button, you should be selective and make sure that the appearance of the icon you use is in accordance with the message. To specify the icon, you use one of the following constants:

Value	Icon		Suited when
MB_ICONEXCLAMATION MB_ICONWARNING			Warning the user of an action performed on the application
MB_ICONINFORMATION MB_ICONASTERISK			Informing the user of a non-critical situation
MB_ICONQUESTION			Asking a question that expects a Yes or No, or a Yes, No, or Cancel answer
MB_ICONSTOP MB_ICONERROR MB_ICONHAND			A critical situation or error has occurred. This icon is appropriate when informing the user of a termination or deniability of an action

The icons are used in conjunction with the buttons constant. To combine these two flags, use the bitwise OR operator “|”. Here is an example:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
	Application->MessageBox("Do you hear any music now or any sound at all?",
				"CD Player Instructions",
				MB_YESNOCANCEL | MB_ICONQUESTION);
	return 0;
}
//---------------------------------------------------------------------------

This would produce:

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, use one of the following constants:

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. Here is an example:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
    Application->MessageBox("Do you hear any music now or any sound at all?",
	  		    "CD Player Instructions",
	                    MB_YESNOCANCEL | MB_ICONQUESTION | MB_DEFBUTTON2);
    return 0;
}
//---------------------------------------------------------------------------

This would produce:

Since the combination of these buttons is using the OR bitwise operator to construct the Flags argument, it does not make a difference which constant appears first:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
    Application->MessageBox("Do you hear any music now or any sound at all?",
			    "CD Player Instructions",
			    MB_YESNOCANCEL | MB_DEFBUTTON3 | MB_ICONQUESTION);
    return 0;
}
//---------------------------------------------------------------------------

After reading the message displaying on the dialog box, the user would click one of the buttons and the dialog would be closed. Each one of the buttons has a constant number that is assigned and recognized by the compiler. You can use this number to find out what button the user had clicked. This means that the MessageBox() function returns an integer value as in the following table:

Displayed Button(s)	If the user clicked	The return value is
		IDOK
		IDOK
		IDCANCEL
		IDABORT
		IDRETRY
		IDIGNORE
		IDYES
		IDNO
		IDCANCEL
		IDYES
		IDNO
		IDRETRY
		IDCANCEL

Therefore, you can use one of these integers to act depending on the button clicked:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
    if( Application->MessageBox(
			"Do you hear any music now or any sound at all?",
			"CD Player Instructions",
			MB_YESNOCANCEL | MB_ICONQUESTION) == IDNO )
	ShowMessage("We will stop these tests now. "
		    "Let the machine rest!");
    return 0;
}
//---------------------------------------------------------------------------

The MessageDlg() function is the VCL’s enhanced message box and it provides a good alternative to the Win32’s MessageBox() function:

The syntax of the MessageDlg() function is:

int __fastcall MessageDlg(const AnsiString Message,
                          TMsgDlgType IconType,
                          TMsgDlgButtons Buttons,
                          int HelpContext);

The first argument, Message, is the message addressed to the user. It can be a simple static sentence, a paragraph or any combination of strings. The IconType is an icon used to enhance the dialog box. The icon is set using a constant integer as follows:

Value	Icon
mtWarning
mtError
mtInformation
mtConfirmation
mtCustom	None

The Buttons argument is used to specify the type(s) of button(s) to display on the dialog box. The buttons are defined using the TMsgDlgButtons set as follows:

Value Button mbYes mbNo mbOK mbCancel mbAbort mbHelp

Value Button mbRetry mbIgnore mbAll mbNoToAll mbYesToAll

The last argument is used if there is a help file available, in which case you would specify the particular index related to this message box. This message box uses the name of the project as its caption.

Here is an example:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
    MessageDlg(L"All songs on the CD have been copied. Now it will be ejected.",
	       mtInformation, TMsgDlgButtons() << mbOK, 0);
    return 0;
}
//---------------------------------------------------------------------------

This would produce:

Here is another example:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
		   HINSTANCE hPrevInstance, 
		   LPSTR lpCmdLine, 
		   int nCmdShow)
{
    MessageDlg(L"The file C:\\Musics\\tune1.wav"
	       L" that you are trying to upload "
	       L"already exists on the server.\n"
	       L"If you continue, you will replace the recent versions "
	       L"of the files on the server.\n"
	       L"Would you like to upload anyway?",
	       mtConfirmation,
	       TMsgDlgButtons() << mbNoToAll << mbNo
				<< mbYes << mbYesToAll, 0);
    return 0;
}
//---------------------------------------------------------------------------

This would produce:

The MessageDlgPos() function provides extra possibilities to the programmer. It behaves exactly like the MessageDlg() function. To create a message box based on this function, use the syntax:

int __fastcall MessageDlgPos(const AnsiString Msg,
			     TMsgDlgType DlgType,
			     TMsgDlgButtons Buttons,
			     int HelpCtx,
			     int X,
			     int Y);

Besides the same arguments as the MessageDlg() function, the MessageDlgPos() function allows you to specify the coordinates used to display the dialog box. The X argument is an integer value that specifies the distance between the left border of the screen and the left border of the dialog box. The Y argument represents the height from the top border of the screen to the top border of the dialog box. Here is an example:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
    MessageDlgPos(L"The right side of the main form displays "
	          L"a \"Read-Only\" list of currently registered students.\n"
	          L"This only includes students with good records.",
	          mtInformation,
	          TMsgDlgButtons() << mbRetry << mbIgnore,
                  0, 20, 120);
    return 0;
}
//---------------------------------------------------------------------------

This would produce:

The InputBox() function allows you to display a message box that would request a piece of information from the user. The message box is equipped with a text box and two buttons. The edit box accepts a string from the user. The user can type anything but it is up to you to use the content of that edit box as your program needs it. When the user clicks OK, the Input Box returns the content of its text box. If the user clicks Cancel or presses Esc, the content of its edit box is dismissed.

The syntax of the InputBox() function is

AnsiString __fastcall InputBox(const AnsiString Caption,
			       const AnsiString Prompt,
			       const AnsiString Default);

The Caption argument specifies the string that would display on the title bar of the dialog box. The Prompt is a sentence that would display to the user as to what to type in the provided text box. The Default argument is a suggested value you can display in the edit box to guide the user as the type of value expected. If you do not want to specify a default value, you can set its string value to empty. Here is example:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
	InputBox(L"Distance and Measurement",
		 L"Enter the distance in kilometer:", L"");
	return 0;
}
//---------------------------------------------------------------------------

This would produce:

If you specify the Default argument and the user clicks OK without changing the content of the edit box, the compiler would consider the default value as valid. After using the dialog box, the user would click OK, press Enter, click Cancel, or press Esc. If the user clicks OK or presses Enter, the function returns the value that the user would have typed in the edit box. This allows you to write a conditional statement that would consider the new value returned by clicking OK on the InputBox dialog. If the user clicks Cancel or presses Esc, whatever the text box was displaying would be ignored. But the function would still return the default value. If the returned value is intended for mathematical, date, or time calculations, you should convert it appropriately.

Like the InputBox() function, the InputQuery() function is used to display a prompting dialog box to the user. The syntax of this function is:

extern PACKAGE bool __fastcall InputQuery(const AnsiString ACaption,
                                          const AnsiString APrompt,
                                          AnsiString &Value);

This takes three strings. The ACaption parameter is a string that displays on the title bar of the dialog box. The APrompt parameter is the sentence that indicates to the user what to type in the edit box. Like the InputBox() function, the Value parameter provides a default and sample value to the user. Like the InputBox() function, the user can type a new value.

Here is an example of calling the InputQuery() function:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
		   HINSTANCE hPrevInstance,
		   LPSTR lpCmdLine,
		   int nCmdShow)
{
	AnsiString Value;

	InputQuery(L"Exiting Application",
			   L"Are you sure you want to exist (y=Yes/n=No)?",
			   Value);
	return 0;
}
//---------------------------------------------------------------------------

This would produce:

Unlike the InputBox() function that returns a string, the InputQuery() function returns two values. By its declaration, this function returns a Boolean value of true or false. If the user clicks OK or presses Enter after using the dialog box, the function returns true. If the user presses Esc or clicks Cancel, the function returns false.

If the user clicks OK (or presses Enter), like the InputBox() function, whether the user had changed the value of the text box or not, the content of the text box, provided as the Value argument, would be returned. Because the Value argument is passed by reference, the function can return two values. If the user clicks Cancel (or presses Esc) after dealing with the dialog box, the value of the Value argument would be ignored.

You can validate the returned Value by writing a conditional statement that examines whether the user had clicked OK or Cancel. In the following example, when the user clicks a button on the form, the compiler finds out if the user had clicked OK:

//---------------------------------------------------------------------------
WINAPI _tWinMain(HINSTANCE hInstance,
				   HINSTANCE hPrevInstance,
				   LPSTR lpCmdLine,
				   int nCmdShow)
{
    AnsiString Answer;

    if( InputQuery(L"Exiting Application",
		   L"Are you sure you want to exist (Yes/No)?",
		   Answer) == True )
	ShowMessage("Your answer was " + Answer);
    return 0;
}
//---------------------------------------------------------------------------

Here is an example of running the program: