Hierarchy

Functions for dealing with hierarchies.

DupHierarchy
Duplicate a hierarchy, and preserve parent->child relationship in the copied hierarchy, use with the functions below.
CopyHierarchy
Copy a hierarchy.
InstanceHierarchy
Instance a hierarchy.
ReferenceHierarchy
Reference a hierarchy.
GetChildren
Gets the child hierarchy of the passed object, to a specified depth.
GetDepth
Finds out how deep the object is in a hierarchy tree.
GetHierarchyRoot
Get the top level object of the hierarchy of passed object.
GetHierarchy
Gets the entire hierarchy associated with passed object.
GetParentChain
Get the single chain of parent objects to passed object.
SafeDelete
Safely deletes objects with instanced animation.

DupHierarchy:

Duplicate a hierarchy, preserving the parent->child relationship in the duplicated hierarchy.
Use copy/instance/referenceHierarchy instead of this function directly.

Returns:

An array of all the objects in the duplicated hierarchy. array[1] will be the root of the hierarchy.

Arguments:
<rootObject>
The object that you want duplicated along with its children.
<dupFunc>
A function that does the actual object duplication (ie. copy, instance, replace, etc)
[instanceAnimation:false]
If true, the animation of the duplicated children (but not the rootObject) will be instanced with the original objects. This can save a lot of space when duplicating many, or large, hierarchies.

Back to top...


CopyHierarchy:

Copies an object along with its children, preserving the parent->child relationship in the copies.

Returns:

An array of all the objects in the copied hierarchy. array[1] will be the root of the hierarchy.

Arguments:
<parentObj>
The object that you want copied along with its children.

Back to top...


InstanceHierarchy:

Instances an object along with its children, preserving the parent->child relationship in the instances.

Returns:

An array of all the objects in the instanced hierarchy. array[1] will be the root of the hierarchy.

Arguments:
<parentObj>
The object that you want instanced along with its children.
[instanceAnimation:false]
If true, the animation of the instanced children (but not the rootObject) will be instanced with the original objects. This can save a lot of space when instancing many, or large, hierarchies.

Back to top...


ReferenceHierarchy:

Refereces an object along with its children, preserving the parent->child relationship in the references.

Returns:

An array of all the objects in the referenced hierarchy. array[1] will be the root of the hierarchy.

Arguments:
<parentObj>
The object that you want referenced along with its children.
[instanceAnimation:false]
If true, the animation of the referenced children (but not the rootObject) will be instanced with the original objects. This can save a lot of space when referencingmany, or large, hierarchies.

Back to top...


GetChildren:

Gets the child hierarchy of the passed object, to a specified depth.

Returns:

An array of all the children of the passed parent object. The array will not contain the passed parent object.

Arguments:
<parentObj>
The object who's children are to be retrieved.
[depth:-1]
How deep to look in the object tree.
-1 will look for all children.
1 will only look for immediate children.
2 will look for children and "grandchildren, etc...
[objArray:#()]
An array to store the children in.

Back to top...


GetDepth:

Finds out how deep the object is in a hierarchy tree.

Returns:

Returns 0 if no parents, 1 if there is 1 parent, etc.

Arguments:
<object>
The object who's depth is to be retrieved.

Back to top...


GetHierarchyRoot:

Get the top level object of the hierarchy of passed object.

Returns:

The top level object in the hierarchy of the passed object, or the passed object if it is already the top level object.

Arguments:
<obj>
The object who's hierarchy root is to be retrieved.

Back to top...


GetHierarchy:

Gets the entire hierarchy associated with passed object.

Returns:

An array of all the objects associated with the hierarchy of the passed object.

Arguments:
<obj>
The object who's hierarchy tree is to be retrieved.

Back to top...


GetParentChain:

Get the single chain of parent objects to passed object.

Returns:

An array of objects that make up the direct parent chain of the passed object. array[1] == theRoot.

Arguments:
<obj>
The object who's parent chain is to be retrieved.

Back to top...


SafeDelete:

Safely deletes objects with instanced animation.

Returns:

An array of objects that couldn't be deleted (array size can be 0), or undefined on failure.
An object will not be deleted if it has children.

Arguments:
<objs>
An array of objects that are to be deleted.

Back to top...