Working With User Forms in Tests

Applies to TestComplete 14.40, last modified on April 22, 2021

User forms can be used during the test run to input and output information. You can obtain the data inputted into the form or populate a form with data during the test execution. The following sections describe how to access forms, form components and their properties from scripts.

Note that you can also perform the same actions with user forms from your keyword tests using the Call Object Method, Run Code Snippet or Run Script Routine operation with appropriate program objects, their methods and properties (see below).

Addressing Forms

TestComplete provides a top-level program object called UserForms that lets you access user forms included in the current project. Forms are child objects of the UserForms object, as you can see in the Code Completion window. You can address forms by their names via the UserForms object. Another way to address a form is to use the UserForms.FormByName property with the form name as a parameter. Both notations are equivalent and return the UserForm object that represents the desired form:

JavaScript, JScript

var form;
 
// The following two lines are equivalent
form = UserForms.SampleForm;
form = UserForms.FormByName("SampleForm");

Python

# The following two lines are equivalent
form = UserForms.SampleForm
form = UserForms.FormByName["SampleForm"]

VBScript

' The following two lines are equivalent
Set form = UserForms.SampleForm
Set form = UserForms.FormByName("SampleForm")

DelphiScript

var form : OleVariant;
...
// The following two lines are equivalent
form := UserForms.SampleForm;
form := UserForms.FormByName['SampleForm'];

C++Script, C#Script

var form;
 
// The following two lines are equivalent
form = UserForms["SampleForm"];
form = UserForms["FormByName"]("SampleForm");

Note: The use of the UserForms object name is required.

Addressing Form Components

All components of the form are the child objects of the UserForm object that represents the form. You can specify the component name directly after the form name or as the parameter of the ComponentByName property of the UserForm object:

JavaScript, JScript

var btn;
 
// The following two lines are equivalent
btn = UserForms.SampleForm.buttonOK;
btn = UserForms.SampleForm.ComponentByName("buttonOK");

Python

# The following two lines are equivalent
btn = UserForms.SampleForm.buttonOK
btn = UserForms.SampleForm.ComponentByName["buttonOK"]

VBScript

' The following two lines are equivalent
Set btn = UserForms.SampleForm.buttonOK
Set btn = UserForms.SampleForm.ComponentByName("buttonOK")

DelphiScript

var btn : OleVariant;
...
// The following two lines are equivalent
btn := UserForms.SampleForm.buttonOK;
btn := UserForms.SampleForm.ComponentByName['buttonOK'];

C++Script, C#Script

var btn;
 
// The following two lines are equivalent
btn = UserForms["SampleForm"]["buttonOK"];
btn = UserForms["SampleForm"]["ComponentByName"]("buttonOK");
Note: The use of the UserForms object name and the form name is required.

To enumerate form components, use the Component and ComponentCount properties of the UserForm object. The Component property returns the form component by its index and the ComponentCount property returns the total number of form components.

The UserForm object provides three more properties for accessing and enumerating form components: ChildControlByName, ChildControl and ChildControlCount. They are similar to the corresponding ComponentNNN properties except for the following: The ChildControlNNN properties are used to access controls, that is components (text boxes, buttons, etc.) that are located on the form. Components that do not occupy a place on the form, such as dialogs, cannot be obtained via these properties. Another difference is that the ChildControlNNN property only lets you access those controls that are situated directly on the form and thus are child controls of the form, whereas the ComponentNNN property lets you address all form controls, even if they reside on another component (for instance, on a TcxPanel object), but not on the form itself.

Components that are not situated directly on the form, but are on the container component such as a panel or group box, can be accessed as the form's child objects. If you need to preserve the actual hierarchy of objects, use the ChildControlByName property of the container component:

JavaScript, JScript

var cb = UserForms.SampleForm.ChildControlByName("checkBox");

Python

cb = UserForms.SampleForm.ChildControlByName["checkBox"]

VBScript

Set cb = UserForms.SampleForm.panel.ChildControlByName("checkBox")

DelphiScript

var cb : OleVariant;
...
cb := UserForms.SampleForm.panel.ChildControlByName['checkBox'];

C++Script, C#Script

var cb = UserForms["SampleForm"]["panel"]["ChildControlByName"]("checkBox");

Displaying Forms on the Screen

There is no need to create a user form instance before displaying the form. TestComplete always creates one form instance when the test starts. So, you can display or hide a form, but not create and delete it as you would do in Visual C++, C# or Delphi.

Note: Since only one instance of a form exists, you can display only one instance of a form. You cannot display several instances of the same form.

There are two modes where a form can be displayed: modeless and modal. If a form is displayed as a modeless window, the test execution continues while the form is displayed. You can use modeless forms to display helper information, for example, the current progress of a time-consuming operation towards completion. When the form is displayed as a modal window (dialog), the test execution is paused until the form is closed. Modal forms can be used to input data (such as test options) as well as to output information (for example, test summary).

To display the form as a modeless window, you can either call the Show method or set the form’s Visible property to True:

JavaScript, JScript

// Use any of the following lines to display the modeless form.
UserForms.SampleForm.Visible = true;
UserForms.SampleForm.Show();

Python

# Use any of the following lines to display the modeless form.
UserForms.SampleForm.Visible = True
UserForms.SampleForm.Show()

VBScript

' Use any of the following lines to display the modeless form.
UserForms.SampleForm.Visible = True
UserForms.SampleForm.Show

DelphiScript

// Use any of the following lines to display the modeless form.
UserForms.SampleForm.Visible := true;
UserForms.SampleForm.Show;

C++Script, C#Script

// Use any of the following lines to display the modeless form.
UserForms["SampleForm"]["Visible"] = true;
UserForms["SampleForm"]["Show"]();

Note that after the modeless form appears on screen, the test execution continues. This is because the Show method does not wait until the form is closed and immediately resumes test execution. Thus, a form displayed by the Show method remains visible until it is minimized or closed or until the test execution ends.

When you need to close (hide) the modeless form, call the Hide method or set the Visible property to False:

JavaScript, JScript

// Use any of the following lines to hide the modeless form.
UserForms.SampleForm.Visible = false;
UserForms.SampleForm.Hide();

Python

# Use any of the following lines to hide the modeless form.
UserForms.SampleForm.Visible = False
UserForms.SampleForm.Hide()

VBScript

' Use any of the following lines to display the modeless form.
UserForms.SampleForm.Visible = False
UserForms.SampleForm.Hide

DelphiScript

// Use any of the following lines to hide the modeless form.
UserForms.SampleForm.Visible := false;
UserForms.SampleForm.Hide;

C++Script, C#Script

// Use any of the following lines to hide the modeless form.
UserForms["SampleForm"]["Visible"] = false;
UserForms["SampleForm"]["Hide"]();

Note: The form’s property values and properties of form’s components are stored in the corresponding program object during the test run. The next time the form is displayed, all of its components will have the same state and hold the same data as before the form was closed.

To display the form as a modal dialog, use the UserForm.ShowModal method. This method displays the form on screen, waits until the form is closed and returns the result indicating which button the user pressed to close the form (for example, OK or Cancel). Note that in order for the button to close the form, its ModalResult property should be set to anything other than mrNone.

JavaScript, JScript

// Display the form as a modal dialog
UserForms.SampleForm.ShowModal();

Python

# Display the form as a modal dialog
UserForms.SampleForm.ShowModal()

VBScript

' Display the form as a modal dialog
UserForms.SampleForm.ShowModal

DelphiScript

// Display the form as a modal dialog
UserForms.SampleForm.ShowModal;

C++Script, C#Script

// Display the form as a modal dialog
UserForms["SampleForm"]["ShowModal"]();

Obtaining Dialog Result

When you display the form as a modal dialog using the ShowModal method, this method returns the form’s dialog result. The dialog result means the final result of user interaction with the form. It indicates which button the user pressed to close the form, for example, OK, Cancel, Yes, No and so on. You can use the dialog result to decide what actions should be performed after the form is closed. For instance, you can start a test if the user pressed OK and skip the test if the user pressed Cancel, like in the following example:

JavaScript

// Display the form and determine which button was pressed
var mr = UserForms.SampleForm.ShowModal();

// Run tests if the tester pressed OK button
if (equal(mr, mrOk))
  RunTests();
else
  Log.Warning ("The test was cancelled.");

JScript

// Display the form and determine which button was pressed
var mr = UserForms.SampleForm.ShowModal();

// Run tests if the tester pressed OK button
if (mr == mrOk)
  RunTests();
else
  Log.Warning ("The test was cancelled.");

Python

# Display the form and determine which button was pressed
mr = UserForms.SampleForm.ShowModal()

# Run tests if the tester pressed OK button
if mr == mrOk:
  RunTests()
else:
  Log.Warning ("The test was cancelled.")

VBScript

' Display the form and determine which button was pressed
mr = UserForms.SampleForm.ShowModal

' Run tests if the tester pressed OK button
If mr = mrOk Then
  RunTests
Else
  Log.Warning "The test was cancelled."
End If

DelphiScript

var mr : integer;
begin
  // Display the form and determine which button was pressed
  mr := UserForms.SampleForm.ShowModal;

  // Run tests if the tester pressed OK button
  if mr = mrOk then
    RunTests
  else
    Log.Warning ('The test was cancelled.');
end;

C++Script, C#Script

// Display the form and determine which button was pressed
var mr = UserForms["SampleForm"]["ShowModal"]();

// Run tests if the tester pressed OK button
if (mr == mrOk)
  RunTests();
else
  Log["Warning"] ("The test was cancelled.");

To obtain the form’s dialog result from scripts or keyword tests, you can also use the UserForm.ModalResult property:

JavaScript, JScript

var form, mr;

form = UserForms.SampleForm;

// Display the form as a dialog
form.ShowModal();

// Obtain the dialog result
mr = form.ModalResult;

Python

form = UserForms.SampleForm

# Display the form as a dialog
form.ShowModal()

# Obtain the dialog result
mr = form.ModalResult

VBScript

Set form = UserForms.SampleForm

' Display the form as a dialog
form.ShowModal

' Obtain the dialog result
mr = form.ModalResult

DelphiScript

var form, mr : OleVariant;
begin
  form := UserForms.SampleForm;

  // Display the form as a dialog
  form.ShowModal;

  // Obtain the dialog result
  mr := form.ModalResult;

end;

C++Script, C#Script

var form, mr;

form = UserForms["SampleForm"];

// Display the form as a dialog
form["ShowModal"]();

// Obtain the dialog result
mr = form["ModalResult"];

The ModalResult property also lets you set the form’s result from scripts and keyword tests. Note that when you set this property to anything other than mrNone, this causes the form to close:

JavaScript, JScript

UserForms.SampleForm.ModalResult = mrOK;

Python

form = UserForms.SampleForm
form.Left = 0
form.Top  = 0
form.ShowModal()

VBScript

UserForms.SampleForm.ModalResult = mrOK

DelphiScript

UserForms.SampleForm.ModalResult := mrOK;

C++Script, C#Script

UserForms["SampleForm"]["ModalResult"] = mrOK;

Positioning Form on Screen

When you display the form for the first time during the test run, TestComplete sets the form position automatically so that it appears in the center of the screen. The next time the form is displayed, it appears in the same place where it was situated before it was closed (that is, where the user has moved the form).

If you need to display the form in a custom screen position, use the Left and Top properties of the UserForm object. These properties let you determine and set the form’s position on screen as the horizontal and vertical coordinates of the form’s top-left corner.

In the following example, Left and Top are set to 0 in order for the form to appear in the top left corner of screen.

JavaScript, JScript

var form = UserForms.SampleForm;
form.Left = 0;
form.Top  = 0;
form.ShowModal();

Python

form = UserForms.SampleForm

# Display the form as a dialog
form.ShowModal()

# Obtain the dialog result
mr = form.ModalResult

VBScript

Set form = UserForms.SampleForm
form.Left = 0
form.Top  = 0
form.ShowModal

DelphiScript

var form: OleVariant;
begin
  form := UserForms.SampleForm;
  form.Left := 0;
  form.Top  := 0;
  form.ShowModal;
end;

C++Script, C#Script

var form = UserForms["SampleForm"];
form["Left"] = 0;
form["Top"]  = 0;
form["ShowModal"]();

Changing Form Size

When you design the form in the User Forms editor, you adjust the form size as you need. However, you may also need to change the form size dynamically, during the test execution. For example, your form can display a set of common options and a “More” button that when pressed it increases the form height and displays additional options. In this case, you have to change the form size from the script code or from the keyword test operations that use appropriate program objects.

To change the form size, use the Width and Height properties. They let you obtain the form height and width as well as change them.

Note: If the AutoSize property of the user form is set to True and the form is not visible on screen, the form’s Height property returns 0, no matter what the actual height is. To obtain the form’s height in such cases, call the ShowModal method right before calling the Height property.

The following example illustrates the described case. It requires a form named SampleForm that contains a TcxButton component named btnMoreLess and another component named extra. Pressing the btnMoreLess button expands or shrinks the form, depending on the previous form state specified by the maximized variable. The extra component should be situated on the part of the form that becomes visible when the form is maximized. The SampleForm_btnMoreLess_OnClick routine assumes to be bound to the btnMoreLess’s OnClick event. minWidth and maxWidth specify minimal and maximal height of the form respectively. You may need to specify different values for minHeight and maxHeight according to the required height of your form.

JavaScript, JScript

var maximized = false, // Indicates whether the form displays additional options
    maxHeight = 250,   // The maximal height of the form
    minHeight = 150,   // The minimal height of the form
    dy = maxHeight - minHeight; // The height of the additional part of the form

function Main()
{
  var form = UserForms.SampleForm;
  // Set the initial form height
  form.Height = minHeight;
  // Display the form
  form.ShowModal();
}

function SampleForm_btnMoreLess_OnClick(Sender)
{
  var form = UserForms.SampleForm;
  
  // Switch the state flag
  maximized = !maximized;
  
  if (maximized)
  {
    // Enable the extra component so that it can be selected
    form.extra.Enabled = true;

    // Increase the form height
    form.Height += dy;

    // Move the button to the bottom of the form
    Sender.Top += dy;

    // Change the button caption
    Sender.Caption = "&Less <<";
  }
  else
  {
    // Disable the extra component so that it cannot be selected
    form.extra.Enabled = false;

    // Reduce the form height
    form.Height -= dy;

    // Move the button to the bottom of the form
    Sender.Top -= dy;
    
    // Change the button caption
    Sender.Caption = "&More >>";
  }
}

Python

maximized = False # Indicates whether the form displays additional options
maxHeight = 250   # The maximal height of the form 
minHeight = 150   # The minimal height of the form
dy = maxHeight - minHeight # The height of the additional part of the form 

def Main():
  form = UserForms.SampleForm
  # Set the initial form height form.Height = minHeight
  # Display the form
  form.ShowModal()

def SampleForm_btnMoreLess_OnClick(Sender): 
  form = UserForms.SampleForm
  
  # Switch the state flag
  maximized = not maximized
  
  if maximized:
    # Enable the extra component so that it can be selected
    form.extra.Enabled = True

    # Increase the form height
    form.Height += dy

    # Move the button to the bottom of the form 
    Sender.Top += dy

    # Change the button caption 
    Sender.Caption = "&Less <<"
  else:
    # Disable the extra component so that it cannot be selected
    form.extra.Enabled = False

    # Reduce the form height
    form.Height -= dy

    # Move the button to the bottom of the form
    Sender.Top -= dy
    
    # Change the button caption
    Sender.Caption = "&More >>"

VBScript

maximized = False ' Indicates whether the form displays additional options
maxHeight = 250   ' The maximal height of the form
minHeight = 150   ' The minimal height of the form
 dy = maxHeight - minHeight ' The height of the additional part of the form

Sub Main
  Set form = UserForms.SampleForm
  ' Set the initial form height
  form.Height = minHeight
  ' Display the form
  form.ShowModal
End Sub

Sub SampleForm_btnMoreLess_OnClick(Sender)
  Set form = UserForms.SampleForm

  ' Switch the flag state
  maximized = Not maximized

  If maximized Then
    ' Enable the extra component so that it can be selected
    form.extra.Enabled = True

    ' Increase the form height
    form.Height = form.Height + dy

    ' Move the button to the bottom of the form
    Sender.Top = Sender.Top + dy

    ' Change the button caption
    Sender.Caption = "&Less <<"
  Else
    ' Disable the extra component so that it cannot be selected
    form.extra.Enabled = False

    ' Reduce the form height
    form.Height = form.Height - dy

    ' Move the button to the bottom of the form
    Sender.Top = Sender.Top - dy

    ' Change the button caption
    Sender.Caption = "&More >>"
  End If
End Sub

DelphiScript

const maximized = false; // Indicates whether the form displays additional options
const maxHeight = 250;   // The maximal height of the form
const minHeight = 150;   // The minimal height of the form
const dy = maxHeight - minHeight; // The height of the additional part of the form

procedure Main;
var
  form : OleVariant;
begin
  form := UserForms.SampleForm;
  form.Height := minHeight;
  form.ShowModal;
end;

procedure SampleForm_btnMoreLess_OnClick(Sender);
var
  form : OleVariant;
begin
  form := UserForms.SampleForm;
  
  // Switch the state flag
  maximized := not maximized;
  
  if maximized then
  begin
    // Enable the extra component so that it can be selected
    form.extra.Enabled := true;

    // Increase the form height
    form.Height := form.Height + dy;

    // Move the button to the bottom of the form
    Sender.Top := Sender.Top + dy;

    // Change the button caption
    Sender.Caption := '&Less <<';
  end
  else begin
    // Disable the extra component so that it cannot be selected
    form.extra.Enabled := false;

    // Reduce the form height
    form.Height := form.Height - dy;

    // Move the button to the bottom of the form
    Sender.Top := Sender.Top - dy;
    
    // Change the button caption
    Sender.Caption := '&More >>';
  end;
end;

C++Script, C#Script

var maximized = false, // Indicates whether the form displays additional options
    maxHeight = 250,   // The maximal height of the form
    minHeight = 150,   // The minimal height of the form
    dy = maxHeight - minHeight; // The height of the additional part of the form

function Main()
{
  var form = UserForms["SampleForm"];
  // Set the initial form height
  form.Height = minHeight;
  // Display the form
  form["ShowModal"]();
}

function SampleForm_btnMoreLess_OnClick(Sender)
{
  var form = UserForms["SampleForm"];
  
  // Switch the state flag
  maximized = !maximized;
  
  if (maximized)
  {
    // Enable the extra component so that it can be selected
    form["extra"]["Enabled"] = true;

    // Increase the form height
    form["Height"] += dy;

    // Move the button to the bottom of the form
    Sender["Top"] += dy;

    // Change the button caption
    Sender["Caption"] = "&Less <<";
  }
  else
  {
    // Disable the extra component so that it cannot be selected
    form["extra"]["Enabled"] = false;

    // Reduce the form height
    form["Height"] -= dy;

    // Move the button to the bottom of the form
    Sender["Top"] -= dy;
    
    // Change the button caption
    Sender["Caption"] = "&More >>";
  }
}

Sample

TestComplete includes a sample project that demonstrates how you can work with user forms:

<TestComplete Samples>\Common\User Forms

Note: If you do not have the sample, download the TestComplete Samples installation package from the https://support.smartbear.com/downloads/testcomplete/samples/ page of our website and run it.

See Also

User Forms
Handling Events in User Forms
UserForms Object
UserForm Object

Highlight search results