8. Creating an Edit Form

Applies to TestComplete 14.93, last modified on September 27, 2021

Script extensions can display custom forms to ask the user to input some data or to display this data. Our sample keyword test operation will use a form to provide users with access to its fields. Earlier, we created an empty form named laEditForm in our TestComplete project. On this step, we will design this form.

1. Add Controls to the Form

  • In the Project Explorer panel, double-click the UserForms | laEditForm item. This will open the form in the form designer.

  • In the Properties panel, specify the Log Attributes value of the Caption property. This string is the form title.

  • In the Components panel and activate the Helpers category. Click the TcxLabel control in the panel, and then click somewhere within the form to add the control to the form.

  • In the Properties panel, set the following property values:

    Property Value
    Name lblMessage
    Caption Message
    Style.Font.Style.fsBold True
    Properties.LineOptions.Visible True
  • Add the following controls to the form and configure their properties as described in the table:

    Control Purpose Position Property Value
    TcxComboBox Holds the list of options for the font color of test log entries. Below the lblMessage text label. Name cbFontColor
    Properties.Sorted True
    Properties.DropDownListStyle lsEditFixedList
    TcxLabel A label for the cbFontColor combo box. Below the lblMessage text label, on the left of the cbFontColor combo box. Name lblFontColor
    Caption &Font
    (the ampersand indicates the hot key)
    FocusControl cbFontColor
    TcxComboBox Holds the list of options for the background color of test log entries. Below the cbFontColor combo box. Name cbBackColor
    Properties.DropDownListStyle lsEditFixedList
    Properties.Sorted True
    TcxLabel A label for the cbBackColor combo box. Below the lblFontColor text label, on the left of the cbBackColor combo box. Name lblBackColor
    Caption &Background
    FocusControl cbBackColor
    TcxCheckBox A check box that toggles the bold font style. Below the lblBackColor text label. Name chkBold
    Caption &Bold
    Style.Font.Style.fsBold True
    TcxCheckBox A check box that toggles the italic font style. On the right of the chkBold check box. Name chkItalic
    Caption &Italic
    Style.Font.Style.fsItalic True
    TcxCheckBox A check box that toggles the underline font style. On the right of the chkItalic check box. Name chkUnderline
    Caption &Underline
    Style.Font.Style.fsUnderline True
    TcxCheckBox A check box that toggles the strikeout font style. On the right of the chkUnderline check box. Name chkStrikeout
    Caption &Strikeout
    Style.Font.Style.fsStrikeOut True
    TcxLabel A sample text with the specified font and color settings applied. Below the chkBold, chkItalic, chkUnderline and chkStrikeout check boxes. Name lblSample
    Caption Sample text
    AutoSize False
    Style.Color clWhite
    Style.Font.Color clBlack
    TcxLabel A label for settings of extended log messages. Below the lblSampe label. Name lblRemarks
    Caption Remarks
    Style.Font.Style.fsBold True
    Properties.LineOptions.Visible True
    TcxComboBox Holds the list of formats for the extended text of log messages. Below the lblRemarks text label. Name cbRemarksFormats
    Properties.DropDownListStyle lsEditFixedList
    Properties.Items HTML
    Plain text
    TcxLabel A label for the cbRemarksFormats combo box. Below the lblRemarks text label, on the left of the cbRemarksFormats combo box. Name lblFormat
    Caption &Format
    FocusControl cbRemarksFormats
    TcxButton The OK button. Below the bvl line. Name btnOK
    Caption OK
    Default True
    ModalResult mrOK
    TcxButton The Cancel button. On the right of the btnOK button. Name btnCancel
    Caption Cancel
    Cancel True
    ModalResult mrCancel
    TcxButton The Help button. On the right of the btnCancel button. Name Help
    Caption &Help
  • Arrange and resize the controls on the form so that it looks like the following image:

    Log Attributes Form

2. Create Event Handlers

Now we can create event handlers for the form and its controls. The handlers will enable the form and controls to perform certain actions in response to user actions.

Let’s start with the handler for the form’s OnShow event. This event occurs when the form is displayed on screen. The event handler will set the input focus to the Font combo box.

  • Click somewhere in the form.

  • In the Properties panel, click Events to open the list of the form events.

  • To create an event handler, click the ellipsis button of the OnShow event. This will invoke the New Event Handler dialog.

  • In the dialog:

    • Select laCode in the Test Containers list.

    • Specify laEditForm_OnShow in the Test name box.

    • Click OK.

    Creating an Event Handler

    TestComplete will create the specified routine in the laCode unit and will open the unit in the Code Editor.

  • Enter the following code for the laCode_OnClick function.

    JScript

    [laCode.js]

    // Sets the form's focused element
    function laEditForm_OnShow(Sender)
    {
      UserForms.laEditForm.cbFontColor.SetFocus();
    }

Now let’s handle the OnEditValueChanged event of the combo box controls. This event occurs when a new item has been selected in the combo box. The event handlers will apply the colors selected in the combo boxes to the sample text.

  • Switch to the form editor and select the cbFontColor control in the form.

  • Activate the Events page of the Properties panel and click the ellipsis button of the OnEditValueChanged event.

  • In the New Event Handler dialog, select laCode in the Test Containers list, specify laEditForm_cbFontColor_OnEditValueChanged in the Test name box, and click OK.

    TestComplete will create the specified routine and display it in the Code Editor.

  • Enter the following code for the routine:

    JScript

    [laCode.js]

    // Applies the selected font color to the sample area
    function laEditForm_cbFontColor_OnEditValueChanged(Sender)
    {
      var frm = UserForms.laEditForm;
      frm.lblSample.Style.Font.Color = GetColorByName(frm.cbFontColor.Text);
    }

    This routine will be called when the user selects a color from the cbFontColor combo box. The routine obtains the RGB value of the color and applies this color to the text of the lblSample label (this label serves as a preview of the current style settings). The GetColorByName routine used in this event handler was described in one of the previous steps.

  • In a similar way, create a handler for the OnEditValueChanged event of the cbBackColor combo box. Name the routine laEditForm_cbBackColor_OnEditValueChanged and add it to the laCode unit. The routine code is below; it is very similar to the laEditForm_cbFontColor_OnEditValueChanged routine.

    JScript

    [laCode.js]

    // Applies the selected background color to the sample area
    function laEditForm_cbBackColor_OnEditValueChanged(Sender)
    {
      var frm = UserForms.laEditForm;
      frm.lblSample.Style.Color = GetColorByName(frm.cbBackColor.Text);
    }

    This routine is similar to the previous one. The difference is that it applies the color selected in the cbBackColor combo box to the background of the lblSample label.

Next, we will create a handler for the OnClick event of the check box controls. This event is raised when a check box is checked or unchecked. The event handler will set or clear the appropriate attribute (bold, italic, underline or strikeout) of the sample text. We will create a single, universal event handler and then attach it to each of the check boxes:

  1. Insert the following routine into the laCode unit:

    JScript

    [laCode.js]

    // Applies the specified font style to the sample area
    function laEditForm_chkFontStyle_OnClick(Sender)
    {
      var frm = UserForms.laEditForm;
      var style = 0;

      if (frm.chkBold.Checked)      style |= 0x1;
      if (frm.chkItalic.Checked)    style |= 0x2;
      if (frm.chkUnderline.Checked) style |= 0x4;
      if (frm.chkStrikeout.Checked) style |= 0x8;

      frm.lblSample.Style.Font.Style = style;
    }

  2. In the form editor, select the chkBold control.

  3. Open the Events page of the Properties panel and click the down arrow button of the OnClick event. TestComplete will display the Select Test dialog that holds a list of all suitable routines for the event handler:

    Select Test Dialog
  4. Select the laEditForm_chkFontStyle_OnClick routine in the list and click OK.

  5. Repeat steps 2-4 for the chkItalic, chkUnderline, and chkStrikeout controls.

Finally, we will create a handler for the OnClick event of the btnHelp button. This code will be executed when the user clicks the Help button in the form.

  • In the form editor, select the btnHelp button.

  • Switch to the Properties panel, activate the Events page and create the event handler for the OnClick event. Name the routine laEditForm_btnHelp_OnClick and add it to the laCode unit.

  • Specify the following code for the routine:

    JScript

    [laCode.js]

    // Displays Help for the Log Attributes operation
    function laEditForm_btnHelp_OnClick(Sender)
    {
      Help.ShowContext("LogAttrExtension.chm", 3041);
    }

    This code opens the help file and displays a topic that contains information about the form.

    In this tutorial, we will not create the LogAttrExtension.chm help file manually. Instead, we will copy it from an existing script extension:

    • Open Windows Explorer or any other file manager and go to the <TestComplete>\Bin\Extensions\ScriptExtensions folder.

    • Copy the AQAScriptExtensions.chm file, which resides in this folder, to the C:\My Extensions\LogAttrExtension folder.

    • Rename the file to LogAttrExtension.chm.

    Note that the help file name must not contain spaces. Also, the name of the .chm help file must coincide with the name of the script extension’s .tcx file in order for TestComplete to be able to install the script extension correctly.

    For detailed information on calling help topics from forms used by script extensions, see Calling Help for Script Extensions.

3. Saving the Form in a Special Format

To be able to use the created form in a script extension, you need to save the form in a special format:

  • Open the form editor and right-click somewhere within the form.

  • Select Export to File from the context menu. This will invoke the standard Save File dialog.

  • Save the form under the laEditForm.aqfrm name to the C:\My Extensions\LogAttrExtension folder.

There is no need to add information about the form to the description.xml file. The only requirement is that the form file resides in the same folder that the description.xml and other files of our script extension are in.

Prev     Next

See Also

Script Extensions
User Forms
Using Forms in Script Extensions
Handling Events in User Forms

Highlight search results