TApplication.MessageBox Method

Displays a specified message to the user.

Pascal

function MessageBox(const Text: PChar; const Caption: PChar; Flags: Longint = MB_OK): Integer;

C++

__fastcall int MessageBox(const const char * Text, const const char * Caption, Longint Flags = MB_OK);

Description

Use MessageBox to display a generic dialog box a message and one or more buttons. Caption is the caption of the dialog box and is optional.

MessageBox is an encapsulation of the Windows API MessageBox function. TApplication's encapsulation of MessageBox automatically supplies the missing window handle parameter needed for the Windows API function.

The value of the Text parameter is the message, which can be longer than 255 characters if necessary. Long messages are automatically wrapped in the message box.

The value of the Caption parameter is the caption that appears in the title bar of the dialog box. Captions can be longer than 255 characters, but don't wrap. A long caption results in a wide message box.

The Flags parameter specifies what buttons appear on the message box and the behavior (possible return values). The following table lists the possible values. These values can be combined to obtain the desired effect.

Value	Meaning
MB_ABORTRETRYIGNORE	The message box contains three push buttons: Abort, Retry, and Ignore.
MB_OK	The message box contains one push button: OK. This is the default.
MB_OKCANCEL	The message box contains two push buttons: OK and Cancel.
MB_RETRYCANCEL	The message box contains two push buttons: Retry and Cancel.
MB_YESNO	The message box contains two push buttons: Yes and No.
MB_YESNOCANCEL	The message box contains three push buttons: Yes, No, and Cancel.

MessageBox returns 0 if there isn't enough memory to create the message box. Otherwise it returns one of the following values:

ValueNumeric valueMeaning

Value	Numeric value	Meaning
IDOK	1	The user chose the OK button.
IDCANCEL	2	The user chose the Cancel button.
IDABORT	3	The user chose the Abort button.
IDRETRY	4	The user chose the Retry button.
IDIGNORE	5	The user chose the Ignore button.
IDYES	6	The user chose the Yes button.
IDNO	7	The user chose the No button.

C++ Examples:

Copy Code

/*
The following code causes "stay on top" forms to allow a 
MessageBox to appear on top. After the message box is 
closed, the topmost forms are restored so that they continue
to float to the top.
*/
void __fastcall TForm1::Button1Click(TObject *Sender)
{
Application->NormalizeTopMosts();
#ifdef _DELPHI_STRING_UNICODE
Application->MessageBox(L"This should be on top.", L"Look", MB_OKCANCEL);
#else
Application->MessageBox("This should be on top.", "Look", MB_OKCANCEL);
#endif
Application->RestoreTopMosts();
}

Delphi Examples:

Copy Code

{
The following code causes "stay on top" forms to allow a 
MessageBox to appear on top. After the message box is 
closed, the topmost forms are restored so that they continue
to float to the top.
}
procedure TForm1.Button1Click(Sender: TObject);
begin
  with Application do
  begin
    NormalizeTopMosts;
    MessageBox('This should be on top.', 'Look', MB_OK);    // [smbOK]
    RestoreTopMosts;
  end;
end;