Articles

[Collapse]TestComplete/viewarticle/63445/
 [Expand]General Information/viewarticle/63445/
 [Expand]Using Help System/viewarticle/55799/
 [Expand]Getting Started Tutorial/viewarticle/56246/
 [Expand]Using TestComplete/viewarticle/57875/
 [Expand]Testing Types/viewarticle/62721/
 [Expand]Applications Testing/viewarticle/62606/
 [Expand]Working With Application Objects and Controls/viewarticle/55815/
 [Expand]Samples and Tutorials/viewarticle/56239/
 [Collapse]References/viewarticle/57878/
  [Collapse]Test Objects/viewarticle/57881/
   [Expand]Controls and Objects/viewarticle/59743/
   [Collapse]Methods and Properties/viewarticle/62328/
    [Expand]Common Methods and Properties (Desktop)/viewarticle/62329/
    [Expand]Common Methods and Properties (Web)/viewarticle/62327/
    [Expand]A
    [Expand]B
    [Expand]C
    [Expand]D
    [Expand]E
    [Collapse]F
      wFieldCount Property (Specific to iOS AlertView Object)/viewarticle/63579/
      wFieldText Property (Specific to iOS AlertView Object)/viewarticle/63590/
      FileVersionInfo Property/viewarticle/55332/
      Find Method/viewarticle/55436/
      FindAll Method/viewarticle/55466/
      FindAllChildren Method/viewarticle/55098/
      FindChild Method/viewarticle/55112/
      FindChildByXPath Method (Page Objects)/viewarticle/55745/
      FindChildByXPath Method (UIPage Objects)/viewarticle/55771/
      FindChildByXPath Method (Web Objects)/viewarticle/55732/
      FindId Method/viewarticle/55460/
      FindRow Action/viewarticle/55603/
      FlatScrollBar Property (ListViewStyleEx Objects)/viewarticle/61702/
      FlexObject Property/viewarticle/55507/
      Focus Property (Specific to Flash List and Flex List Objects)/viewarticle/62136/
      Focus Property (Specific to MSAA List Objects)/viewarticle/60936/
      wFocus Property (Android Controls)/viewarticle/62235/
      wFocus Property (ListBox Controls)/viewarticle/60294/
      wFocus Property (ListView Controls)/viewarticle/61820/
      Focused Property/viewarticle/56643/
      Focused Property (MSAA Objects)/viewarticle/60940/
      wFocused Property (ListView Controls)/viewarticle/61677/
      wFocused Property (Specific to InfragisticsWinListView Controls)/viewarticle/60719/
      wFocusedTab Property (Mobile Controls)/viewarticle/62317/
      wFocusedTab Property (Tab Controls)/viewarticle/60480/
      FocusedTab Property (Specific to MSAA TabList Objects)/viewarticle/60941/
      FocusedTab Property (Tab Controls)/viewarticle/62142/
      wFocusedTab Property (Tab Controls)/viewarticle/60480/
      FocusedWindow Method (Desktop Objects)/viewarticle/61960/
      FocusItem Action (ListView Controls)/viewarticle/61662/
      Footer Property (Specific to Win32ListViewGroup Object)/viewarticle/62030/
      FooterAlign Property (Specific to Win32ListViewGroup Objects)/viewarticle/62032/
      wFormat Property (Header Controls)/viewarticle/61626/
      Frame Method (Web Objects)/viewarticle/61570/
      FriendlyName Property (Windows Store Processes)/viewarticle/61067/
      FullName Property/viewarticle/57304/
      FullRowSelect Property (ListViewStyleEx Objects)/viewarticle/61704/
    [Expand]G
    [Expand]H
    [Expand]I
    [Expand]J
    [Expand]K
    [Expand]L
    [Expand]M
    [Expand]N
    [Expand]O
    [Expand]P
    [Expand]Q
    [Expand]R
    [Expand]S
    [Expand]T
    [Expand]U
    [Expand]V
    [Expand]W
    [Expand]X
    [Expand]Y
    [Expand]Z
  [Expand]Scripting Objects/viewarticle/57882/
  [Expand]Project and Project Item Objects/viewarticle/57880/
  [Expand]TestComplete Events/viewarticle/56945/
  [Expand]Language Reference/viewarticle/57879/
  [Expand]User Form Components/viewarticle/56689/
 [Expand]Other Tools That Help You Test Better/viewarticle/63442/
 [Expand]TestComplete 10 Licensing Guide/viewarticle/63451/
Updated: 7/15/2014 Applies To: TestComplete 10 Rating: AverageAverageAverageAverageAverage 4 vote(s) Click to rate: PoorNot badAverageGoodExcellent
Programming Reference

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

TestObj.FindChild(PropNamesPropValuesDepthRefresh)

   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
Refresh [in] Optional Boolean Default value: True
Result Object  

Applies To

All processes, windows, controls and onscreen objects.

Parameters

The method has the following parameters:

PropNames

An array of strings containing the names of properties or a single property name. See the Remarks section for details. The method returns an object by the values of these properties (property).

PropValues

An array containing the values of the specified properties or a single property value (see Remarks). The string property value(s) can contain asterisk (*) or question mark (?) wildcards. The asterisk corresponds to the string of any length, the question mark - to any single character.

Depth

A zero-based number that specifies the level of child objects where FindChild 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, FindChild will search in child and grandchild objects; if Depth is 2, FindChild 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.

Refresh

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

  • 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 and JScript 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:

      VBScript

      Set wndNotepad = Sys.Process("notepad").Window("Notepad", "Untitled - Notepad")

      JScript

      var 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 VBScript, eval in JScript, C++Script and C#Script and Evaluate in DelphiScript. The following example demonstrates this approach:

      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

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

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

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

Example

The following code searches for a visible window with the caption “Font style” among all child objects of the Notepad process (the window is part of the Font dialog that is displayed when selecting Format | Font from Notepad’s main menu).

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

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

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

See also
FindAllChildren Method | Find Method | FindAll Method | FindId Method | Find Method | Child Method | WaitChild Method


© 2014 SmartBear Software. All rights reserved.
Email Send feedback on this document