com.openinventor.inventor.actions

Class SoSearchAction

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.actions.SoAction

com.openinventor.inventor.actions.SoSearchAction

Direct Known Subclasses:

SoSearchDepthOffsetAction, SoSearchPathAction, SoSearchStepAction

public class SoSearchAction
extends SoAction

Searches for nodes in a scene graph. This class is used to search scene graphs for specific nodes, nodes of a specific type, nodes with a specific name, or any combination of these. It can search for just the first or last node satisfying the criteria or for all such nodes. The action returns a path (SoPath) to each node found. The searched for node is the "tail" of each path.

Note that the search criteria are cumulative. For example, if you do a search by name (setName()), then reuse the same SoSearchAction object to do a search by type (setType()), the action will actually search for a node that satisfies both criteria. To avoid this problem, call reset() before reusing the action object.

By default SoSearchAction only searches nodes that are actually traversed. For example it would not search all the children of an SoSwitch node unless the whichChild field is set to SO_SWITCH_ALL. To search all nodes in the scene graph (except nodekits - see next paragraph) call setSearchingAll(true).

Nodekits:

• By default SoSearchAction will not search inside nodekits even when setSearchingAll is true. This is because nodekits try to keep their children hidden. To allow searching inside nodekits call the static method SoBaseKit.setSearchingChildren(true).
  
• A common problem is that when the searched for node is found inside a nodekit, the SoPath method regular.getTail() does not return the found node. This is also because nodekits try to keep their children hidden. To avoid this problem use full.getTail() instead. Hidden references:

  SoSearchAction creates one or more SoPath objects when applied to the scene graph. The SoPath object references each node in the path. This reference will prevent the node and its associated memory from being reclaimed for as long as the SoPath object exists. These SoPath objects are stored internally in the action and exist until the action object itself is reclaimed or reset. Efficiency:

  SoSearchAction is convenient for finding one or many nodes in the scene graph. However it may be an inefficient solution for finding a large number of nodes because it uses CPU time and memory to create an SoPath for every node found. If you expect to find many nodes, especially if you just need the node object and not a path, then you should consider using SoCallbackAction instead.

  For example, if you want to count all the shape nodes in the scene graph, you could use an SoSearchAction similar to the second example below. The number of shapes would conveniently be the number of paths created by the action, but you wouldn't actually make any use of the path information. Using SoCallbackAction would be a little more work, because you have to implement a counter in a callback class. But it would be much more efficient because the action simply calls your callback when each shape node is visited during the traversal. EXAMPLE

Example 1: Given an instance of a node, create a path to the location of that node in the scene graph:

 SoSearchAction sa = new SoSearchAction();
     sa.setNode( cone );
     sa.setSearchingAll( true );              // Optional: Search all nodes
     SoBaseKit.setSearchingChildren( true );  // Optional: Search inside nodekits
     sa.apply( root );
     SoPath path = sa.getPath();
     if (path != null) {
         SoNode node = path.regular.getTail();
     }

Example 2: Find all the SoFont nodes in the scene graph:

 SoSearchAction sa = new SoSearchAction();
   sa.setNodeClass( SoFont.class );
   sa.setInterest( SoSearchAction.Interests.ALL );   // Find ALL instances
   sa.setSearchingAll( true );              // Optional: Search all nodes
   SoBaseKit.setSearchingChildren( true );  // Optional: Search inside nodekits
   sa.apply( rootNode );
   java.util.Vector<SoPath> pathList = sa.getPaths();
   if (! pathList.isEmpty()) {
       SoPath path = pathList.get( 0 );
       SoFont fontNode = (SoFont)path.regular.getTail();
   }

See also:

SoPath, SoBaseKit, SoSearchPathAction, SoSearchStepAction

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoSearchAction.Interests Enum that defines which paths to return.
static class	SoSearchAction.LookFors Enum that defines the search criterion.

Nested classes/interfaces inherited from class com.openinventor.inventor.actions.SoAction

SoAction.AppliedCodes, SoAction.DistribModes, SoAction.PathCodes, SoAction.PathIndices

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALL Deprecated. Use SoSearchAction.Interests.ALL instead.
static int	FIRST Deprecated. Use SoSearchAction.Interests.FIRST instead.
static int	LAST Deprecated. Use SoSearchAction.Interests.LAST instead.
static int	NAME Deprecated. Use SoSearchAction.LookFors.NAME instead.
static int	NODE Deprecated. Use SoSearchAction.LookFors.NODE instead.
static int	TYPE Deprecated. Use SoSearchAction.LookFors.TYPE instead.

Fields inherited from class com.openinventor.inventor.actions.SoAction

BELOW_PATH, CLUSTER_ONLY, IN_PATH, LOCAL_ONLY, NO_PATH, OFF_PATH, PATH, PATH_LIST

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoSearchAction() Constructor.

Method Summary

Modifier and Type	Method and Description
void	addPath(SoPath path)
static void	enableElement(java.lang.Class<? extends Inventor> t, int stkIndex)
int	getFind() Returns what to look for.
SoSearchAction.Interests	getInterest() Returns which paths to return.
java.lang.String	getName() Returns the name of the node to search for.
SoNode	getNode() Returns the node to search for.
java.lang.Class<? extends Inventor>	getNodeClass() Returns the node type to search for.
SoPath	getPath() Returns resulting path, or NULL if no path was found.
java.util.Vector<SoPath>	getPaths() Returns resulting path list.
boolean	isFound()
boolean	isSearchingAll() Returns false if searching uses regular traversal, true if it traverses every single node.
boolean	isSearchingExtendedClass() Returns the node type to search for.
void	reset() Resets options back to default values; clears list of returned paths.
void	setFind(int what) Sets what to look for; what is a bitmask of LookFor enum values.
void	setFound()
void	setInterest(SoSearchAction.Interests i) Sets which paths to return.
void	setName(java.lang.String n) Sets the name of the node to search for.
void	setNode(SoNode n) Sets the node to search for.
void	setNodeClass(java.lang.Class<? extends Inventor> t) Calls setNodeClass(t, true).
void	setNodeClass(java.lang.Class<? extends Inventor> t, boolean derivedIsOk) Sets the node type to search for.
void	setSearchingAll(boolean flag) Sets whether searching uses regular traversal or whether it traverses every single node.

Methods inherited from class com.openinventor.inventor.actions.SoAction

apply, apply, clearApplyResult, forwardTraversal, getContinueActionInBranchFlag, getCurPath, getNodeAppliedTo, getOriginalPathListAppliedTo, getPathAppliedTo, getPathCode, getPathListAppliedTo, getPipeId, getSceneManager, getState, getWhatAppliedTo, hasTerminated, invalidateState, isBeingApplied, isLastPathListAppliedTo, isUsingAlternateRep, nullAction, postDelayedTraversal, preDelayedTraversal, resetContinueActionInBranchFlag, setPipeId, setSceneManager, setUpState, stopActionInBranch, traverse, useAlternateRep

Methods inherited from class com.openinventor.inventor.Inventor

dispose, getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NODE

@Deprecated
public static final int NODE

Deprecated. Use SoSearchAction.LookFors.NODE instead.

TYPE

@Deprecated
public static final int TYPE

Deprecated. Use SoSearchAction.LookFors.TYPE instead.

NAME

@Deprecated
public static final int NAME

Deprecated. Use SoSearchAction.LookFors.NAME instead.

FIRST

@Deprecated
public static final int FIRST

Deprecated. Use SoSearchAction.Interests.FIRST instead.

LAST

@Deprecated
public static final int LAST

Deprecated. Use SoSearchAction.Interests.LAST instead.

ALL

@Deprecated
public static final int ALL

Deprecated. Use SoSearchAction.Interests.ALL instead.

Constructor Detail

SoSearchAction

public SoSearchAction()

Constructor.

Method Detail

setNodeClass

public void setNodeClass(java.lang.Class<? extends Inventor> t)

Calls setNodeClass(t, true).

isSearchingAll

public boolean isSearchingAll()

Returns false if searching uses regular traversal, true if it traverses every single node. Default is false.

getName

public java.lang.String getName()

Returns the name of the node to search for.

setNodeClass

public void setNodeClass(java.lang.Class<? extends Inventor> t,
                         boolean derivedIsOk)

Sets the node type to search for. If derivedIsOk is true, a node that is of a type that is derived from t will pass this search criterion.

reset

public void reset()

Resets options back to default values; clears list of returned paths. This can be used to apply the action again with a different set of search criteria. See also clearApplyResult().

setSearchingAll

public void setSearchingAll(boolean flag)

Sets whether searching uses regular traversal or whether it traverses every single node. For example, if this flag is false, an SoSwitch node will traverse only the child or children it would normally traverse for an action. If the flag is true, the switch would always traverse all of its children. The default is false.

setName

public void setName(java.lang.String n)

Sets the name of the node to search for.

getInterest

public SoSearchAction.Interests getInterest()

Returns which paths to return.

isSearchingExtendedClass

public boolean isSearchingExtendedClass()

Returns the node type to search for.

setInterest

public void setInterest(SoSearchAction.Interests i)

Sets which paths to return. Default is FIRST.

addPath

public void addPath(SoPath path)

enableElement

public static void enableElement(java.lang.Class<? extends Inventor> t,
                                 int stkIndex)

getFind

public int getFind()

Returns what to look for.

setNode

public void setNode(SoNode n)

Sets the node to search for.

getPaths

public java.util.Vector<SoPath> getPaths()

Returns resulting path list. This should be used if the interest is ALL.

getNode

public SoNode getNode()

Returns the node to search for.

isFound

public boolean isFound()

getNodeClass

public java.lang.Class<? extends Inventor> getNodeClass()

Returns the node type to search for.

setFind

public void setFind(int what)

Sets what to look for; what is a bitmask of LookFor enum values. Default is no flags at all. Note that setting a node, type, and/or name to search for activates the relevant flag, so you may never need to call this method directly.

getPath

public SoPath getPath()

Returns resulting path, or NULL if no path was found. This should be used if the interest is FIRST or LAST.

setFound

public void setFound()