Working With User Forms in Tests

Addressing Forms

Addressing Form Components

Displaying Forms on the Screen

Obtaining Dialog Result

Positioning Form on Screen

Changing Form Size

Sample

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:

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

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:

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

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:

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

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.

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:

# 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:

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

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.

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

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:

# 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.")

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

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:

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

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.

form = UserForms.SampleForm

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

# Obtain the dialog result
mr = form.ModalResult

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.

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.

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 >>"

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

<TestComplete Samples>\Common\User Forms