Description

An object can have one or more child objects. For instance, processes are children of the Sys object and windows are children of processes. The FindChild method searches for a child object with the specified values of the specified properties.

The FindChild method is analogue to Find. The difference between them is that Find searches in the object and its child objects, while FindChild only searches in child objects.

Declaration

TestObj.FindChild(PropNames, PropValues, Depth, RefreshTree)

TestObj	A variable, parameter or expression that specifies a reference to one of the objects listed in the Applies To section
PropNames	[in]	Required	Variant
PropValues	[in]	Required	Variant
Depth	[in]	Optional	Integer	Default value: 0
RefreshTree	[in]	Optional	Boolean	Default value: True
Result	Object

Applies To

All processes, windows, controls and onscreen objects.

View Mode

This method is available in the Object Browser panel and in other panels and dialogs in both Basic and Advanced view modes.

Parameters

The method has the following parameters:

PropNames

A property or an array of properties by which the method will search for an object.

You can view the list of object properties and their values in the Object Browser. See Exploring Object Properties and Methods in the Object Browser.

For web applications and hybrid mobile applications, you can also specify names of native web attributes (since TestComplete treats native web attributes as object properties). See Accessing Native Web Attributes and Methods for details.

PropValues

A value of a single property or an array of values of properties that the PropNames parameter specifies.

Values can contain wildcards or regular expressions:

The asterisk (*) wildcard corresponds to a string of any length (including an empty string).
The question mark (?) wildcard corresponds to any single character (including none).
To specify more complicated sought-for patterns for property values, use regular expressions, in the following format: regexp:<pattern>. For example, regexp:gr[ae]y.

The property does not support native regular expression syntax, that is, the syntax provided by scripting languages. Use standard TestComplete (non-native) syntax to specify regular expressions.

Notes:
- All patterns are case-insensitive. For example, "regexp:gr[ae]y" will match both "gray" and "GRAY".
- Patterns search for partial matches. For example, regexp:notepad matches both "notepad" and "notepad++". To search for an exact match, use the ^ and $ anchors, for example "regexp:^notepad$".
For detailed information on regular expression syntax, see Regular Expressions Syntax .

Depth

An integer value that sets the maximum level of the object’s hierarchy that the method will reach while searching for the specified object.

If Depth is less than or equal to 0 (0 is the default value), the method will search for the specified object among immediate children of the testObj object.

If Depth is 1, the method will search among child objects of the testObj object and their child objects. If Depths is 2, the method will search among the testObj object’s child objects, their child and grandchild objects, and so on.

To search in the whole hierarchy of the testObj object’s child objects, use a Depth value that is greater than the number of child levels in the hierarchy, for example, 2000.

RefreshTree

TestComplete performs the search in the cached copy of the object hierarchy, which may not correspond to the actual hierarchy of objects in the tested application. This may happen, for instance, if the actions that precedes the search caused changes in the application state. The RefreshTree parameter lets you specify what TestComplete should do if no object matching the search criteria was found in the cached object tree. If it is True (default), TestComplete will refresh the cached object tree and perform the search once again. If it is False, TestComplete will not refresh the object tree and will return a stub object indicating that the search failed.

Result Value

The object that has the specified values of the specified properties. If no object matching the search criteria was found, the FindChild method returns a stub object that only contains the Exists property equal to False. So, you can check the Exists property value of the returned object to determine whether the search was successful.

Remarks

As an alternative to using the FindChild method, to get a needed tested object, you can use Name Mapping. Specify the properties by which your tested object will be searched and store the object together with its search criteria in the Name Mapping repository for later use. To learn more, see Name Mapping.
We do not recommend that you use the VisibleOnScreen property in a search condition of the method. It may take much time for TestComplete to get the value of this property, and using it for searching for objects may decrease the test performance significantly.
To call the FindChild method in a keyword test, you can use the Call Object Method or Run Code Snippet operation. A possible alternative is to use the Find Object operation.
The project property Object search strategy controls whether the method uses depth-first or breadth-first search.
When the FindChild method is used to search for an object by its name (the Name property), TestComplete ignores spaces and the following characters in the name:

( ) [ ] . , " '

This behavior is intended to eliminate differences between the object name syntax in different scripting languages during the search. This way, for example, FindChild can search for the Notepad process by any of the following names: Process("notepad") (VBScript, JavaScript, JScript and Python syntax), Process('notepad') (DelphiScript syntax) and ["Process"]("notepad") (C++Script and C#Script syntax).

In general, it is not recommended to use the Name property with FindChild; consider using other properties instead. For example, Name is a complex value that is composed of other properties, such as WndClass or WndCaption, so you can search by a combination of these individual properties.
To obtain an object by its name, you can also use the following techniques:
- If you know the object name, you can refer to the object directly by this name:
  
  JavaScript, JScript
  
  Python
  
  VBScript
  
  DelphiScript
  
  C++Script, C#Script
  Copy Code
  
  JavaScript, JScript
  
  var wndNotepad = Sys.Process("notepad").Window("Notepad", "Untitled - Notepad");
  
  Python
  
  wndNotepad = Sys.Process("notepad").Window("Notepad", "Untitled - Notepad")
  
  VBScript
  
  Set wndNotepad = Sys.Process("notepad").Window("Notepad", "Untitled - Notepad")
  
  DelphiScript
  
  wndNotepad := Sys.Process('notepad').Window('Notepad', 'Untitled - Notepad');
  
  C++Script, C#Script
  
  var wndNotepad = Sys["Process"]("notepad")["Window"]("Notepad", "Untitled - Notepad");
- If an object name is specified as a string in your test (for example, if it is stored in a script variable), you can get the object by "evaluating" the string holding its name. For this purpose, you can use the following functions: eval in JavaScript, JScript, Python, C#Script and C++Script, Eval in VBScript and Evaluate in DelphiScript. The following example demonstrates this approach:
  JavaScript, JScript
  
  Python
  
  VBScript
  
  DelphiScript
  
  C++Script, C#Script
  Copy Code
  JavaScript, JScript
  
  function NotepadTest()
  {
    var strObjName, p, wndNotepad;
  
    strObjName = "Window(\"Notepad\", \"* - Notepad\")";
  
    // Store the parent object to a variable
    p = Sys.Process("notepad");
  
    // Obtain the object by its Name property
    // p is the name of the variable that holds the parent object
    wndNotepad = eval("p." + strObjName);
  
    Log.Picture(wndNotepad, "Notepad window", wndNotepad.FullName);
  }
  Python
  
  def NotepadTest(): strObjName = "Window(\"Notepad\", \"* - Notepad\")" # Store the parent object to a variable p = Sys.Process("notepad") # Obtain the object by its Name property # p is the name of the variable that holds the parent object wndNotepad = eval("p." + strObjName) Log.Picture(wndNotepad, "Notepad window", wndNotepad.FullName)
  VBScript
  
  Sub NotepadTest
    Dim strObjName, p, wndNotepad
  
    strObjName = "Window(""Notepad"", ""* - Notepad"")"
  
    ' Store the parent object to a variable
    Set p = Sys.Process("notepad")
  
    ' Obtain the object by its Name property
    ' p is the name of the variable that holds the parent object
    Set wndNotepad = Eval("p." & strObjName)
  
    Log.Picture wndNotepad, "Notepad window", wndNotepad.FullName
  End Sub
  
  DelphiScript
  
  procedure NotepadTest;
  var strObjName, p, wndNotepad;
  begin
    strObjName := 'Window(''Notepad'', ''* - Notepad'')';
  
    // Store the parent object to a variable
    p := Sys.Process('notepad');
  
    // Obtain the object by its Name property
    // p is the name of the variable that holds the parent object
    wndNotepad := Evaluate('p.' + strObjName);
  
    Log.Picture(wndNotepad, 'Notepad window', wndNotepad.FullName);
  end;
  
  C++Script, C#Script
  
  function NotepadTest()
  {
    var strObjName, p, wndNotepad;
  
    strObjName = "[\"Window\"](\"Notepad\", \"* - Notepad\")";
  
    // Store the parent object to a variable
    p = Sys["Process"]("notepad");
  
    // Obtain the object by its Name property
    // p is the name of the variable that holds the parent object
    wndNotepad = eval("p" + strObjName);
  
    Log.Picture(wndNotepad, "Notepad window", wndNotepad.FullName);
  }
In mobile tests, the identification criteria of the objects that the FindChild method returns are based on the internal properties that TestComplete assigns to objects. This differs from the objects you can get by using various FindElement, FindElements, and WaitElements methods. Their identification criteria are based on the accessibility information the tested application provides. This makes the objects got by Find methods and those got by the FindElement, FindElements, and WaitElement methods incompatible.

Example

The following code searches for a visible window with the caption “Font style” among all child objects of the Notepad process. The window belongs to the Font dialog that Notepad shows when you select Format | Font from Notepad’s main menu.

JavaScript, JScript

function Test()
{
  var PropArray, ValuesArray, p, w;

  // Creates arrays of property names and values
  PropArray = new Array("WndCaption", "Visible");
  ValuesArray = new Array("Font st&yle:", true);

  // Searches for the window
  p = Sys.Process("Notepad");
  w = p.FindChild(PropArray, ValuesArray, 5);

  // Processes the search results
  if (w.Exists)
    Log.Message(w.FullName);
  else
    Log.Error("The object was not found.");
}

Python

def Test():
  
  # Creates arrays of property names and values
  PropArray = ["WndCaption", "Visible"]
  ValuesArray = ["Font st&yle:", True]

  # Searches for the window
  p = Sys.Process("Notepad")
  w = p.FindChild(PropArray, ValuesArray, 5)

  # Processes the search results
  if (w.Exists):
    Log.Message(w.FullName)
  else:
    Log.Error("The object was not found.")

VBScript

Sub Test
  Dim PropArray, ValuesArray, p, w

  ' Creates arrays of property names and values
  PropArray = Array("WndCaption", "Visible")
  ValuesArray = Array("Font st&yle:", True)

  ' Searches for the window
  Set p = Sys.Process("Notepad")
  Set w = p.FindChild(PropArray, ValuesArray, 5)

  ' Processes the search results
  If w.Exists Then
    Log.Message w.FullName
  Else
    Log.Error "The object was not found."
  End If
End Sub

DelphiScript

procedure Test;
var PropArray, ValuesArray, p, w;
begin
  // Creates arrays of property names and values
  PropArray := ['WndCaption', 'Visible'];
  ValuesArray := ['Font st&yle:', true];

  // Searches for the window
  p := Sys.Process('Notepad');
  w := p.FindChild(PropArray, ValuesArray, 1000);

  // Processes the search results
  if w.Exists then
    Log.Message(w.FullName)
  else
    Log.Error('The object was not found.');
end;

C++Script, C#Script

function Test()
{
  var PropArray, ValuesArray, p, w;

  // Creates arrays of property names and values
  PropArray = new Array("WndCaption", "Visible");
  ValuesArray = new Array("Font st&yle:", true);

  // Searches for the window
  p = Sys["Process"]("Notepad");
  w = p["FindChild"](PropArray, ValuesArray, 5);

  // Processes the search results
  if (w["Exists"])
    Log["Message"](w["FullName"]);
  else
    Log["Error"]("The object was not found.");
}

FindChild Method

Description

Declaration

Applies To

View Mode

Parameters

Result Value

Remarks

Example

See Also