Script extensions can use custom forms to ask the user for some data or to display information to the user. These forms are the same that are provided by the TestComplete User Forms project item and that you can use in your test projects.
You create and design custom forms in TestComplete environment, and then export the form file to the format adopted by script extensions.
The following sections explain how to create forms and call them from the script extension code:
Creating and Designing Forms| Note: | The script extension’s ability to use forms does not depend on the presence of the User Forms item in the user’s project. |
Creating and Designing Forms
To be able to create and edit forms, you must have a project opened in TestComplete. We recommend that you create a special project where you will design forms to be used in your script extension (see the Best Practices section of the Creating Script Extensions - Basic Concepts topic).
To create a new form, do the following:
- Add the User Forms item to your project.
- Right-click the User Forms node in the Project Explorer and select Add | New Item from the context menu. In the ensuing dialog, enter the form name. This is the same name that will be used to refer to this form from the script code.
- Click OK to close the dialog and create a new form.
After you have created a new form, it gets opened in the form editor, where you can design the form as your needs dictate. You can add controls to the form, arrange them, set up their properties, and so on. For more information on some common design tasks, see the User Forms Editor topic.
We would like to pay your attention to the TObjectPicker control. It is an analog of the TestComplete target glyph (
), which allows you to pick an object from screen. You can use this control in your form to enable the users visually select the needed object, like they can do it in the Checkpoint wizard.
Creating Event Handlers for Forms and Controls
Quite often, you may need the form controls to react upon certain actions. This can be done by handling the corresponding events that occur in the form or individual controls. For example, when the form is about to be closed, you can check whether the user has inputted all the needed data and, if not, cancel form closing.
To create event handlers for a form and its controls, open that form in the TestComplete User Forms editor and use the Events page of the Properties panel. For detailed instructions, see Handling Events in User Forms. Two notes:
-
The event handlers must reside in the script extension’s script unit that calls the form.
-
If the form is called from multiple script files of a script extension, the event handlers must be duplicated in each of these files.
The following sample illustrates how you can handle the OnObjectPicked event of a TObjectPicker control. It requires a form named Form1 with a TObjectPicker control named ObjectPicker1 and a TcxTextEdit control named cxTextEdit1. Whenever a user selects an object from screen using the object picker, the code displays the object name in the text box.
JScript
function Form1_ObjectPicker1_OnObjectPicked(Sender)
{
// Get the full name of the picked object
var objName = UserForms.Form1.ObjectPicker1.PickedObjectName;
// Displays the object name in a text box
UserForms.Form1.cxTextEdit1.Text = objName;
}
VBScript
Sub Form1_ObjectPicker1_OnObjectPicked(Sender)
Dim objName
' Get the full name of the picked object
objName = UserForms.Form1.ObjectPicker1.PickedObjectName
' Displays the object name in a text box
UserForms.Form1.cxTextEdit1.Text = objName
End Sub
Exporting Forms
The format of form files that can be used in script extensions (.aqfrm) is different from that used in TestComplete projects (.tcUsrFrm). Thus, once a form is ready you must export the form file to the format adopted by script extensions. To do this:
- Double-click the form node in the Project Explorer to open the form in the editor.
- Right-click somewhere within the editor and choose Export to File from the context menu.
- Browse for the folder that contains your script extension files and enter the form name in the File name box.
- Click Save to finish.
Importing Forms
To import a user form from the .aqfrm file to the TestComplete project, do the following:
- Right-click the User Forms node in the Project Explorer and choose Add | New Item from the context menu.
- In the ensuing dialog, enter the form name and click OK to close the dialog and create a new form. TestComplete will display the new form in the User Forms editor.
- Right-click somewhere within the editor and choose Import from File from the context menu. TestComplete will ask you whether you want to discard the current form design. Click Yes.
- Using the standard Open File dialog, browse for the .aqfrm file that represents the imported form.
Using Forms in Script Extension Code
You can work with user forms from the script extension code in the same way as you do this in usual TestComplete scripts -- via the UserForms program object. To access a form, use the UserForms.FormName syntax, where FormName is the name that you have specified when exporting the form. After you have obtained a form reference, you can perform the desired actions. For example, you can display the form to the user, check its dialog result and obtain data inputted or selected in the form by the user.
To display a form from the script code, use the UserForms.FormName.ShowModal method. This method returns the form’s dialog result -- the result of the user’s interaction with the form. This value indicates which button the user pressed to close the form -- OK, Cancel, and so on. You can check this result to see whether to proceed with the checkpoint creation or cancel the action. For example:
JScript
// Display the form and check the dialog result.
// If the user clicked any button but OK, cancel the action.
if (UserForms.MyForm.ShowModal() != mrOK) return;
// Proceed
...
VBScript
' Display the form and check the dialog result.
' If the user clicked any button but OK, cancel the action.
If UserForms.MyForm.ShowModal <> mrOK Then Exit Sub
' Proceed
...
After the form has been closed, you can obtain values that were inputted or selected by the user in the form. To do this, simply address the desired form controls using the UserForms.FormName.ControlName syntax and check the needed properties (Text, Checked, ItemIndex and so on).
The following example demonstrates how you can display forms from the script code and obtain data from them. It requires a form named Form1 with a TObjectPicker control named ObjectPicker1. The sample displays the form allowing the user to pick an object from screen. After the user closes the form, the code highlights the selected object on screen.
JScript
function SelectObject()
{
// Display the form and wait until the user closes it
UserForms.Form1.ShowModal();
// Get the full name of the picked object
var objName = UserForms.Form1.ObjectPicker1.PickedObjectName;
if (objName != "")
{
// Obtain a reference to the object by its full name
var obj = eval(objName);
// Highlight the object on screen
Sys.HighlightObject(obj);
}
}
VBScript
Sub SelectObject
Dim objName, obj
' Display the form and wait until the user closes it
UserForms.Form1.ShowModal
' Get the full name of the picked object
objName = UserForms.Form1.ObjectPicker1.PickedObjectName
If objName <> "" Then
' Obtain a reference to the object by its full name
Set obj = Eval(objName)
' Highlight the object on screen
Sys.HighlightObject obj
End If
End Sub
To learn more about managing forms from the script code, obtaining values inputted or selected by the user and performing other related actions, see Working With User Forms in Tests.
See Also
Script Extensions
Creating Script Extensions
User Forms
User Forms Editor
Handling Events in User Forms
Working With User Forms in Tests