Addressing Objects in C++Builder Applications

Applies to TestComplete 14.30, last modified on November 21, 2019

There are several ways to refer to objects in C++Builder applications. If you use Name Mapping in your test project, you can refer to application objects using their names specified in Name Mapping. For objects not in Name Mapping, you can use the naming syntax that directly includes identification properties and values of these objects. This topic explains both approaches.

About Object Names in the Object Browser

You can explore the object structure of the tested application in the Object Browser. Here is a sample view of the C++Builder application hierarchy displayed in the Object Browser:

A view of a C++Builder application in the object tree

Click the image to enlarge it.

Here, the Process("Orders") branch of the Sys object corresponds to your tested C++Builder application and further objects correspond to the application’s windows, controls and objects.

To refer to an individual object in a tested C++Builder application, select the needed object in the Object Browser or Object Spy. These tools display the selected object’s name above the member list. From the right-click menu, you can copy this name to the clipboard and then insert it into your test.

Copying the object name from the Object Browser

Click the image to enlarge it.

You may notice that this name is different from what you see in the object tree on the left of the Object Browser. This is because the name displayed at the top of the panel uses object aliases if they are defined, whereas the object tree uses the naming syntax that includes identification properties. The differences between the two object naming syntaxes are explained in the Addressing C++Builder Objects Using Name Mapping and Aliases and Addressing C++Builder Objects Without Name Mapping sections below.

You can also learn object names in different syntaxes by looking at the following object properties:

  • MappedName - the object’s fully-qualified alias (including aliases of all parent objects). This name is used for the object by default in your tests. Note that if the selected object is not in Name Mapping, this property is empty.

  • Name - the object name that includes its identification properties. This is the same name you see in the Object Browser’s object tree. For an explanation of this syntax, see below.

  • FullName - the object’s fully-qualified name in the syntax that includes the identification properties. This name consists of the object’s Name property value and the Names of all of its parent objects. See below.

Addressing C++Builder Objects Using Name Mapping and Aliases

By default, TestComplete uses object names from Name Mapping (the object repository) to refer to individual objects in C++Builder applications under test. These names are called aliases. When you record a test, TestComplete automatically adds recorded objects to Name Mapping and generates aliases for them.

You can see available object aliases and add new aliases in the Name Mapping editor.

Sample Name Mapping for a C++Builder application

Here, Mapped Objects and Aliases display the hierarchy of mapped objects and their aliases, respectively. The fully-qualified alias that can be used to refer to an object is displayed in the top right of the Name Mapping editor (see the image above). It starts with Aliases and includes aliases of all of the object’s parent objects separated by dots (in VBScript, JScript, Python and DelphiScript projects) or square brackets (in C++Script and C#Script projects). For example, in the image above you can see that you can refer to the ListView object using the following name:

JavaScript, JScript

Aliases.Orders.ListView

Python

Aliases.Orders.ListView

VBScript

Aliases.Orders.ListView

DelphiScript

Aliases.Orders.ListView

C++Script, C#Script

Aliases["Orders"]["ListView"]

You can copy object aliases from the Name Mapping editor to the clipboard and use them when manually adding test operations with the tested application’s objects.

The following example shows a sample item selection operation on the ListView control specified by an alias:

A keyword test operation over a C++Builder object addressed using its alias
Note: For simplicity, keyword tests do not display the Aliases identifier at the beginning of object aliases.

Also, keyword tests may not display intermediate objects in the application’s object hierarchy. To view the full name of an operation’s target object, double-click the operation or increase the Maximum depth option in Keyword Test Editor - Groups options.

JavaScript, JScript

Aliases.Orders.ListView.ClickItem("Samuel Clemens", 0);

Python

Aliases.Orders.ListView.ClickItem("Samuel Clemens", 0);

VBScript

Call Aliases.Orders.ListView.ClickItem("Samuel Clemens", 0)

DelphiScript

Aliases.Orders.ListView.ClickItem('Samuel Clemens', 0);

C++Script, C#Script

Aliases["Orders"]["ListView"]["ClickItem"]("Samuel Clemens", 0);

Note that the fully-qualified mapped name for this object is as follows:

JavaScript, JScript

NameMapping.Sys.Orders.MainForm.ListView

Python

NameMapping.Sys.Orders.MainForm.ListView

VBScript

NameMapping.Sys.Orders.MainForm.ListView

DelphiScript

NameMapping.Sys.Orders.MainForm.ListView

C++Script, C#Script

NameMapping["Sys"]["Orders"]["MainForm"]["ListView"]

Since the MainForm object is of no interest for our test, we exclude it from the path to the ListView object in the Alias tree, so the object hierarchy becomes shorter. Using aliases lets you make your scripts shorter and more readable.

For more information about using Name Mapping and aliases, see About Name Mapping and Access Objects by Aliases.

Addressing C++Builder Objects Without Name Mapping

Your tests can work not only with applications and objects added to Name Mapping, but also with any other running applications, their windows and controls. These objects can be addressed using syntax that directly includes identification property values.

Consider the following sample code and keyword test that illustrate how you can refer to an object in your C++Builder application:

A keyword test operation over a C++Builder object that is not in Name Mapping

JavaScript, JScript

Sys.Process("Orders").VCLObject("MainForm").VCLObject("ListView").ClickItem("Samuel Clemens", 0);

Python

Sys.Process("Orders").VCLObject("MainForm").VCLObject("ListView").ClickItem("Samuel Clemens", 0);

VBScript

Call Sys.Process("Orders").VCLObject("MainForm").VCLObject("ListView").ClickItem("Samuel Clemens", 0)

DelphiScript

Sys.Process('Orders').VCLObject('MainForm').VCLObject('ListView').ClickItem('Samuel Clemens', 0);

C++Script, C#Script

Sys["Process"]("Orders")["VCLObject"]("MainForm")["VCLObject"]("ListView")["ClickItem"]("Samuel Clemens", 0);

To learn the exact syntax for referring to a particular object, use the Object Browser - the object tree and the FullName property of objects always use this naming syntax. See the About Object Names in the Object Browser section above.

Let’s have a closer look at this notation and its components.

  • The notation starts with Sys object that represents the operating system.

  • The next object, Process("Orders"), represents the C++Builder application with the file name Orders.exe.

  • Further objects represent windows and controls in the C++Builder application.

    TestComplete uses the following syntax for these objects:

    VCLObject(ObjectIdentifier)

    CLXObject(ObjectIdentifier)

    • The VCLObject notation is used in C++Builder applications that use the VCL library; the CLXObject - for C++Builder applications that use the CLX library.

    • ObjectIdentifier is the object name (the value of the ObjectIdentifier property). This name is specified by the object’s native Name property. If the application code does not specify the Name property, TestComplete will address the application’s objects in the following way:

      • For non-windowed controls (for example, TLabel instances) TestComplete will generate the control’s name using the control’s class name and an index. To determine the object name, explore your application in the Object Browser.
      • Windowed controls and forms (for example, TEdit instances) can be addressed with the Window method of the parent object.

    For more information about the C++Builder object addressing syntax and its parameters, see a description of the VCLObject and CLXObject notations.

For examples of this syntax applied to objects in your tested C++Builder application, examine your application in the Object Browser. You can also copy this syntax from the Object Browser and paste it to your test to avoid having to type it manually.

Remarks

The VCLObject and CLXObject notations are used for C++Builder GUI objects of any type - forms, buttons, combo boxes, grids and so on. The word Object here does not mean that TestComplete does not identify the object type. Just the opposite, TestComplete supports many different types of C++Builder GUI objects and provides high-level methods and properties for automating operations with them. See Support for C++Builder Applications' Controls for more information.

Combining Mapped and Unmapped Object Names

You can combine aliases specified in Name Mapping and the VCLObject (or CLXObject) notation when referencing an object hierarchy in tests. For example, you can use aliases for parent objects and the VCLObject(ObjectIdentifier) notation for child objects:

JavaScript, JScript

Aliases.Orders.MainForm.VCLObject("ListView").ClickItem("Samuel Clemens", 0);

Python

Aliases.Orders.MainForm.VCLObject("ListView").ClickItem("Samuel Clemens", 0);

VBScript

Call Aliases.Orders.MainForm.VCLObject("ListView").ClickItem("Samuel Clemens", 0)

DelphiScript

Aliases.Orders.MainForm.VCLObject('ListView').ClickItem('Samuel Clemens', 0);

C++Script, C#Script

Aliases["Orders"]["MainForm"]["VCLObject"]("ListView")["ClickItem"]("Samuel Clemens", 0);

However, keep in mind that aliases must always precede the VCLObject (or CLXObject) notation in the object hierarchy. Aliases cannot be used after the VCLObject (or CLXObject) notation within the same statement. That is, the following statement is invalid:

JavaScript, JScript

Sys.Process("Orders").VCLObject("MainForm").ListView.ClickItem("Samuel Clemens", 0);

Python

Sys.Process("Orders").VCLObject("MainForm").ListView.ClickItem("Samuel Clemens", 0);

VBScript

Call Sys.Process("Orders").VCLObject("MainForm").ListView.ClickItem("Samuel Clemens", 0)

DelphiScript

Sys.Process('Orders').VCLObject('MainForm').ListView.ClickItem('Samuel Clemens', 0);

C++Script, C#Script

Sys["Process"]("Orders")["VCLObject"]("MainForm")["ListView"]["ClickItem"]("Samuel Clemens", 0);

Accessing Non-Visual Objects in C++Builder Applications

C++Builder applications can include non-visual objects that are not displayed in the Object Browser. However, you can access these objects from your tests.

To get access to a non-visual object, you need to find a property, field or method of another object (visual or non-visual) that would return a reference to the desired object. The parent object can be either visual or non-visual, but the root object in the tree of parent objects must be a visual object. To find the needed property or method, examine the tested C++Builder application in the Object Browser or ask the application developers.

Currently, TestComplete does not have access to non-visual objects, which cannot be obtained through methods or properties of visual objects. To be able to access a non-visual object, you need to add a method or property to a certain visual object (form) of your application that would return a reference to the desired object.

Further Reading

The following topics explain how to refer to objects in C++Builder applications while performing some common operations with them:

See Also

Testing C++Builder Applications
Testing C++Builder Applications - Overview
Support for C++Builder Applications' Controls
Accessing Native Properties and Methods of C++Builder Objects

Highlight search results