Description

The AddNamedChild method is added to any object that is mapped with the Name Mapping feature.

Use the AddNamedChild method to map child objects of the current mapped object. For instance, if the current object maps a process, you can use this method to map top-level windows of this process. If the object maps a window, you can use the AddNamedChild method to map a child window.

Declaration

.AddNamedChild(SysNode, ChildName, Description, Properties, StoreCodeCompletionInfo)


SysNode	[in]	Required	Object
ChildName	[in]	Required	String
Description	[in]	Required	String
Properties	[in]	Required	Variant
StoreCodeCompletionInfo	[in]	Optional	Boolean	Default value: False
Result	Object

Applies To

All mapped processes, windows and controls.

Parameters

The method has the following parameters:

SysNode

Specifies the object to be mapped.

Note:

The SysNode object must be a child of the tested mapped object. Else, an error will occur.

ChildName

Specifies the desired mapped name of the object. Child mapping items must have unique names within the parent mapping item. If you specify the name that coincides with the name of existing mapped item, an error will occur.

The ChildName string must be a valid script identifier. Else, an error will occur. To check whether ChildName is a valid identifier, you can use the aqUtils.IsValidIdent method.

Description

Specifies the description of the mapping item.

Properties

The name of the property that will be used to recognize the mapped object, or the array of property names.

Note: The AddNamedChild method only lets you map an object by its immediate properties. Mapping an object by properties that belong to objects returned by the immediate properties is only possible at design time. See the Mapping Objects Manually topic.

In VBScript, Python or DelphiScript, you can use “native” arrays as well as arrays created using the CreateVariantArray function.

As for JavaScript, JScript, C#Script and C++Script, the implementation of arrays in these languages (the binary implementation used by the scripting engine) differs from the arrays used in Python, VBScript or DelphiScript (see JavaScript - Specifics of Usage and JScript, C#Script and C++Script - Specifics of Usage). In order to use the AddNamedChild method, you need to convert the “native” JavaScript and JScript arrays to the format adopted in VBScript or DelphiScript. Without the conversion, you can still use the AddNamedChild method, but the Properties parameter should only specify one property, not at array.

You can find an example of using the arrays in the Mapping Objects From Tests topic.

StoreCodeCompletionInfo

Specifies whether TestComplete will store information about methods and properties of the mapped object. This information will allow you to view the object's members in keyword test operation editors and Code Completion when the tested application is not running or the object is not available in it. (See View Code Completion Information.)

If this parameter is False (default), information about object members will not be stored. If it is True, TestComplete will save the amount of member information specified by the Store Code Completion information option.

Result Value

If the method maps the specified object successfully, it returns the appropriate mapping item. Else, an error occurs.

Example

The following code snippet maps the Windows Notepad process using its ProcessName property. Note that the Sys object is already mapped.

JavaScript, JScript

function NameMappingSample()
{
  // Specifies the object to map
  var SysNodeObj = Sys.Process("Notepad");
  // Specifies the mapped name
  var Name = "Notepad";
  // Specifies the description for the new mapped object
  var Desc = "Mapped name for the Windows Notepad process object";
  // Specifies the single property to be used to recognize the mapped object
  var Prop = "ProcessName";

  // Maps the object
  var MappedObj = NameMapping.Sys.AddNamedChild(SysNodeObj, Name, Desc, Prop, true);

}

Python

def NameMappingSample():
  # Specifies the object to map
  SysNodeObj = Sys.Process("Notepad")
  # Specifies the mapped name
  Name = "Notepad"
  # Specifies the description for the new mapped object
  Desc = "Mapped name for the Windows Notepad process object"
  # Specifies the single property to be used to recognize the mapped object
  Prop = "ProcessName"

  # Maps the object
  MappedObj = NameMapping.Sys.AddNamedChild(SysNodeObj, Name, Desc, Prop, True)

VBScript

Sub NameMappingSample

  ' Specifies the object to map
  Set SysNodeObj = Sys.Process("Notepad")
  ' Specifies the mapped name
  Name = "Notepad"
  ' Specifies the description for the new mapped object
  Desc = "Mapped name for the Windows Notepad process object"
  ' Specifies the single property to be used to recognize the mapped object
  Prop = "ProcessName"

  ' Maps the object
  Set MappedObj = NameMapping.Sys.AddNamedChild(SysNodeObj, Name, Desc, Prop, True)

End Sub

DelphiScript

procedure NameMappingSample();
var SysNodeObj, Name, Desc, Prop, MappedObj;
begin
  // Specifies the object to map
  SysNodeObj := Sys.Process('Notepad');
  // Specifies the mapped name
  Name := 'Notepad';
  // Specifies the description for the new mapped object
  Desc := 'Mapped name for the Windows Notepad process object';
  // Specifies the single property to be used to recognize the mapped object
  Prop := 'ProcessName';

  // Maps the object
  MappedObj := NameMapping.Sys.AddNamedChild(SysNodeObj, Name, Desc, Prop, true);

end;

C++Script, C#Script

function NameMappingSample()
{
  // Specifies the object to map
  var SysNodeObj = Sys["Process"]("Notepad");
  // Specifies the mapped name
  var Name = "Notepad";
  // Specifies the description for the new mapped object
  var Desc = "Mapped name for the Windows Notepad process object";
  // Specifies the single property to be used to recognize the mapped object
  var Prop = "ProcessName";

  // Maps the object
  var MappedObj = NameMapping["Sys"]["AddNamedChild"](SysNodeObj, Name, Desc, Prop, true);

}

The following example maps the Windows Notepad process using the ProcessName and FullName properties. Note that the Sys object is already mapped. The ConvertScriptArray routine is used to convert the arrays in the JavaScript, JScript, C#Script and C++Script examples to the format adopted in VBScript and DelphiScript.

JavaScript

function NameMappingSampleWithArray()
{
  var Props = new Array(2);
  // Specifies the object to map
  var SysNodeObj = Sys.Process("Notepad");
  // Specifies the mapped name
  var Name = "Notepad";
  // Specifies the description for the new mapped object
  var Desc = "Mapped name for the Windows Notepad process object";
  // Specifies the properties to be used to recognize the mapped object
  Props[0] = "ProcessName";
  Props[1] = "FullName";

  // Maps the object
  var MappedObj = NameMapping.Sys.AddNamedChild(SysNodeObj, Name, Desc, ConvertScriptArray(Props), true);

}

// Convert a JavaScript array to a Variant-compatible array
function ConvertScriptArray(Array)
{
  var objDict = getActiveXObject("Scripting.Dictionary");
  objDict.RemoveAll();
  for (let i in Array)
    objDict.Add(i, Array[i]);
  return objDict.Items();
}

JScript

function NameMappingSampleWithArray()
{
  var Props = new Array(2);
  // Specifies the object to map
  var SysNodeObj = Sys.Process("Notepad");
  // Specifies the mapped name
  var Name = "Notepad";
  // Specifies the description for the new mapped object
  var Desc = "Mapped name for the Windows Notepad process object";
  // Specifies the properties to be used to recognize the mapped object
  Props[0] = "ProcessName";
  Props[1] = "FullName";

  // Maps the object
  var MappedObj = NameMapping.Sys.AddNamedChild(SysNodeObj, Name, Desc, ConvertScriptArray(Props), true);

}

// Convert a JScript array to a Variant-compatible array
function ConvertScriptArray(Array)
{
  var objDict = new ActiveXObject("Scripting.Dictionary");
  objDict.RemoveAll();
  for (var i in Array)
    objDict.Add(i, Array[i]);
  return objDict.Items();
}

Python

def NameMappingSampleWithArray():
  Props = []
  # Specifies the object to map
  SysNodeObj = Sys.Process("notepad")
  # Specifies the mapped name
  Name = "Notepad"
  # Specifies the description for the new mapped object
  Desc = "Mapped name for the Windows Notepad process object"
  # Specifies the properties to be used to recognize the mapped object
  Props.append("ProcessName")
  Props.append("FullName")

  # Maps the object
  MappedObj = NameMapping.Sys.AddNamedChild(SysNodeObj, Name, Desc, Props, True)

VBScript

Sub NameMappingSampleWithArray

  Dim Props(1)
  ' Specifies the object to map
  Set SysNodeObj = Sys.Process("Notepad")
  ' Specifies the mapped name
  Name = "Notepad"
  ' Specifies the description for the new mapped object
  Desc = "Mapped name for the Windows Notepad process object"
  ' Specifies the properties to be used to recognize the mapped object
  Props(0) = "ProcessName"
  Props(1) = "FullName"

  ' Maps the object
  Set MappedObj = NameMapping.Sys.AddNamedChild(SysNodeObj, Name, Desc, Props, True)

End Sub

DelphiScript

procedure NameMappingSampleWithArray();
var
  Props : array[0..1] of string;
  SysNodeObj, MappedObj : OleVariant;
  Name, Desc : string;
begin
  // Specifies the object to map
  SysNodeObj := Sys.Process('Notepad');
  // Specifies the mapped name
  Name := 'Notepad';
  // Specifies the description for the new mapped object
  Desc := 'Mapped name for the Windows Notepad process object';
  // Specifies the properties to be used to recognize the mapped object
  Props[0] := 'ProcessName';
  Props[1] := 'FullName';

  // Maps the object
  MappedObj := NameMapping.Sys.AddNamedChild(SysNodeObj, Name, Desc, Props, true);

end;

C++Script, C#Script

function NameMappingSampleWithArray()
{
  var Props = new Array(2);
  // Specifies the object to map
  var SysNodeObj = Sys["Process"]("Notepad");
  // Specifies the mapped name
  var Name = "Notepad";
  // Specifies the description for the new mapped object
  var Desc = "Mapped name for the Windows Notepad process object";
  // Specifies the properties to be used to recognize the mapped object
  Props[0] = "ProcessName";
  Props[1] = "FullName";

  // Maps the object
  var MappedObj = NameMapping["Sys"]["AddNamedChild"](SysNodeObj, Name, Desc, ConvertScriptArray(Props), true);

}

// Convert a JScript array to a Variant-compatible array
function ConvertScriptArray(ScriptArray)
{
  var objDict = new ActiveXObject("Scripting.Dictionary");
  objDict["RemoveAll"]();
  for (var i in ScriptArray)
    objDict["Add"](i, ScriptArray[i]);
  return objDict["Items"]();
}

AddNamedChild Method

Description

Declaration

Applies To

Parameters

Result Value

Example

See Also