ChildInstances

(Engine-Level Function)

Description	Returns the object values of module instances that are children of a particular module instance (i.e. all objects whose parent is a specified object).
Returns	Object array
Usage	Script Only.
Function Groups	Basic Module
Related to:	CalledInstances | GetInstance | Instance | NumInstances | Self | Valid
Format	ChildInstances(Object [, Options])
Parameters

Object

Required. An object value of the module instance for which to get the number of child instances.

Options

Required. Any numeric expression that defines which modules are to be included in the returned set. Options is formed by adding together the values from the following table: (See: Bitwise Parameters & Operations) Options Bit Number Description 1 0 Include all modules, even if they are in the same window as their caller. False to include only (root) modules for modules in separate windows. 2 1 Recurse into child module instances of children. False to include only modules whose immediate parent is the module instance referenced by the Object parameter. 4 2 Group all instances of the same module into an array and store that array of object values in the element of the returned array, instead of the object value.

Comments

The return value is an array of objects that are called from Object. If no instances are called from Object, Invalid is returned.

Example:

  i = -1;
...
  If i == -1;
  [
    NumKids = ChildInstances(Self()); 
    i++; 
  ]
  If Valid(NumKids [i]);
  [
    Slay(NumKids[i], 0); 
    i++; 
  ]

The first If statement and script creates an array of object values to all instances that are children of the current module. The second If and script slays all of these instances. Notice that in the case of the first script, the action trigger must be based on i rather than on a Valid test of numKids. If this were not the case and !Valid(numKids) was used instead, then, if there were in fact no child instances of this module, ChildInstances would return invalid, and an "if one" (infinite loop) condition would occur.