.TH "SoSearchAction" 3 "Thu May 29 2014" "Version 4.0.0a" "Coin" \" -*- nroff -*-
.ad l
.nh
.SH NAME
SoSearchAction \- 
.PP
The \fBSoSearchAction\fP class provides methods for searching through scene graphs\&.
.PP
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)\&.  

.SH SYNOPSIS
.br
.PP
.PP
\fC#include <Inventor/actions/SoSearchAction\&.h>\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
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "virtual \fBSoType\fP \fBgetTypeId\fP (void) const "
.br
.ti -1c
.RI "\fBSoSearchAction\fP (void)"
.br
.ti -1c
.RI "virtual \fB~SoSearchAction\fP (void)"
.br
.ti -1c
.RI "void \fBsetNode\fP (\fBSoNode\fP *const node)"
.br
.ti -1c
.RI "\fBSoNode\fP * \fBgetNode\fP (void) const "
.br
.ti -1c
.RI "void \fBsetType\fP (const \fBSoType\fP type, const SbBool chkderived=TRUE)"
.br
.ti -1c
.RI "\fBSoType\fP \fBgetType\fP (SbBool &chkderived) const "
.br
.ti -1c
.RI "void \fBsetName\fP (const \fBSbName\fP name)"
.br
.ti -1c
.RI "\fBSbName\fP \fBgetName\fP (void) const "
.br
.ti -1c
.RI "void \fBsetFind\fP (const int what)"
.br
.ti -1c
.RI "int \fBgetFind\fP (void) const "
.br
.ti -1c
.RI "void \fBsetInterest\fP (const \fBInterest\fP interest)"
.br
.ti -1c
.RI "\fBInterest\fP \fBgetInterest\fP (void) const "
.br
.ti -1c
.RI "void \fBsetSearchingAll\fP (const SbBool searchall)"
.br
.ti -1c
.RI "SbBool \fBisSearchingAll\fP (void) const "
.br
.ti -1c
.RI "\fBSoPath\fP * \fBgetPath\fP (void) const "
.br
.ti -1c
.RI "\fBSoPathList\fP & \fBgetPaths\fP (void)"
.br
.ti -1c
.RI "void \fBreset\fP (void)"
.br
.ti -1c
.RI "void \fBsetFound\fP (void)"
.br
.ti -1c
.RI "SbBool \fBisFound\fP (void) const "
.br
.ti -1c
.RI "void \fBaddPath\fP (\fBSoPath\fP *const path)"
.br
.in -1c
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "static \fBSoType\fP \fBgetClassTypeId\fP (void)"
.br
.ti -1c
.RI "static void \fBaddMethod\fP (const \fBSoType\fP type, SoActionMethod method)"
.br
.ti -1c
.RI "static void \fBenableElement\fP (const \fBSoType\fP type, const int stackindex)"
.br
.ti -1c
.RI "static void \fBinitClass\fP (void)"
.br
.in -1c
.SS "Static Public Attributes"

.in +1c
.ti -1c
.RI "static SbBool \fBduringSearchAll\fP = FALSE"
.br
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "virtual const 
.br
\fBSoEnabledElementsList\fP & \fBgetEnabledElements\fP (void) const "
.br
.ti -1c
.RI "virtual void \fBbeginTraversal\fP (\fBSoNode\fP *node)"
.br
.in -1c
.SS "Static Protected Member Functions"

.in +1c
.ti -1c
.RI "static \fBSoEnabledElementsList\fP * \fBgetClassEnabledElements\fP (void)"
.br
.ti -1c
.RI "static \fBSoActionMethodList\fP * \fBgetClassActionMethods\fP (void)"
.br
.in -1c
.SS "Additional Inherited Members"
.SH "Detailed Description"
.PP 
The \fBSoSearchAction\fP class provides methods for searching through scene graphs\&.
.PP
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)\&. 

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 "enum \fBSoSearchAction::LookFor\fP"
Specify the search criterion\&. This can be a bitwise combination of the available values\&. 
.SS "enum \fBSoSearchAction::Interest\fP"
Values used when specifiying what node(s) we are interested in: the first one found, the last one or all of them\&. 
.SH "Constructor & Destructor Documentation"
.PP 
.SS "SoSearchAction::SoSearchAction (void)"
Initializes internal settings with default values\&. With the default settings, the \fBSoSearchAction\fP will ignore all nodes\&. 
.SS "SoSearchAction::~SoSearchAction (void)\fC [virtual]\fP"
Destructor\&. 
.SH "Member Function Documentation"
.PP 
.SS "\fBSoType\fP SoSearchAction::getTypeId (void) const\fC [virtual]\fP"
Returns the type identification of an action derived from a class inheriting \fBSoAction\fP\&. This is used for run-time type checking and 'downward' casting\&.
.PP
Usage example:
.PP
.PP
.nf
void bar(SoAction * action)
{
  if (action->getTypeId() == SoGLRenderAction::getClassTypeId()) {
    // safe downward cast, know the type
    SoGLRenderAction * glrender = (SoGLRenderAction *)action;
  }
  return; // ignore if not renderaction
}
.fi
.PP
.PP
For application programmers wanting to extend the library with new actions: this method needs to be overridden in \fIall\fP subclasses\&. This is typically done as part of setting up the full type system for extension classes, which is usually accomplished by using the pre-defined macros available through Inventor/nodes/SoSubAction\&.h: SO_ACTION_SOURCE, SO_ACTION_INIT_CLASS and SO_ACTION_CONSTRUCTOR\&.
.PP
For more information on writing Coin extensions, see the \fBSoAction\fP class documentation\&.
.PP
Returns the actual type id of an object derived from a class inheriting \fBSoAction\fP\&. Needs to be overridden in \fIall\fP subclasses\&. 
.PP
Implements \fBSoAction\fP\&.
.SS "void SoSearchAction::addMethod (const \fBSoType\fPtype, SoActionMethodmethod)\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 
.SS "void SoSearchAction::enableElement (const \fBSoType\fPtype, const intstackindex)\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 
.SS "const \fBSoEnabledElementsList\fP & SoSearchAction::getEnabledElements (void) const\fC [protected]\fP, \fC [virtual]\fP"
Returns a list of the elements used by action instances of this class upon traversal operations\&. 
.PP
Reimplemented from \fBSoAction\fP\&.
.SS "void SoSearchAction::setNode (\fBSoNode\fP *constnodeptr)"
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 (void) 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 "void SoSearchAction::setType (const \fBSoType\fPtypearg, const SbBoolchkderivedarg = \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 "void SoSearchAction::setName (const \fBSbName\fPnamearg)"
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 (void) const"
Returns the name the \fBSoSearchAction\fP instance is configured to search for\&. 
.SS "void SoSearchAction::setFind (const intwhat)"
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 (void) const"
Returns the search configuration of the action instance\&. 
.SS "void SoSearchAction::setInterest (const \fBInterest\fPinterestarg)"
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 (void) const"
Returns whether only the first, the last, or all the searching matches will be saved\&. 
.SS "void SoSearchAction::setSearchingAll (const SbBoolsearchallarg)"
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 (void) const"
Returns the traversal method configuration of the action\&. 
.SS "\fBSoPath\fP * SoSearchAction::getPath (void) 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 (void)"
Returns a pathlist 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 "void SoSearchAction::reset (void)"
Resets all the \fBSoSearchAction\fP internals back to their default values\&. 
.SS "void SoSearchAction::setFound (void)"
\fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP
.PP
Marks the \fBSoSearchAction\fP instance as terminated\&. 
.SS "SbBool SoSearchAction::isFound (void) const"
\fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP
.PP
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 "void SoSearchAction::addPath (\fBSoPath\fP *constpathptr)"
\fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP
.PP
Sets the path, or adds the path to the path list, depending on the interest configuration\&. The path is not copied, so it can not be modified after being added without side effects\&. 
.SS "void 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 scenegraph 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 scenegraph 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\&.