Description

Use this method to delay the script execution until the specified object of a VCL Open Application (Delphi or C++Builder using VCL) becomes available to TestComplete. The method returns a program object that provides a scripting interface to the specified window or control. The resulting object contains both VCL and TestComplete methods, properties, events and actions.

Declaration

TestObj.WaitVCLObject(Name, Timeout)

TestObj	A variable, parameter or expression that specifies a reference to one of the objects listed in the Applies To section
Name	[in]	Required	String
Timeout	[in]	Required	Integer
Result	Object

Applies To

The method is applied to the following objects:

Process, Window

View Mode

To view this method in the Object Browser panel and in other panels and dialogs, activate the Advanced view mode.

Parameters

The method has the following parameters:

Name

The name of the desired object. This can be the object’s name as it is specified in the tested application’s source code (the string that is returned by the object’s “native” Name property) or the name generated by TestComplete (when the “native” Name property is empty). TestComplete generates the name using the object’s class name (for example, TEdit) and an index. To learn the generated name, explore your application in the Object Browser.

Note: In some cases, the “native” name of an object can differ from its “real” name. To get access to the native object name, use the string which results from the NativeDelphiObject.Name property.

Timeout

The number of milliseconds to wait until the specified object becomes available. If Timeout is 0, the method returns immediately. If Timeout is -1, the wait time is infinite.

Note that Timeout value is not strict and if the tested application is busy, TestComplete could wait for the object for a longer period of time than it is specified by the parameter. The following can cause this:

A call to any WaitXXXObject method causes the object tree to refresh. To update object data, TestComplete may call some of object’s native methods that are accessible only from the application’s thread. When the thread is busy, TestComplete tries to call those methods during some pre-defined time (one second) thus delaying the refresh. There could be several attempts to get the object’s data which could result in a noticeable difference from the Timeout value.

Result Value

The WaitVCLObject method returns an object that provides a scripting interface to an object located in an Open Application that was created in Delphi or C++Builder using VCL classes. If TestComplete cannot access the specified object (for example, this object does not exist), the method will return an empty stub object. To determine whether WaitVCLObject returns a valid object, use the Exists property of the resultant object. If this property returns False, then the returned object is a stub object and the call to WaitVCLObject was not successful.

Remarks

The returned object contains both methods and properties defined in the application code as well as methods, properties and actions provided by TestComplete. The returned object may have two or more methods and properties with the same name. When you call such a method or property, a naming conflict will occur. To avoid it and to specify which method or property is to be called, use the NativeDelphiObject namespace.

The method is available only if the Delphi and C++Builder Application Support plugin is installed and enabled in TestComplete. Otherwise, the method is absent in the method list of the TestObj object.

WaitVCLObject Method