NavigateNode
 
 
 

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