Class SoSearchAction
- java.lang.Object
-
- com.openinventor.inventor.Inventor
-
- com.openinventor.inventor.actions.SoAction
-
- com.openinventor.inventor.actions.SoSearchAction
-
- Direct Known Subclasses:
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 sameSoSearchAction
object to do a search by type (setType()
), the action will actually search for a node that satisfies both criteria. To avoid this problem, callreset()
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 anSoSwitch
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:
Efficiency:SoSearchAction
creates one or moreSoPath
objects when applied to the scene graph. TheSoPath
object references each node in the path. This reference will prevent the node and its associated memory from being reclaimed for as long as theSoPath
object exists. TheseSoPath
objects are stored internally in the action and exist until the action object itself is reclaimed or reset.
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 anSoPath
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 usingSoCallbackAction
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. UsingSoCallbackAction
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 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 inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle
-
-
Constructor Summary
Constructors Constructor Description SoSearchAction()
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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, forwardTraversal, getContinueActionInBranchFlag, getCurPath, getDistribMode, 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, getNativeResourceHandle
-
-
-
-
Method Detail
-
setNodeClass
public void setNodeClass(java.lang.Class<? extends Inventor> t)
Calls setNodeClass(t, true).
-
getFind
public int getFind()
Returns what to look for.
-
setNode
public void setNode(SoNode n)
Sets the node to search for.
-
addPath
public void addPath(SoPath path)
-
getNode
public SoNode getNode()
Returns the node 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.
-
isSearchingExtendedClass
public boolean isSearchingExtendedClass()
Returns the node type to search for.
-
isSearchingAll
public boolean isSearchingAll()
Returns false if searching uses regular traversal, true if it traverses every single node. Default is false.
-
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().
-
isFound
public boolean isFound()
-
setInterest
public void setInterest(SoSearchAction.Interests i)
Sets which paths to return. Default is FIRST.
-
getInterest
public SoSearchAction.Interests getInterest()
Returns which paths to return.
-
getPaths
public java.util.Vector<SoPath> getPaths()
Returns resulting path list. This should be used if the interest is ALL.
-
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, anSoSwitch
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.
-
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.
-
setName
public void setName(java.lang.String n)
Sets the name of the node to search for.
-
setFound
public void setFound()
-
getNodeClass
public java.lang.Class<? extends Inventor> getNodeClass()
Returns the node type 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.
-
enableElement
public static void enableElement(java.lang.Class<? extends Inventor> t, int stkIndex)
-
getName
public java.lang.String getName()
Returns the name of the node to search for.
-
-