Searching for a Node

SoSearchAction searches through the scene graph for paths to specific nodes, types of nodes, or nodes with a given name. First, you initialize the action. Then, you specify the node, node type, or name to search for (or a combination of these elements). If you specify a node type, you can also specify whether to search for an exact type match, or to search for subclasses of the specified type as well.

Specify the Search Criteria

First, specify what you are searching for, whether you want to find all matches, and how to traverse the scene graph.

Searching for a Node

If you want to search for a particular node (by pointer), use the setNode() method. For example, you might use setNode() to search for a particular light-source node so that you can attach an editor to it.

Searching for a Node Type

Rather than searching for a specific node, you may want to search for a type of node (see Nodes and Groups). When searching for a node type, you then have the choice of searching for all nodes of a particular type, or for derivations of the given type (the default). The syntax for setType() is as follows:

setType (SoType t , int derivedIsOk = TRUE);

Searching for a Name

Use the setName() method to specify the name of the node to search for. (See Nodes and Groups for more information on naming.)

Specify Whether to Find All Matches

Use the setInterest() method to specify which paths to return:

FIRST	returns only the first path found (the default)
LAST	returns only the last path found
ALL	returns all paths found

Specify the Type of Traversal

Use the setSearchingAll() method to specify whether to search using normal traversal (following traversal order for switches and separators) or to search every node in the scene graph, regardless of switch settings. The default is FALSE (search using normal traversal order).

Apply the Action

SoSearchAction is applied in the same manner as any other action.

Obtain the Results

To obtain the results of the search, use one of the following methods:

getPath()	returns the found path (if interest is FIRST or LAST)
getPaths()	returns the found path list (if interest is ALL)

See the Open Inventor C++ Reference Manual for a complete description of all methods available for SoSearchAction.

The following example searches a scene graph for any node derived from SoLight. If it does not find one, it creates and adds an SoDirectionalLight. This example searches for only the first match by calling setInterest- **(SoSearchAction::FIRST)**.

C++ :

SoSearchAction mySearchAction;
 
// Look for first existing light derived from class SoLight
mySearchAction.setType( SoLight::getClassTypeId() );
mySearchAction.setInterest( SoSearchAction::FIRST );
 
mySearchAction.apply( root );
if ( mySearchAction.getPath() == NULL )
{ // No lights found
 
  // Add a default directional light to the scene
  SoDirectionalLight* myLight = new SoDirectionalLight;
  root->insertChild( myLight, 0 );
}

C# :

SoSearchAction mySearchAction = new SoSearchAction();
 
// Look for first existing light derived from class SoLight
mySearchAction.SetType( Type.GetType( "SoLight" ) );
mySearchAction.SetInterest( SoSearchAction.Interests.FIRST );
 
mySearchAction.Apply( root );
if ( mySearchAction.GetPath() == null ) // No lights found
{
  // Add a default directional light to the scene
  SoDirectionalLight myLight = new SoDirectionalLight();
  root.InsertChild( myLight, 0 );
}

Java :

SoSearchAction mySearchAction = new SoSearchAction();
 
// Look for first existing light derived from class SoLight
mySearchAction.setNodeClass( SoLight.class );
mySearchAction.setInterest( SoSearchAction.Interests.FIRST );
 
mySearchAction.apply( root );
if ( mySearchAction.getPath() == null ) // No lights found
{
  // Add a default directional light to the scene
  SoDirectionalLight myLight = new SoDirectionalLight();
  root.insertChild( myLight, 0 );
}