.TH "SoSearchAction" 3 "Tue Dec 26 2023 17:59:22" "Version 4.0.2" "Coin" \" -*- nroff -*- .ad l .nh .SH NAME SoSearchAction \- The \fBSoSearchAction\fP class provides methods for searching through scene graphs\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .PP Inherits \fBSoAction\fP\&. .SS "Public Types" .in +1c .ti -1c .RI "enum \fBLookFor\fP { \fBNODE\fP = 1, \fBTYPE\fP = 2, \fBNAME\fP = 4 }" .br .ti -1c .RI "enum \fBInterest\fP { \fBFIRST\fP, \fBLAST\fP, \fBALL\fP }" .br .in -1c Public Types inherited from \fBSoAction\fP .in +1c .ti -1c .RI "enum \fBAppliedCode\fP { \fBNODE\fP = 0, \fBPATH\fP = 1, \fBPATH_LIST\fP = 2 }" .br .ti -1c .RI "enum \fBPathCode\fP { \fBNO_PATH\fP = 0, \fBIN_PATH\fP = 1, \fBBELOW_PATH\fP = 2, \fBOFF_PATH\fP = 3 }" .br .in -1c .SS "Public Member Functions" .in +1c .ti -1c .RI "\fBvirtual\fP \fBSoType\fP \fBgetTypeId\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBSoSearchAction\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvirtual\fP \fB~SoSearchAction\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvoid\fP \fBsetNode\fP (\fBSoNode\fP *\fBconst\fP node)" .br .ti -1c .RI "\fBSoNode\fP * \fBgetNode\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetType\fP (\fBconst\fP \fBSoType\fP type, \fBconst\fP SbBool chkderived=TRUE)" .br .ti -1c .RI "\fBSoType\fP \fBgetType\fP (SbBool &chkderived) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetName\fP (\fBconst\fP \fBSbName\fP name)" .br .ti -1c .RI "\fBSbName\fP \fBgetName\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetFind\fP (\fBconst\fP int \fBwhat\fP)" .br .ti -1c .RI "int \fBgetFind\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetInterest\fP (\fBconst\fP \fBInterest\fP interest)" .br .ti -1c .RI "\fBInterest\fP \fBgetInterest\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBsetSearchingAll\fP (\fBconst\fP SbBool searchall)" .br .ti -1c .RI "SbBool \fBisSearchingAll\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBSoPath\fP * \fBgetPath\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBSoPathList\fP & \fBgetPaths\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvoid\fP \fBreset\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvoid\fP \fBsetFound\fP (\fBvoid\fP)" .br .ti -1c .RI "SbBool \fBisFound\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvoid\fP \fBaddPath\fP (\fBSoPath\fP *\fBconst\fP path)" .br .in -1c Public Member Functions inherited from \fBSoAction\fP .in +1c .ti -1c .RI "\fBvirtual\fP \fB~SoAction\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvirtual\fP SbBool \fBisOfType\fP (\fBSoType\fP type) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBapply\fP (\fBSoNode\fP *root)" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBapply\fP (\fBSoPath\fP *path)" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBapply\fP (\fBconst\fP \fBSoPathList\fP &\fBpathlist\fP, SbBool \fBobeysrules\fP=FALSE)" .br .ti -1c .RI "\fBvoid\fP \fBapply\fP (\fBSoAction\fP *\fBbeingApplied\fP)" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBinvalidateState\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBAppliedCode\fP \fBgetWhatAppliedTo\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBSoNode\fP * \fBgetNodeAppliedTo\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBSoPath\fP * \fBgetPathAppliedTo\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBconst\fP \fBSoPathList\fP * \fBgetPathListAppliedTo\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBconst\fP \fBSoPathList\fP * \fBgetOriginalPathListAppliedTo\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "SbBool \fBisLastPathListAppliedTo\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBPathCode\fP \fBgetPathCode\fP (int &\fBnumindices\fP, \fBconst\fP int *&indices)" .br .ti -1c .RI "\fBvoid\fP \fBtraverse\fP (\fBSoNode\fP *\fBconst\fP node)" .br .ti -1c .RI "SbBool \fBhasTerminated\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBconst\fP \fBSoPath\fP * \fBgetCurPath\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBSoState\fP * \fBgetState\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBPathCode\fP \fBgetCurPathCode\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP \fBSoNode\fP * \fBgetCurPathTail\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvoid\fP \fBusePathCode\fP (int &\fBnumindices\fP, \fBconst\fP int *&indices)" .br .ti -1c .RI "\fBvoid\fP \fBpushCurPath\fP (\fBconst\fP int \fBchildindex\fP, \fBSoNode\fP *node=\fBNULL\fP)" .br .ti -1c .RI "\fBvoid\fP \fBpopCurPath\fP (\fBconst\fP \fBPathCode\fP \fBprevpathcode\fP)" .br .ti -1c .RI "\fBvoid\fP \fBpushCurPath\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvoid\fP \fBpopPushCurPath\fP (\fBconst\fP int \fBchildindex\fP, \fBSoNode\fP *node=\fBNULL\fP)" .br .ti -1c .RI "\fBvoid\fP \fBpopCurPath\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvoid\fP \fBswitchToPathTraversal\fP (\fBSoPath\fP *path)" .br .ti -1c .RI "\fBvoid\fP \fBswitchToNodeTraversal\fP (\fBSoNode\fP *node)" .br .in -1c .SS "Static Public Member Functions" .in +1c .ti -1c .RI "\fBstatic\fP \fBSoType\fP \fBgetClassTypeId\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBaddMethod\fP (\fBconst\fP \fBSoType\fP type, SoActionMethod method)" .br .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBenableElement\fP (\fBconst\fP \fBSoType\fP type, \fBconst\fP int \fBstackindex\fP)" .br .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBinitClass\fP (\fBvoid\fP)" .br .in -1c Static Public Member Functions inherited from \fBSoAction\fP .in +1c .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBinitClass\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBinitClasses\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBSoType\fP \fBgetClassTypeId\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBvoid\fP \fBnullAction\fP (\fBSoAction\fP *action, \fBSoNode\fP *node)" .br .in -1c .SS "Static Public Attributes" .in +1c .ti -1c .RI "\fBstatic\fP SbBool \fBduringSearchAll\fP = FALSE" .br .in -1c .SS "Protected Member Functions" .in +1c .ti -1c .RI "\fBvirtual\fP \fBconst\fP \fBSoEnabledElementsList\fP & \fBgetEnabledElements\fP (\fBvoid\fP) \fBconst\fP" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBbeginTraversal\fP (\fBSoNode\fP *node)" .br .in -1c Protected Member Functions inherited from \fBSoAction\fP .in +1c .ti -1c .RI "\fBSoAction\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBvirtual\fP \fBvoid\fP \fBendTraversal\fP (\fBSoNode\fP *node)" .br .ti -1c .RI "\fBvoid\fP \fBsetTerminated\fP (\fBconst\fP SbBool \fBflag\fP)" .br .ti -1c .RI "\fBvirtual\fP SbBool \fBshouldCompactPathList\fP (\fBvoid\fP) \fBconst\fP" .br .in -1c .SS "Static Protected Member Functions" .in +1c .ti -1c .RI "\fBstatic\fP \fBSoEnabledElementsList\fP * \fBgetClassEnabledElements\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBSoActionMethodList\fP * \fBgetClassActionMethods\fP (\fBvoid\fP)" .br .in -1c Static Protected Member Functions inherited from \fBSoAction\fP .in +1c .ti -1c .RI "\fBstatic\fP \fBSoEnabledElementsList\fP * \fBgetClassEnabledElements\fP (\fBvoid\fP)" .br .ti -1c .RI "\fBstatic\fP \fBSoActionMethodList\fP * \fBgetClassActionMethods\fP (\fBvoid\fP)" .br .in -1c .SS "Additional Inherited Members" Protected Attributes inherited from \fBSoAction\fP .in +1c .ti -1c .RI "\fBSoState\fP * \fBstate\fP" .br .ti -1c .RI "\fBSoActionMethodList\fP * \fBtraversalMethods\fP" .br .in -1c .SH "Detailed Description" .PP The \fBSoSearchAction\fP class provides methods for searching through scene graphs\&. Nodes can be searched for by pointer, type, and name, or a combination of those criteria\&. Types can be interpreted as exact types, or the type can match nodes derived from it\&. Every single node can be searched, or normal traversal rules can be followed when searching (this is especially important to note with regard to switch nodes)\&. .PP When using more than one of the \fBsetNode()\fP, \fBsetType()\fP and \fBsetName()\fP calls, note that the action will search for node(s) with an \fC'AND'\fP combination of the given search criteria\&. .PP One of the most common pitfalls when using the \fBSoSearchAction\fP class is to call the function \fBisFound()\fP after doing a search\&. It does not return what you would expect it to return if you haven't read the documentation for that function\&. .PP Be aware that if you do search operations on an \fBSoSearchAction\fP created on the stack, you can get some unfortunate side effects if you're not careful\&. Since \fBSoSearchAction\fP keeps a list of the path(s) found in the latest search, the nodes in these paths will be unref'ed when the \fBSoSearchAction\fP stack instance is destructed at the end of your function\&. If the root of your scene graph then has ref-count zero (it is often useful to do a unrefNoDelete() before returning a node from a function to leave the referencing to the caller), the root node will be destructed! It might be better to create a heap instance of the search action in those cases, since you'll then be able to destruct the search action before calling unrefNoDelete()\&. Another solution would be to call \fBreset()\fP before calling unrefNoDelete() on your object, since \fBreset()\fP truncates the path list\&. .PP See the documentation of \fBSoTexture2\fP for a full usage example of \fBSoSearchAction\fP\&. .SH "Member Enumeration Documentation" .PP .SS "\fBenum\fP \fBSoSearchAction::LookFor\fP" Specify the search criterion\&. This can be a bitwise combination of the available values\&. .PP \fBEnumerator\fP .in +1c .TP \fB\fINODE \fP\fP Search for a node by pointer\&. .TP \fB\fITYPE \fP\fP Search for a node by type\&. .TP \fB\fINAME \fP\fP Search for a node by name\&. .SS "\fBenum\fP \fBSoSearchAction::Interest\fP" Values used when specifying what node(s) we are interested in: the first one found, the last one or all of them\&. .PP \fBEnumerator\fP .in +1c .TP \fB\fIFIRST \fP\fP Return the path to the first node found\&. .TP \fB\fILAST \fP\fP Return the path to the last node found\&. .TP \fB\fIALL \fP\fP Return paths to all nodes found\&. .SH "Constructor & Destructor Documentation" .PP .SS "SoSearchAction::SoSearchAction (\fBvoid\fP)" Initializes internal settings with default values\&. With the default settings, the \fBSoSearchAction\fP will ignore all nodes\&. .SS "SoSearchAction::~SoSearchAction (\fBvoid\fP)\fC [virtual]\fP" Destructor\&. .SH "Member Function Documentation" .PP .SS "\fBSoType\fP SoSearchAction::getTypeId (\fBvoid\fP) const\fC [virtual]\fP" Returns the type identification of an object derived from a class inheriting \fBSoAction\fP\&. This is used for runtime type checking and 'downward' casting\&. .br .PP Implements \fBSoAction\fP\&. .SS "\fBSoType\fP SoSearchAction::getClassTypeId (\fBvoid\fP)\fC [static]\fP" This static method returns the \fBSoType\fP object associated with objects of this class\&. .br .SS "\fBvoid\fP SoSearchAction::addMethod (\fBconst\fP \fBSoType\fP type, SoActionMethod method)\fC [static]\fP" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .br .br .SS "\fBvoid\fP SoSearchAction::enableElement (\fBconst\fP \fBSoType\fP type, \fBconst\fP int stackindex)\fC [static]\fP" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .br .br .SS "\fBconst\fP \fBSoEnabledElementsList\fP & SoSearchAction::getEnabledElements (\fBvoid\fP) const\fC [protected]\fP, \fC [virtual]\fP" Returns list of enabled elements\&. .br .PP Reimplemented from \fBSoAction\fP\&. .SS "\fBSoEnabledElementsList\fP * SoSearchAction::getClassEnabledElements (\fBvoid\fP)\fC [static]\fP, \fC [protected]\fP" Returns list of enabled elements for this class\&. The enabledElements and methods variables are protected in the original OIV API\&. This is not such a good idea, since exposed static class member variables is a major grievance with regard to Win32 DLLs\&. This function is an extension for Coin, and it is not available in the original SGI Open Inventor \fBv2\&.1\fP API\&. .br .br .SS "\fBSoActionMethodList\fP * SoSearchAction::getClassActionMethods (\fBvoid\fP)\fC [static]\fP, \fC [protected]\fP" Returns list of action methods for this class\&. The enabledElements and methods variables are protected in the original OIV API\&. This is not such a good idea, since exposed static class member variables is a major grievance with regard to Win32 DLLs\&. This function is an extension for Coin, and it is not available in the original SGI Open Inventor \fBv2\&.1\fP API\&. .br .br .SS "\fBvoid\fP SoSearchAction::initClass (\fBvoid\fP)\fC [static]\fP" Initializes the runtime type system for this class, and sets up the enabled elements and action method list\&. .SS "\fBvoid\fP SoSearchAction::setNode (\fBSoNode\fP *\fBconst\fP nodeptr)" Sets the \fInode\fP pointer to search for\&. .PP The action will be configured to set the search 'interest' to LookFor \fCNODE\fP, so there is no need to call \fBSoSearchAction::setFind()\fP\&. .SS "\fBSoNode\fP * SoSearchAction::getNode (\fBvoid\fP) const" Returns the node the \fBSoSearchAction\fP instance is configured to search for\&. .PP Note that this method does not return what was found when you applied the action - it only returns what was specifically set by the user with \fBsetNode()\fP\&. What the action found is returned by \fBgetPath()\fP and \fBgetPaths()\fP\&. .SS "\fBvoid\fP SoSearchAction::setType (\fBconst\fP \fBSoType\fP typearg, \fBconst\fP SbBool chkderivedarg = \fCTRUE\fP)" Configures the \fBSoSearchAction\fP instance to search for nodes of the given \fItype\fP, and nodes of classes derived from the given \fItype\fP if \fIchkderived\fP is \fCTRUE\fP\&. .PP The action will be configured to set the search 'interest' to LookFor \fCTYPE\fP, so there is no need to call \fBSoSearchAction::setFind()\fP\&. .SS "\fBSoType\fP SoSearchAction::getType (SbBool & chkderivedref) const" Returns the node type which is searched for, and whether derived classes of that type also returns a match\&. .SS "\fBvoid\fP SoSearchAction::setName (\fBconst\fP \fBSbName\fP namearg)" Configures the \fBSoSearchAction\fP instance to search for nodes with the given \fIname\fP\&. .PP The action will be configured to set the search 'interest' to LookFor \fCNAME\fP, so there is no need to call \fBSoSearchAction::setFind()\fP\&. .PP \fBSee also\fP .RS 4 \fBSoNode::getByName()\fP .RE .PP .SS "\fBSbName\fP SoSearchAction::getName (\fBvoid\fP) const" Returns the name the \fBSoSearchAction\fP instance is configured to search for\&. .SS "\fBvoid\fP SoSearchAction::setFind (\fBconst\fP int what)" Configures what to search for in the scene graph\&. \fIwhat\fP is a bitmask of LookFor flags\&. .PP Default find configuration is to ignore all nodes, but the \fBsetFind()\fP configuration is updated automatically when any one of \fBSoSearchAction::setNode()\fP, \fBSoSearchAction::setType()\fP or \fBSoSearchAction::setName()\fP is called\&. .SS "int SoSearchAction::getFind (\fBvoid\fP) const" Returns the search configuration of the action instance\&. .SS "\fBvoid\fP SoSearchAction::setInterest (\fBconst\fP \fBInterest\fP interestarg)" Configures whether only the first, the last, or all the searching matches are of interest\&. Default configuration is \fCFIRST\fP\&. .SS "\fBSoSearchAction::Interest\fP SoSearchAction::getInterest (\fBvoid\fP) const" Returns whether only the first, the last, or all the searching matches will be saved\&. .SS "\fBvoid\fP SoSearchAction::setSearchingAll (\fBconst\fP SbBool searchallarg)" Specifies whether normal graph traversal should be done (\fIsearchall\fP is \fCFALSE\fP, which is the default setting), or if every single node should be searched (\fIsearchall\fP is \fCTRUE\fP)\&. .PP If the \fIsearchall\fP flag is \fCTRUE\fP, even nodes considered 'hidden' by other actions are searched (like for instance the disabled children of \fBSoSwitch\fP nodes)\&. .PP \fBSoBaseKit::setSearchingChildren()\fP must be used to search for nodes under node kits\&. .SS "SbBool SoSearchAction::isSearchingAll (\fBvoid\fP) const" Returns the traversal method configuration of the action\&. .SS "\fBSoPath\fP * SoSearchAction::getPath (\fBvoid\fP) const" Returns the path to the node of interest that matched the search criterions\&. If no match was found, \fCNULL\fP is returned\&. .PP Note that if \fCALL\fP matches are of interest, the result of a search action must be fetched through \fBSoSearchAction::getPaths()\fP\&. .PP There is one frequently asked question about the paths that are returned from either this method or the \fBgetPaths()\fP method below: 'why am I not getting the complete path as expected?' .PP Well, then you probably have to cast the path to a \fBSoFullPath\fP, since certain nodes (nodekits, many VRML97 nodes) have hidden children\&. \fBSoPath::getTail()\fP will return the first node that has hidden children, or the tail if none of the nodes have hidden children\&. \fBSoFullPath::getTail()\fP will always return the actual tail\&. Just do like this: .PP .PP .nf SoFullPath * path = (SoFullPath *) searchaction\->getPath(); SoVRMLCoordinate * vrmlcord = (SoVRMLCoordinate *) path\->getTail(); .fi .PP .SS "\fBSoPathList\fP & SoSearchAction::getPaths (\fBvoid\fP)" Returns a path list of all nodes that matched the search criterions\&. .PP Note that if interest were only \fCFIRST\fP or \fCLAST\fP, \fBSoSearchAction::getPath()\fP should be used instead of this method\&. .PP \fBSee also\fP .RS 4 \fBgetPath()\fP .RE .PP .SS "\fBvoid\fP SoSearchAction::reset (\fBvoid\fP)" Resets all the \fBSoSearchAction\fP internals back to their default values\&. .SS "\fBvoid\fP SoSearchAction::setFound (\fBvoid\fP)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .br .br Marks the \fBSoSearchAction\fP instance as terminated\&. .SS "SbBool SoSearchAction::isFound (\fBvoid\fP) const" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .br .br Returns whether the search action was terminated\&. .PP Note that this value does not reflect whether the node(s) that was searched for was found or not\&. Use the result of \fBgetPath()\fP / \fBgetPaths()\fP if that is what you really are looking for\&. .SS "\fBvoid\fP SoSearchAction::addPath (\fBSoPath\fP *\fBconst\fP pathptr)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .br .br Sets the path, or adds the path to the path list, depending on the interest configuration\&. The path is not copied, so it cannot be modified after being added without side effects\&. .SS "\fBvoid\fP SoSearchAction::beginTraversal (\fBSoNode\fP * node)\fC [protected]\fP, \fC [virtual]\fP" This virtual method is called from \fBSoAction::apply()\fP, and is the entry point for the actual scene graph traversal\&. .PP It can be overridden to initialize the action at traversal start, for specific initializations in the action subclasses inheriting \fBSoAction\fP\&. .PP Default method just calls \fBtraverse()\fP, which any overridden implementation of the method must do too (or call \fBSoAction::beginTraversal()\fP) to trigger the scene graph traversal\&. .PP Reimplemented from \fBSoAction\fP\&. .SH "Member Data Documentation" .PP .SS "SbBool SoSearchAction::duringSearchAll = FALSE\fC [static]\fP" Obsoleted global flag, only present for compatibility reasons with old SGI / TGS Inventor application code\&. .PP It's set to \fCTRUE\fP when an \fBSoSearchAction\fP traversal with \fBSoSearchAction::isSearchingAll()\fP equal to \fCTRUE\fP is started, and is reset to \fCFALSE\fP again after traversal has finished\&. .PP (The flag is used by SGI / TGS Inventor in \fBSoSwitch::affectsState()\fP to know when \fBSoSwitch::whichChild\fP should behave as SoSwitch::SO_SWITCH_ALL\&. We have a better solution for this problem in Coin\&.) .SH "Author" .PP Generated automatically by Doxygen for Coin from the source code\&.