Handling Events in User Forms

Applies to TestComplete 15.0, last modified on November 17, 2021

TestComplete lets you handle events that occur in user form components. An event handler is a script routine or keyword test, which is usually named as <FormName>_<ComponentName>_<EventName>. It is executed when the corresponding event occurs in the component or it can also be called from other keyword tests or script routines just like any other test or routine. To “bind” a keyword test or script routine to a component’s event, you should specify this test or routine on the Events page of the User Forms editor. You can either specify an existing test or routine for handling events, or create a new test or routine.

To create a new test for event handling
  • Select the desired component on the user form or choose it in the Components list.

  • Click in the Properties panel to switch to the Events page (by default, this panel is on the right of the User Forms editor).

  • Click the cell right to the event name and then press the ellipsis button within the cell.

  • In the resulting New Event Handler dialog, specify a test for the event handling routine.
  • After you press OK to close the dialog, TestComplete will create the new test, bind it to the event and display it in the Code Editor or in the Keyword Test editor.

Now you can write code or append keyword test operations that will perform the desired actions when the given event occurs.

To specify an existing test for event handling
  • Select the desired component on the form or choose it in the Components list.

  • Click in the Properties panel to switch to the Events page (by default, this panel is on the right of the User Forms editor).

  • Click the cell on the right of the event name and then press the down button within the cell.

  • In the ensuing Select Test dialog, choose a script routine or keyword test for handling the selected event.

    Note that this dialog lists only those script routines and keyword tests that have the same number of parameters as the handler that the given event requires.

  • Press OK to close the dialog.

To bind a single event handler to multiple events

It is possible to bind a single script routine or keyword test to multiple events. These can be several events of the same component, or the same event of several components, or both. To attach the event handler to multiple events, perform the steps described in the previous section for each needed event and each time select the same test or script routine for event handling.

Having a single keyword test or script routine for handling the same events in multiple components may be more convenient than having several similar tests or routines for this purpose. For example, if you have several TcxCheckBox components that form a logical group, you can create a single keyword test or script routine for handling the OnChange event of all check boxes.

Any event handler has a parameter, usually named Sender, that specifies the object where the event occurred. Using this parameter, you can determine which component raised the event. To get the component name, use the Name property of the Sender object.

JavaScript, JScript

function cbOptionsForm_checkBox_OnChange (Sender)
{
  switch (Sender.Name)
  {
    case "cbOption1" : DoActionA(); break;
    case "cbOption2" : DoActionB(); break;
    ...
  }
}

Python

def cbOptionsForm_checkBox_OnChange(Sender):
  if Sender.Name == "cbOption1":
    DoActionA()
  elif Sender.Name == "cbOption2":
    DoActionB()

VBScript

Sub cbOptionsForm_checkBox_OnChange (Sender)
  Select Case Sender.Name
    Case "cbOption1" DoActionA()
    Case "cbOption2" DoActionB()
    ...
  End Select
End Sub

DelphiScript

function cbOptionsForm_checkBox_OnChange (Sender);
begin
  case Sender.Name of
     'cbOption1' : DoActionA();
     'cbOption2' : DoActionB();
    ...
  end;
end;

C++Script, C#Script

function cbOptionsForm_checkBox_OnChange (Sender)
{
  switch (Sender["Name"])
  {
    case "cbOption1" : DoActionA(); break;
    case "cbOption2" : DoActionB(); break;
    ...
  }
}

To check the parameter value in keyword tests, you can use the If... Then operation.

To rename an event handler

If you need to rename an event handler, you should rename the keyword test in the Project Explorer panel or rename the script routine in the Code Editor and also update the reference to the handler in the User Forms editor. To do this:

  • Click the cell to the right of the event name and then press the down button within the cell.

  • In the ensuing Select Test dialog, choose the new test name.

  • Press OK to save changes and close the dialog.

To remove an event handler
  • Click the cell to the right of the event name and then press the down button within the cell.

  • In the ensuing Select Test dialog, select [None] in the Available Tests list.

  • Press OK to save changes and close the dialog.

Removing an event handler simply deletes the association between the event and the event handler. It does not remove the corresponding routine from the script or the keyword test from the project.

See Also

User Forms
User Forms Editor
Handling Events

Highlight search results