UserForm.ShowModal Method

Applies to TestComplete 14.20, last modified on September 11, 2019

Description

Use the ShowModal method to display the form as a modal dialog. When the form is displayed using the ShowModal method, the script execution is paused until the form is closed, so the ShowModal method does not return until the form closes.

The ShowModal method sets the form’s ModalResult property to mrNone, displays the form on the screen and waits until the form closes. The form is closed in one of the following cases:

  • The form’s ModalResult property is set to anything other than mrNone. When the user presses the form button whose ModalResult property differs from mrNone, the same value is automatically assigned to the form’s ModalResult property. The ModalResult property can also be modified from the script code.
  • The Hide method is called.

After the form is closed, the ShowModal method returns the value of the ModalResult property. You can use this value to determine what actions should be performed next. For example, you can skip the code following the ShowModal method call in case the method returns mrCancel. See Working With User Forms in Tests for more information.

Declaration

UserForm.ShowModal()

Result Integer

Applies To

The method is applied to the following object:

Result Value

The ShowModal method returns the value of the ModalResult property. It can be one of the following constants defined in the BuiltIn object:

Constant Value Description
mrNone 0 None.
mrOk 1 The dialog result is OK.
mrCancel 2 The dialog result is Cancel.
mrAbort 3 The dialog result is Abort.
mrRetry 4 The dialog result is Retry.
mrIgnore 5 The dialog result is Ignore.
mrYes 6 The dialog result is Yes.
mrNo 7 The dialog result is No.
mrAll 8 The dialog result is All.
mrNoToAll 9 The dialog result is No To All.
mrYesToAll 10 The dialog result is Yes To All.

Remarks

To display the form in a modeless mode, use the Show method.

When the form is displayed for the first time, by default it appears in the center of the screen. If you need to display the form in the custom screen position, specify the desired X and Y coordinates in the Left and Top properties respectively, before calling the ShowModal method.

Example

The following example checks which form button was pressed to close the form. It assumes that the current project contains the form named TestForm with OK and Cancel buttons. The buttons' ModalResult property should be mrOK and mrCancel respectively.

JavaScript, JScript

function Test()
{
  var mr = UserForms.TestForm.ShowModal();

  // Check which form button was pressed
  if (mr == mrOk)
    ShowMessage ("The OK button was pressed.");
  else
    ShowMessage ("The Cancel button was pressed.");
}

Python

def Test():
  mr = UserForms.TestForm.ShowModal()
  # Check which form button was pressed
  if mr == mrOk:
    ShowMessage ("The OK button was pressed.")
  else:
    ShowMessage ("The Cancel button was pressed.")

VBScript

Sub Test
  mr = UserForms.TestForm.ShowModal

  ' Check which form button was pressed
  If mr = mrOk Then
    ShowMessage ("The OK button was pressed.")
  Else
    ShowMessage ("The Cancel button was pressed.")
  End If
End Sub

DelphiScript

procedure Test;
var mr: integer;
begin
  mr := UserForms.TestForm.ShowModal;

  // Check which form button was pressed
  if mr = mrOk then
    ShowMessage ('The OK button was pressed.')
  else
    ShowMessage ('The Cancel button was pressed.');
end;

C++Script, C#Script

function Test()
{
  var mr = UserForms["TestForm"]["ShowModal"]();

  // Check which form button was pressed
  if (mr == mrOk)
    ShowMessage ("The OK button was pressed.");
  else
    ShowMessage ("The Cancel button was pressed.");
}

See Also

Working With User Forms in Tests
UserForm.Hide Method
UserForm.ModalResult Property
UserForm.Show Method
UserForm.OnShow Event
TcxButton.ModalResult

Highlight search results