Working With the Event Control Editor

Adding Events to the Event Control

Creating an Event Handler

Using an Existing Event Handler for an Event

Modifying the Event Description

Viewing an Event Handler’s Commands (Code)

Renaming Events

Renaming Event Handlers

Removing Event Handlers

Removing Events From the Event Control

Saving or Cancelling Changes

To add events to the Event control, specify the event’s source in the Source object box, choose the desired events in the Available Events list and add these events to the Events to Handle list. For detailed information on these actions, see Adding Events to Event Controls.

The Events to Handle list displays the events that were added to the Events control. The list has two columns: Events to Handle and Event Handler. The Events to Handle column displays the events’ names. The Event Handler column displays the name of the script routine or keyword test that will be called when the event occurs.

To create an event handler:

1. Select the desired event in the Events to Handle list.

2. Select the Event Handler cell and click the New button displayed within this cell.

   -- or --

   Right-click the event and select Add Event Handler from the context menu.

   -- or --

   Double-click the event.

3. In the resulting New Event Handler dialog, specify the name for the event handling keyword test. If you want to create the event handling script routine, you can select any existing unit in the dialog and then specify the routine name. You can also create a new unit from the dialog by clicking the Script | Click here to add a new script unit item in the Test Containers tree. Press OK.

   Note:

   If you specify the name of an existing keyword test or script routine that has an inappropriate number of parameters, the specified handler name will be highlighted with red in the New Event Handler dialog, and the OK button will become unavailable. Thus, you cannot specify the name of an existing event handler if the number of its parameters is more or less than that the event to be handled requires.

TestComplete will create an event handler for the event and show it either in the Code Editor or in the Keyword Test editor, depending on whether you use a script routine or a keyword test as the event handler. Also, TestComplete will display the icon next to the event name in the Events to Handle list to indicate that this event has a handler.

Instead of creating a new routine or keyword test that will handle a specific event, you can associate an existing routine or keyword test with the event. To do this:

• Select the desired event in the Events to Handle list.

• In the Event Handler cell for that event, click the New button. This will invoke the New Event Handler dialog.

• In the Test Containers tree on the left of this dialog, select the KeywordTests item, if you want to use an existing keyword test, or select the unit that contains the desired event handling routine, if you prefer script routines as event handlers. In the Available Tests column on the right of the dialog, TestComplete will list the existing keyword tests or script routines that have the appropriate number of parameters required by the event to be handled. Routines and keyword tests that have an inappropriate number of parameters will not be listed in the Available Tests column.

• Press OK. TestComplete will associate the specified routine or keyword test with the event.

You can modify the description of events displayed in the Events to Handle list. To do this:

• Right-click the desired event in the list.

• Choose Edit Description from the context menu and specify the new description in the ensuing Change Event Description dialog.

To quickly jump to the code of the event handling routine or to view the commands of the handling keyword test:

1. Choose the desired event in the Events to Handle list.

2. Select the Event Handler cell and click the View button that is displayed within this cell.

   -- or --

   Right-click the event and select Show Source from the context menu.

   -- or --

   Double-click the routine name in the Event Handler cell.

TestComplete will open the script unit holding the event handling routine in the Code Editor and position the insertion point at the beginning of the routine, if the handler is implemented in a script routine. If a keyword test is used for handling, TestComplete will open this keyword test in the Keyword Test editor.

The name of the added event may coincide with the name of another event, which may have been added earlier. Each event in the Events to Handle list must have a unique name. If there are two or more events with identical names, you need to rename one of them. Keeping the events without renaming them will cause an error.

To rename an event, right-click it in the Events to Handle list, choose Rename from the context menu and then specify the new event name in the ensuing Rename Event dialog. TestComplete will display the original event name in parentheses next to the new name in the Events to Handle list.

In certain cases, you may want to rename event handling routines or keyword tests. If you do this directly in the Code Editor or in the Project Explorer (in case of a keyword test), the event’s reference to the handler will become invalid. To rename an event handler preserving the connection between it and the event, use the Event control editor:

• Right-click the desired event in the Events to Handle list and select Rename Event Handler from the context menu.

• In the ensuing dialog box, enter the new handler name and press OK.

-- or --

• Select the desired event in the Events to Handle list.

• Click the handler name in the Event Handler cell twice (not double-click). This will activate the in-place editor.

• Enter the new handler name and press OK.

After that, TestComplete renames the event handler in the Event Control Editor as well as in the Code Editor or in the Project Explorer.

To remove an event handler:

• Right-click the desired event in the Events to Handle list.

• Select Remove Event Handler from the context menu.

Removing an event handler simply deletes the association between the event and the event handler. It does not remove the corresponding handling routine or keyword test. If needed, you can then remove the routine in the Code Editor or the keyword test from the project in the Project Explorer panel.

For detailed instructions on deleting events, see Removing Events From Event Controls.

To save the changes made in the editor, choose File | Save from the TestComplete main menu. TestComplete updates the implementation of the Events control and registers the control in the operating system.

The Event control consists of two modules. The <TestComplete>\Bin\Extensions\tcEventControl.ocx module holds the binary code of the control. The <EventControlName>.tlb module is the type library and is located in the folder that holds the Events project item file (by default, <Project Folder>\Events) if the “Unregister the type library when the project is closed” option is unchecked. Otherwise, if the option is checked, the type library is located in a temporary folder and is removed when you close the project. This library describes the events used in the project. TestComplete does not recompile the .ocx module. It only updates the type library.

The type library’s description is specified in the TLB description box of the Event Control editor. This description identifies the control to other users: it is displayed in almost all dialogs that add ActiveX components to the development tools.

To discard any changes, close the editor and click No when TestComplete asks whether you want to save the changes.