FindChildEx Method

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 FindChildEx method searches for a child object with the specified values of the specified properties. If it does not find such an object (for example, it does not exist), the method refreshes the object tree and tries to find the object again. It keeps doing this until the method finds the object or until the timeout elapses.

If you do not want to use a timeout, set it to 0 or use the FindChild method.

The FindChildEx method is similar to FindEx. The difference between them is that FindEx searches in the object and its child objects, while FindChildEx only searches in child objects.

Declaration

Applies To

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.

We do not recommend using the VisibleOnScreen property in search criteria. It can significantly decrease your test performance because it may take some time for TestComplete to get this property’s value, and TestComplete will have to get the value for every object it checks during the search.

PropValues

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

Values can contain asterisk (*) or question mark (?) wildcards, or regular expressions. The asterisk (*) wildcard corresponds to a string of any length (including an empty string), the question mark corresponds to any single character (including none). To specify more complicated parts of the value, use regular expressions. For information on them, see the Remarks section below.

Values can be case-sensitive or case-insensitive depending on the Use case-sensitive parameters setting of your current project. Regular expression patterns are always case-insensitive.

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.

Depth

A zero-based number that specifies the level of child objects where FindChildEx will search for the desired object. By default, Depth is 0 and means that the method will search in the child objects of the testObj object. If Depth is 1, FindChildEx will search in child and grandchild objects; if Depth is 2, FindChildEx will search in child, grandchild and great grandchild objects, and so on. To search in the whole hierarchy of child objects, use a Depth value that is greater than the number of child levels in the hierarchy, for example, 20000.

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.

Timeout

Specifies the time, in milliseconds, for which the FindChildEx method will try to find the specified object. If the Timeout is 0, the method will search for the object only once, like the FindChild method. If the Timeout is -1, the waiting time is equal to the auto-wait timeout option.

Result Value

The object that has the specified values of the specified properties. If no object matching the search criteria was found, the FindChildEx 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

• To call the FindChildEx 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 FindChildEx 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, FindChildEx 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 FindChildEx; 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

    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

    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);
    }

• The actual waiting time can be longer than the specified timeout, because TestComplete analyzes the object tree.

• Regular expressions should start with "regexp:", for example:

  obj = parent.Find("PropName", "regexp:gr[ae]y", 5)

  Regular expression patterns use the standard TestComplete syntax, but have the following specifics:

  • 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$".

  Native regular expressions of the scripting languages are not supported.

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. If the object does not exist, the method will try to find it for ten seconds.

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.FindChildEx(PropArray, ValuesArray, 5, True, 1000)

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

See Also

FindAllChildren Method
FindEx Method
Find Method
FindAll Method
FindId Method
FindChild Method
Child Method
WaitChild Method