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 FindAllChildren method searches for all child objects that have the specified values of the specified properties. The search is started from child objects of testedObj and continues down the object hierarchy to the specified depth.

The FindAllChildren method is similar to the FindAll method. The difference between them is that FindAllChildren only searches in child objects, while FindAll also checks properties of the testedObj object.

Declaration

TestObj.FindAllChildren(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: 1
RefreshTree	[in]	Optional	Boolean	Default value: True
Result	An array of the tested objects.

Applies To

All processes, windows, controls and onscreen objects.

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:

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

A positive number (greater than 0) that specifies the level of child objects where FindAllChildren will search for the desired objects. By default, Depth is 1 and means that the method will search in the child objects of the testObj object. If Depth is 2, FindAllChildren will search in child and grandchild objects; if Depth is 3, FindAllChildren 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 precede the search caused changes in the application state. The RefreshTree parameter lets you specify what TestComplete should do if no objects matching the search criteria were 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 an empty array indicating that no objects were found.

Result Value

An array of child objects that have the specified values of the specified properties.

Note for JScript, C#Script and C++Script users: The array returned by the FindAllChildren method is in the safe array format, which is not compatible with standard JScript arrays. To use such an array in JScript, C#Script or C++Script code, you need to convert it to the native format using the toArray method of the variant array.

Remarks

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.
When the FindAllChildren method is used to search for objects by 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.

In general, it is not recommended to use the Name property with FindAllChildren; 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.
In mobile tests, the identification criteria of the objects that the FindAllChildren 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 example searches for all buttons of the Edit class in the Notepad’s Font dialog (Notepad must be running). The example uses a single search condition: WndClass equals to “Edit”. The single values are passed to the PropNames and PropValues parameters:

JavaScript

function FindEditbuttons()
{
  var p, w, textBoxes;

  // Obtain the Notepad process
  p = Sys.Process("notepad");

  // Open the Font dialog
  p.Window("Notepad", "*").MainMenu.Click("Format|Font...");
  w = p.Window("#32770", "Font");

  // Search for all edit buttons in the Font dialog
  textBoxes = w.FindAllChildren("WndClass", "Edit", 5);

  // Log the search results
  if (textBoxes.length > 0)
  {
    for (let i = 0; i < textBoxes.length; i++)
      Log.Message("FullName: " + textBoxes[i].FullName + "\r\n" +
                  "Text: " + textBoxes[i].wText);
    Log.Message("Total number of found edit buttons: " + textBoxes.length);
  }
  else
    Log.Warning("No edit buttons found.");
}

JScript

function FindEditbuttons()
{
  var p, w, textBoxes, i;

  // Obtain the Notepad process
  p = Sys.Process("notepad");

  // Open the Font dialog
  p.Window("Notepad", "*").MainMenu.Click("Format|Font...");
  w = p.Window("#32770", "Font");

  // Search for all edit buttons in the Font dialog
  textBoxes = w.FindAllChildren("WndClass", "Edit", 5).toArray();

  // Log the search results
  if (textBoxes.length > 0)
  {
    for (i = 0; i < textBoxes.length; i++)
      Log.Message("FullName: " + textBoxes[i].FullName + "\r\n" +
                  "Text: " + textBoxes[i].wText);
    Log.Message("Total number of found edit buttons: " + textBoxes.length);
  }
  else
    Log.Warning("No edit buttons found.");
}

Python

def FindEditbuttons():
  # Obtain the Notepad process
  p = Sys.Process("notepad")
  # Open the Font dialog
  p.Window("Notepad", "*").MainMenu.Click("Format|Font...")
  w = p.Window("#32770", "Font")
  # Search for all edit buttons in the Font dialog
  textBoxes = w.FindAllChildren("WndClass", "Edit", 5)
  # Log the search results
  if len(textBoxes) > 0:
    for i in range(0, len(textBoxes)):
      Log.Message("FullName: " + textBoxes[i].FullName + "\r\n" + "Text: " + textBoxes[i].wText)
    Log.Message("Total number of found edit buttons: " + str(len(textBoxes)))
  else:
    Log.Warning("No edit buttons found.")

VBScript

Sub FindEditbuttons
  Dim p, w, textBoxes, i

  ' Obtain the Notepad process
  Set p = Sys.Process("notepad")

  ' Open the Font dialog
  p.Window("Notepad", "*").MainMenu.Click("Format|Font...")
  Set w = p.Window("#32770", "Font")

  ' Find all edit buttons in the Font dialog
  textBoxes = w.FindAllChildren("WndClass", "Edit", 5)

  ' Log the search results
  If UBound(textBoxes) >= 0 Then
    For i = 0 To UBound(textBoxes)
      Log.Message("FullName: " & textBoxes(i).FullName & vbNewLine & _
                  "Text: " & textBoxes(i).wText)
    Next
    Log.Message("Total number of found edit buttons: " & (UBound(textBoxes) + 1))
  Else
    Log.Warning("No edit buttons found.")
  End If
End Sub

DelphiScript

procedure FindEditbuttons;
var p, w, textBoxes, i;
begin
  // Obtain the Notepad process
  p := Sys.Process('notepad');

  // Open the Font dialog
  p.Window('Notepad', '*').MainMenu.Click('Format|Font...');
  w := p.Window('#32770', 'Font');

  // Find all edit buttons in the Font dialog
  textBoxes := w.FindAllChildren('WndClass', 'Edit', 5);

  // Log the search results
  if VarArrayHighBound(textBoxes, 1) >= 0 then
  begin
    for i := 0 to VarArrayHighBound(textBoxes, 1) do
      Log.Message('FullName: ' + textBoxes[i].FullName + #13#10 +
                  'Text: ' + textBoxes[i].wText);
    Log.Message('Total number of found edit buttons: ' + aqConvert.VarToStr(VarArrayHighBound(textBoxes, 1) + 1));
  end
  else
    Log.Warning('No edit buttons found.');
end;

C++Script, C#Script

function FindEditbuttons()
{
  var p, w, textBoxes, i;

  // Obtain the Notepad process
  p = Sys["Process"]("notepad");

  // Open the Font dialog
  p["Window"]("Notepad", "*")["MainMenu"]["Click"]("Format|Font...");
  w = p["Window"]("#32770", "Font");

  // Obtain all edit buttons in the Font dialog
  textBoxes = w["FindAllChildren"]("WndClass", "Edit", 5)["toArray"]();

  // Log the search results
  if (textBoxes["length"] > 0)
  {
    for (i = 0; i < textBoxes["length"]; i++)
      Log["Message"]("FullName: " + textBoxes[i]["FullName"] + "\r\n" +
                  "Text: " + textBoxes[i]["wText"]);
    Log["Message"]("Total number of found edit buttons: " + textBoxes["length"]);
  }
  else
    Log["Warning"]("No edit buttons found.");
}

Below is a more complex example. It searches for all enabled buttons in Notepad’s Replace dialog (Notepad must be running). This example uses a multiple search conditions: WndClass equals “Button” and Enabled is equal to True. The PropNames and PropValues parameters of the FindAllChildren method receive variant arrays containing the sought-for property names and values.

JavaScript

function FindEnabledButtons()
{
  var p, w, PropArray, ValuesArray, buttons;

  // Obtain the Notepad process
  p = Sys.Process("notepad");

  // Open the Replace dialog
  p.Window("Notepad", "*").MainMenu.Click("Edit|Replace...");
  w = p.Window("#32770", "Replace");

  // Specify the sought-for property names
  PropArray = new Array ("WndClass", "Enabled");
  // Specify the sought-for property values
  ValuesArray = new Array ("Button", true);

  // Find all enabled buttons in the Replace dialog
  buttons = w.FindAllChildren(PropArray, ValuesArray, 5);

  // Log the search results
  if (buttons.length > 0)
  {
    for (let i = 0; i < buttons.length; i++)
      Log.Message(buttons[i].FullName);
    Log.Message("Total number of found enabled buttons: " + buttons.length)
  }
  else
    Log.Warning("No enabled buttons were found.");
}

JScript

function FindEnabledButtons()
{
  var p, w, PropArray, ValuesArray, buttons, i;

  // Obtain the Notepad process
  p = Sys.Process("notepad");

  // Open the Replace dialog
  p.Window("Notepad", "*").MainMenu.Click("Edit|Replace...");
  w = p.Window("#32770", "Replace");

  // Specify the sought-for property names
  PropArray = new Array ("WndClass", "Enabled");
  // Specify the sought-for property values
  ValuesArray = new Array ("Button", true);

  // Find all enabled buttons in the Replace dialog
  buttons = w.FindAllChildren(PropArray, ValuesArray, 5).toArray();

  // Log the search results
  if (buttons.length > 0)
  {
    for (i = 0; i < buttons.length; i++)
      Log.Message(buttons[i].FullName);
    Log.Message("Total number of found enabled buttons: " + buttons.length)
  }
  else
    Log.Warning("No enabled buttons were found.");
}

Python

def FindEnabledButtons():
  # Obtain the Notepad process
  p = Sys.Process("notepad")
  # Open the Replace dialog
  p.Window("Notepad", "*").MainMenu.Click("Edit|Replace...")
  w = p.Window("#32770", "Replace")
  # Specify the sought-for property names 
  PropArray = ["WndClass", "Enabled"]
  # Specify the sought-for property values
  ValuesArray = ["Button", True]
  # Find all enabled buttons in the Replace dialog
  buttons = w.FindAllChildren(PropArray, ValuesArray, 5)
  # Log the search results
  if len(buttons) > 0:
    for i in range(0, len(buttons)):
      Log.Message(buttons[i].FullName);
    Log.Message("Total number of found enabled buttons: " + str(len(buttons)))
  else:
     Log.Warning("No enabled buttons were found.")

VBScript

Sub FindEnabledButtons
  Dim p, w, buttons, i, PropArray, ValuesArray

  ' Obtain the Notepad process
  Set p = Sys.Process("notepad")

  ' Open the Replace dialog
  p.Window("Notepad", "*").MainMenu.Click("Edit|Replace...")
  Set w = p.Window("#32770", "Replace")

  ' Specify the sought-for property names
  PropArray = Array("WndClass", "Enabled")
  ' Specify the sought-for property values
  ValuesArray = Array("Button", True)

  ' Find all enabled buttons in the Replace dialog
  buttons = w.FindAllChildren(PropArray, ValuesArray, 5)

  ' Log the search results
  If UBound(buttons) >= 0 Then
    For i = 0 To UBound(buttons)
      Log.Message(buttons(i).FullName)
    Next
    Log.Message("Total number of found enabled buttons: " & (UBound(buttons) + 1))
  Else
    Log.Warning("No enabled buttons were found.")
  End If
End Sub

DelphiScript

procedure FindEnabledButtons;
var p, w, PropArray, ValuesArray, buttons, i;
begin
  // Obtain the Notepad process
  p := Sys.Process('notepad');

  // Open the Replace dialog
  p.Window('Notepad', '*').MainMenu.Click('Edit|Replace...');
  w := p.Window('#32770', 'Replace');

  // Specify the sought-for property names
  PropArray := ['WndClass', 'Enabled'];
  // Specify the sought-for property values
  ValuesArray := ['Button', true];

  // Find all enabled buttons in the Replace dialog
  buttons := w.FindAllChildren(PropArray, ValuesArray, 5);

  // Log the search results
  if VarArrayHighBound(buttons, 1) >= 0 then
  begin
    for i := 0 to VarArrayHighBound(buttons, 1) do
      Log.Message(buttons[i].FullName);
    Log.Message('Total number of found enabled buttons: ' + aqConvert.VarToStr(VarArrayHighBound(buttons, 1) + 1));
  end
  else
    Log.Warning('No enabled buttons were found.');
end;

C++Script, C#Script

function FindEnabledButtons()
{
  var p, w, PropArray, ValuesArray, buttons, i;

  // Obtain the Notepad process
  p = Sys["Process"]("notepad");

  // Open the Replace dialog
  p["Window"]("Notepad", "*")["MainMenu"]["Click"]("Edit|Replace...");
  w = p["Window"]("#32770", "Replace");

  // Specify the sought-for property names
  PropArray = new Array ("WndClass", "Enabled");
  // Specify the sought-for property values
  ValuesArray = new Array ("Button", true);

  // Find all enabled buttons in the Replace dialog
  buttons = w["FindAllChildren"](PropArray, ValuesArray, 5)["toArray"]();

  // Log the search results
  if (buttons["length"] > 0)
  {
    for (i = 0; i < buttons["length"]; i++)
      Log["Message"](buttons[i]["FullName"]);
    Log["Message"]("Total number of found enabled buttons: " + buttons["length"])
  }
  else
    Log["Warning"]("No enabled buttons were found.");
}

FindAllChildren Method

Description

Declaration

Applies To

View Mode

Parameters

Result Value

Remarks

Example

See Also