13/02/2011 C++ Builder Documentation - ShowM…

The MessageBox() Function

Ads by Google
The MessageBox() function is derived from Win32. Its syntax is:
Compare Excel
int __fastcall MessageBox(const char * Message, const char * Caption, int Flags);
tables

Powerful and handy

add-on for Excel
2000-2007 files
comparison.

www.office-excel.com

The MessageBox() function takes three arguments. The first argument, Message, is a null-
terminated string representing the message that the user would read. The Text 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. Set the other two arguments as NULL. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
Application->MessageBox("This operation can only be "
"performed by an administrator.",
NULL, NULL);
}
//---------------------------------------------------------------------------

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. Therefore, to create a less
boring message box, provide the Caption argument. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
Application->MessageBox("Make sure the music is playing.",
"CD PLayer Instructions", NULL);
}
//---------------------------------------------------------------------------

The third argument specifies the flags that would display on the dialog box: one or more
buttons and an optional picture. 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:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
Application->MessageBox("Make sure the music is playing.",
"CD PLayer Instructions", MB_OK);
}
//---------------------------------------------------------------------------

To display more than one button, use a constant integer that represents a group of the
available buttons. Here are the constants and their buttons:

Constant Integer Button(s)

MB_OK
www.ww.functionx.com/…/msgbox.htm 1/3
13/02/2011 C++ Builder Documentation - ShowM…
MB_OK

MB_OKCANCEL

MB_ABORTRETRYIGNORE

MB_YESNOCANCEL

MB_YESNO
MB_RETRYCANCEL

MB_CANCELTRYCONTINUE

MB_HELP

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

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
Application->MessageBox("Do you hear any music now or any sound at all?",
"CD Player Instructions", MB_YESNO);
}
//---------------------------------------------------------------------------

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

The enhance your dialog and accentuate your 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 tactful and make sure that the appearance is in accordance with the message.
The values and icons are:

Value Icon Suited When

Warning the user of an
MB_ICONEXCLAMATION
action performed on the
MB_ICONWARNING
application.
MB_ICONINFORMATION Informing the user of a
MB_ICONASTERISK non-critical situation.
Asking a question that
MB_ICONQUESTION expects a Yes, No, or
Cancel answers.
A critical situation or
error has occurred. This
MB_ICONSTOP icon is appropriate when
MB_ICONERROR
MB_ICONHAND 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:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
Application->MessageBox("Do you hear any music now or any sound at all?",
"CD Player Instructions", MB_YESNOCANCEL | MB_ICONQUESTION);
}
//---------------------------------------------------------------------------

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:

If the message box has more than

Constant Value one button, the default button
would be
MB_DEFBUTTON1 The first button
www.ww.functionx.com/…/msgbox.htm 2/3
13/02/2011 C++ Builder Documentation - ShowM…
MB_DEFBUTTON1 The first button
MB_DEFBUTTON2 The second button
MB_DEFBUTTON3 The third button
MB_DEFBUTTON4 The fourth button

To specify the default button, use the bitwise OR operator to combine the constant integer
of the desired default button with the buttons constant and the icon. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
Application->MessageBox("Do you hear any music now or any sound at all?",
"CD Player Instructions",
MB_YESNOCANCEL | MB_ICONQUESTION | MB_DEFBUTTON2);
}
//---------------------------------------------------------------------------

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:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
Application->MessageBox("Do you hear any music now or any sound at all?",
"CD Player Instructions",
MB_YESNOCANCEL | MB_DEFBUTTON3 | MB_ICONQUESTION);
}
//---------------------------------------------------------------------------

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 integer
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 the MessageBox() function returns an
integer value as in the following table:

The MessageBox()
If the user clicks
returns
IDOK OK
IDCANCEL Cancel or presses Esc
IDABORT Abort
IDRETRY Retry
IDIGNORE Ignore
IDNO No
IDYES Yes
IDCONTINUE Continue
IDTRYAGAIN Try Again

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

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
if (Application->MessageBox(
"Do you hear any music now or any sound at all?",
"CD Player Instructions",
MB_YESNOCANCEL | MB_ICONQUESTION) == IDNO)
Panel1->Caption = "We will stop these tests now. Let the machine rest!";
}
//---------------------------------------------------------------------------

Copyright © FunctionX 2001-2007

www.ww.functionx.com/…/msgbox.htm 3/3