FindChild 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 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

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:

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

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

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

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.")

See Also

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