## NavigateNode

### Introduced

v1.5

### Description

Navigates through the given object or component, given the specified navigation filter and direction. Returns the corresponding object or component.
Note: To select an element, use SelectNeighborObj instead.

### Scripting Syntax

    oReturn = NavigateNode( [Source], [NavDirection], [NavLoop], [NavFilter], [NavSubFilter], [OutputObj] );

### Return Value

The node at the requested position or InputObj if there is no such node.
Note : Only the first matching node is returned.

### Parameters

Parameter | Type | Description
--- | --- | ---
Source | Selection List | Starting point of the navigation. Default Value: Current selection
NavDirection | Integer | Specifies how to navigate (ie. Up to the parent, down to the child or sideways to a sibling). Default Value: siParentNode
Possible Values: | Description:
siParentNode | Retrieve the parent
siChildNode | Retrieve the child
siNextNode | Retrieve the next sibling
siPreviousNode | Retrieve the previous sibling
siFirstNode | Retrieve the first sibling
siLastNode | Retrieve the last sibling
NavLoop | Boolean | Specifies whether to return to the begining of the hierarchy and continue searching when the end is reached or stop searching at the end. Default Value: False
Possible Values: | Description:
False | Do not loop through the hierarchy
True | Loop through the hierarchy
NavFilter | Integer | Type of object we want back. Default filtering is always used regardless of this value when NavDirection is siParentNode or siChildNode. Default Value: 11 : Same type as input
Possible Values: | Description:
1 | Scene
2 | 3D Object
3 | Operator
4 | Primitive
5 | Container or attribute
6 | Cluster
7 | Subcomponent
8 | Group
9 | Any COM Obj
10 | Any type
11 | Same Type as input
NavSubFilter | Integer | SubType of object we want. This is used in conjunction with the NavFilter argument. Default Value: 1: Same type as input.
Possible Values: | Description:
0 | Any type
1 | Same Type as input
OutputObj | Object derived from SIObject (for example, Parameter or Property or X3DObject) | The node at the requested position. If there is no such node, the node specified by the InputObj parameter is returned. Note : Only the first matching node is returned.

### Examples

#### 1. VBScript Example

    ' Returns the children of the current selection in a collection

    ' Ouput: XSICollection	| Children of the selected object

    Function GetChildren()

    	Set childColl = CreateObject( "XSI.Collection" )

    	If Selection.Count <> 1 Then

    		MsgBox "You must select an object in order to get its children.", vbExclamation, "GetChildren"

    	Else

    		Set oSelected = Selection(0)

    		SetUserPref "SCR_CMDLOG_ENABLED", False

    		' get the first child

    		Set oChild = NavigateNode( oSelected, siChildNode )

    		Set oCurrent = oChild

    		' if there is at least one child

    		If	StrComp( oSelected, oChild ) <> 0 Then

    			' Add the child and its siblings to the collection

    			Do

    				childColl.Add oCurrent

    				set oCurrent = NavigateNode( oCurrent, siNextNode, True, 10 )

    			Loop Until StrComp( oCurrent, oChild ) = 0

    		End If

    		SetUserPref "SCR_CMDLOG_ENABLED", True

    	End If

    	Set GetChildren = childColl

    End Function

    ' Displays the content of a collection in the scripting

    ' log

    ' Input: oColl	| Collection to display

    Sub DisplayCollectionContent( ByRef oColl )

    	Dim message

    	message = "The collection contains the following elements:" & vbLF & vbLF

    	For Each element In oColl

    		message = message & element & vbLf

    	Next

    	LogMessage message

    End Sub

    ' Create a new scene with a null then display its children

    NewScene ,False

    GetPrim "Null", "MyNull"

    DisplayCollectionContent( GetChildren() )

    'Output of the above script:

    'INFO : "The collection contains the following elements:

    '

    ' MyNull.Name

    ' MyNull.null

    ' MyNull.AmbientLighting

    ' MyNull.Scene_Material

    ' MyNull.geomapprox

    ' MyNull.display

    ' MyNull.kine

    ' MyNull.visibility

    ' MyNull.kine

    ' MyNull.display

    ' MyNull.visibility

    ' MyNull.Children

    '"

#### 2. VBScript Example

    ' Create a sphere and a cone :

    oSphere = CreatePrim( "Sphere", "MeshSurface" )

    oCone = CreatePrim( "Cone", "MeshSurface" )

    ParentObj oSphere, oCone

    '

    ' Navigate in the 3D object hierarchy.

    '

    LogMessage " --- Object Navigation ---"

    ' First, from the sphere, navigate "up" to get the scene root:

    rtn = NavigateNode( oSphere, 1, , , 0 )

    LogMessage "From " & oSphere & ", we obtained " & rtn

    ' Now navigate "down" from the sphere:

    rtn = NavigateNode( oSphere, 2, , 11, 0 )

    LogMessage "From " & oSphere & ", we obtained " & rtn

    '

    ' Now, navigate amongst newly created clusters.

    '

    LogMessage "--- Cluster Navigation ---"

    oCls1 = CreateCluster( oSphere & ".pnt[25-27,31-34,38-41]" )

    oCls2 = CreateCluster( oSphere & ".pnt[3-6,11-13,52-55]" )

    ' From the first cluster, get the second one:

    rtn = NavigateNode( oCls1, 3, True )

    LogMessage "From " & oCls1 & ", we obtained " & rtn

    ' From the previously obtained cluster, return the next one.

    ' If the next one doesn't exist, make sure we loop.

    LogMessage "We have now reached the end of the cluster list."

    newrtn = NavigateNode( rtn, 3, True, 6, 1 )

    LogMessage "From " & rtn & ", we loop and we obtained " & newrtn

    ' Same as above but this time, we will not "loop".

    newrtn = NavigateNode( rtn, 3, False, 6, 1 )

    LogMessage "From " & rtn & ", we DON'T loop and we obtained " & newrtn

    ' Running this script should log the following:

    ' ---------------------------------------------

    'INFO : " --- Object Navigation ---"

    'INFO : "From sphere, we obtained Scene_Root"

    'INFO : "From sphere, we obtained sphere.Name"

    'INFO : "--- Cluster Navigation ---"

    'INFO : "From sphere.polymsh.cls.Point, we obtained sphere.polymsh.cls.Point1"

    'INFO : "We have now reached the end of the cluster list."

    'INFO : "From sphere.polymsh.cls.Point1, we loop and we obtained sphere.polymsh.cls.Point"

    'INFO : "From sphere.polymsh.cls.Point1, we DON'T loop and we obtained sphere.polymsh.cls.Point1"

### See Also

SelectNeighborObj