## 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