TCustomForm.ShowModal Method

Shows a form as a modal dialog.

Pascal

function ShowModal: Integer; virtual;

C++

virtual __fastcall int ShowModal();

Description

Use ShowModal to show a form as a modal form. A modal form is one where the application can't continue to run until the form is closed. Thus, ShowModal does not return until the form closes. When the form closes, it returns the value of the ModalResult property.

To close a modal form, set its ModalResult property to a nonzero value.

Note: If the form contains buttons with a ModalResult property set to a value other than mrNone, the form automatically closes when the user clicks one of those buttons and returns the ModalResult value as the return value of ShowModal.

You can check the return value against common return values using the global IsAbortResult, IsAnAllResult, IsNegativeResult, or IsPositiveResult functions.

C++ Examples:

Copy Code

/*
This code brings up the modal dialog from Unit2 when a
button is clicked.  It causes a Beep if the OK button is
clicked. Implement the modal form in Unit2 and then put
Unit2 in the uses clause for this module.
*/
#include "Unit2.h"
void __fastcall TForm1::Button1Click(TObject *Sender)
{
  if (MyDialogBox1->ShowModal() == mrOk)
    MessageBeep(0);
}

Copy Code

/*
The following methods are used for buttons in a form that is
used as a modal dialog box. The methods cause the dialog box
to terminate when the user clicks either the OK or Cancel
button, returning mrOk or mrCancel from ShowModal,
respectively. You could also set the ModalResult value to
mrOk for the OK button and mrCancel for the Cancel button to
accomplish the same thing. When the user clicks either
button, the dialog box closes.
*/
void __fastcall TMyDialogBox1::OKButtonClick(TObject *Sender)
{
  ModalResult = mrOk;
}

void __fastcall TMyDialogBox1::CancelButtonClick(TObject *Sender)
{
  ModalResult = mrCancel;
}

Delphi Examples:

Copy Code

{
This code brings up the modal dialog from Unit2 when a
button is clicked.  It causes a Beep if the OK button is
clicked. Implement the modal form in Unit2 and then put
Unit2 in the uses clause for this module.
}
procedure TForm1.Button1Click(Sender: TObject);
begin
  if MyDialogBox1.ShowModal = mrOK then
    Beep;
end;

Copy Code

{
The following methods are used for buttons in a form that is
used as a modal dialog box. The methods cause the dialog box
to terminate when the user clicks either the OK or Cancel
button, returning mrOk or mrCancel from ShowModal,
respectively. You could also set the ModalResult value to
mrOk for the OK button and mrCancel for the Cancel button to
accomplish the same thing. When the user clicks either
button, the dialog box closes.
}
procedure TMyDialogBox1.CancelButtonClick(Sender: TObject);
begin
  ModalResult := mrCancel;
end;

procedure TMyDialogBox1.OKButtonClick(Sender: TObject);
begin
  ModalResult := mrOK;
end;