SoBaseKit — base class for all node kits

SoGLRenderAction,SoCallbackAction,SoGetBoundingBoxAction,SoHandleEventAction
          Behaves like an SoGroup. Traverses each child in order.

     SoRayPickAction
          Traverses  each  child  in  order.  Then,  for  any  pick  containing  the  kit  on its path, makes an
          SoNodeKitDetail as follows: Sets the "detailNodeKit" (retrievable with  SoNodeKitDetail::getNodeKit())
          to be a pointer to itself. Sets the "detailPart" (retrievable with SoNodeKitDetail::getPart()) to be a
          pointer  to the kit's leaf-most part that lies on the pickPath. Sets the "detailPartName" (retrievable
          with SoNodeKitDetail::getPartName()) to be the partName of that part, as found in the catalog.

          Does not descend into nested nodekits. Each nodekit along the path is the "detailPart" in its parent's
          detail. However, if the pick path goes through a list part, a pointer to the child  is  used  for  the
          "detailPart", and "detailPartName" is of the form "listName[i]".

     SoGetMatrixAction
          Behaves  like an SoGroup. Does nothing unless the kit is in the middle of the path chain the action is
          being applied to. If so, the children up to and including the next node in the chain are traversed.

     SoSearchAction
          First, searches itself like an SoNode. Then, checks  the  value  of  isSearchingChildren().  If  TRUE,
          traverses the children in order. If FALSE, returns.

     SoWriteAction
          Begins  by  writing  out  regular  fields, then writes out the parts. A nodekit does not write out its
          parts the way an SoGroup writes out its children. Instead, it writes each part as an  SoSFNode  field.
          First the partName is written, then the node being used for that part.

          To keep the files terse, nodekits write out as few parts as possible. However, nodekits always write a
          part  if  another  instance  or  a  path  is  writing  it. If this is not the case, parts are left out
          according to the following rules:

          [1] NULL parts only write if the catalog states they are created by default.

          [2] Empty SoGroup and SoSeparator nodes do not write.

          [3] Non-leaf parts only write if they have non-default field values.

          [4] List parts only write if they have children or if the container node has non-default field values.

          [5] Nested nodekit parts only write if they need to write one or more parts,  or  if  they  have  non-
          default field values.

       ┌─────────────────────────────────────────────────────────┐
       │                        Allparts                        │
       │                                                 NULLby │
       │ PartNamePartTypeDefaultTypeDefault │
       │                                                         │
       │ callbackList   NodeKitListPart   --               yes   │
       │                                                         │
       └─────────────────────────────────────────────────────────┘
       ┌────────────────────────────────────────────────────────────────┐
       │       Extrainformationforlistpartsfromabovetable        │
       │                                                                │
       │ PartNameContainerTypePermissibleTypes              │
       │                                                                │
       │ callbackList   Separator        Callback, EventCallback        │
       │                                                                │
       └────────────────────────────────────────────────────────────────┘

       This is the base class from which all nodekit nodes are derived. Nodekits provide a convenient  mechanism
       for  creating  groups of scene graph nodes with some larger meaning. When you create a shape node such as
       an indexed face set, for example, you almost always precede it with a coordinate node. You may also  want
       to  add  a  transform  node  or  specify  properties with material, drawing style, material binding, etc.
       Instead of creating each of these nodes individually and then arranging them into a subgraph, you can use
       a nodekit of the appropriate type (in this case, SoShapeKit).

       Each class of nodekit has a nodekitcatalog (SoNodekitCatalog) that describes the nodes in the  subgraph,
       referred  to  as  parts.  The  catalog has an entry for each part, with information such as the partName,
       partType, and nullByDefault (if FALSE the  constructor  creates  it).  The  catalog  also  describes  the
       arrangement of parts in the subgraph. (Other information is described below; a complete description is in
       the SoNodekitCatalog reference page.)

       If we regard the scene graph arrangement as a branching tree, then the top node (root) of the arrangement
       is  always  the  nodekit  itself.  The  leaf nodes are those at the bottom (containing no children). Some
       leaves of the tree are defined in the catalog to be public parts, while other  leaves  are  private.  All
       non-leaf  parts are considered internal to the nodekit structure and are marked private. Public parts are
       accessible; they may be requested, changed, or set by  the  programmer  with  member  functions  such  as
       getPart().  Private  parts  are not accessible, so methods such as getPart() will have no effect on them.
       For example, if you call getPart() to retrieve a private part, NULL will be returned even when  the  part
       exists.

       Every  nodekit  reference page has a Parts section describing the function of each public part it adds to
       those inherited from its parent  class.  Also,  a  Catalog  Parts  section  has  tables  of  often-needed
       information  from  the  catalog  (part  type,  etc.). These tables include all public parts, both new and
       inherited. Only the public parts of a nodekit are described in the reference pages. Nodekits take care of
       the rest for you; they automatically arrange the subgraph, creating and deleting the private  parts  when
       necessary.  (The  SoNodekitCatalog  reference  page  has  methods  for  finding  out  the  part names and
       arrangement of all parts, both public and private.)

       The nodekit catalog is a template shared by all instances of a class. They use the shared  catalog  as  a
       guide  when  creating  parts  (i.e.,  constructing  actual nodes), but each instance stores its own parts
       separately. Moreover, nodekits are notSoGroup nodes, and parts are added as  hiddenchildren;  you  can
       only access parts with the methods of SoBaseKit and its derived classes.

       Any  public  part  may be retrieved with getPart(), installed with setPart(), or removed by giving a NULL
       argument to setPart(). Paths from the nodekit down to a part can be created by createPathToPart().

       By default, parts are not created until  the  user  requests  or  sets  them.  This  keeps  the  subgraph
       uncluttered and efficient for traversal. Additionally, removing a part (setting it to NULL) has the extra
       effect of removing any internal parts that are no longer needed.

       Since  nodekits  hide  their  children,  any  SoPath containing nodekits will end at the topmost nodekit.
       However, since nodekits may be nested within other nodekits, you may wish to cast an (SoPath*)  into  an
       (SoNodeKitPath*). The methods of SoNodeKitPath allow you to view all nodekits that lie on the path (see
       the reference page for SoNodeKitPath).

       Public parts in the nodekit catalog fall into three categories:

       [1] regularnodes

       [2] nodekits, or nestednodekits (which may nest recursively). Any node  which  is  public  in  a  nested
       nodekit is accessible to the higher level nodekit(s) that contains it. The description of getPart() below
       shows  how  to  refer  to  nested parts by name (e.g., "appearance.material"). This works for any nodekit
       method that takes a part name for an argument.

       [3] lists, or listparts. These parts group together children (listelements) of  a  particular  type  or
       types.  As  with  nested  nodekits,  you  can  refer  to  individual elements using notation described in
       getPart() (e.g., "childList[0]", or if the list elements are in turn nodekits, "childList[2].transform").

       When the  catalog  denotes  that  a  part  is  a  list,  the  part  itself  is  always  a  node  of  type
       SoNodeKitListPart.  The  catalog specifies a set of permissible listItemTypes and a listContainerType for
       that part. It gives this information to the SoNodeKitListPart when it creates it. From then on, the  list
       part  will  enforce type checking. So even if you retrieve the SoNodeKitListPart with getPart(), you will
       not be able to add illegal children. (See the SoNodeKitListPart reference page for more information).  As
       an  example,  the  callbackList part of SoBaseKit has an SoSeparator container and allows only SoCallback
       and SoEventCallback  nodes  in  the  list.  Children  may  be  added,  retrieved,  and  removed  from  an
       SoNodeKitListPart  node  using methods that parallel those of SoGroup. However, type-checking is strictly
       enforced.

       Note that, although all public parts are leaves in the nodekit catalog, you are free to add  children  to
       them  (assuming  that they are groups, nodekits, or list parts). A part's status as a leaf in the catalog
       just means that the nodekit will not manage the part's children. For example,  SoWrapperKit  has  a  part
       called  contents with a part type of SoSeparator. You can put whatever you want underneath the separator,
       as long as contents itself is an SoSeparator.

       Thus, a nodekit only controls a section of the scene graph. Above and below that section, anything goes.

       However, when nodekits are nested, they effectively create a larger `known' section of the  scene  graph.
       For  example, the appearance part of the SoSeparatorKit is a leaf node in the SoSeparatorKit catalog. But
       appearance is in turn an SoAppearanceKit, containing parts  such  as  material  and  drawStyle.  The  two
       nodekits  combine to make an even larger template, which the SoSeparatorKit can examine by looking at the
       catalogs for both classes. So an SoSeparatorKit can successfully return a part named "material"; first it
       finds (or creates) the appearance part, then it gets the material by calling getPart() on the appearance.

       When the catalog defines the listItemTypes of a list part to be nodekits,  the  name-able  space  expands
       further.  For  example,  SoSeparatorKit  has a part childList which permits only SoSeparatorKits, so each
       list element can be further searched. Hence the name "childList[0].childList[1].childList[2].material" is
       perfectly legal.

BaseKit{callbackListNULL}

       SoBase > SoFieldContainer > SoNode > SoBaseKit

SO_GET_PART(kit,partName,partClass)
          Calls getPart() with makeIfNeeded set to TRUE, then casts the result to the type partClass. Note  that
          in  the  debug  library,  this macro checks to see if the part is of type partClass, while the regular
          library does no type checking.

     SO_CHECK_PART(kit,partName,partClass)
          Calls getPart(), but with makeIfNeeded set to FALSE, then casts the result to the type partClass. Note
          that in the debug library, this macro checks to see if the  part  is  of  type  partClass,  while  the
          regular library does no type checking.

SoBaseKit()
          Constructor.

     staticconstSoNodekitCatalog*getClassNodekitCatalog()const
          Returns the SoNodekitCatalog for the class SoBaseKit.

     virtualconstSoNodekitCatalog*getNodekitCatalog()const
          Returns  the  SoNodekitCatalog  for  this  instance of SoBaseKit. While each instance of a given class
          creates its own distinct set of parts (which are actual nodes), all instances share the  same  catalog
          (which describes the parts but contains no actual node pointers).

     virtualSoNode*getPart(constSbName&partName,SbBoolmakeIfNeeded)
          Searches the nodekit catalog (and those of all nested nodekits) for the part named partName. Returns a
          pointer  to  the part if a matchisfound, the part is public, and the part has alreadybeenbuilt. If
          no match is found, or if the part is private, NULL is returned. If partName is in the catalog (or that
          of one of its nested nodekit parts), but the part has not been built yet,  the  argument  makeIfNeeded
          determines  the  course  of action. When makeIfNeeded is FALSE, NULL is returned; when makeIfNeeded is
          TRUE, getPart() will create the part (as well as any necessary intermediary  parts),  put  it  in  the
          correct place, and return a pointer to the newly created part.

          Elements  of  listparts and parts within nested nodekits can all be retrieved with getPart() The full
          syntax for legal partName arguments is given below.

          PartnameBNFnotation:

          partName=singleName|compoundNamecompoundName=singleName|compoundName.singleNamesingleName=singlePartName|singleListElementNamesinglePartName= the name of any single part in  the  catalog  (including  those  that  are  lists  or
          nodekits), or in the recursively nested catalogs of any of its parts.

          singleListElementName=singleListName[index]singleListName=  the  name of any single list-type part in the catalog, or in the recursively nested
          catalogs of any of its parts.

          index=integer

          Examples of valid part names are:

          "transform",    "appearance.material",    "childList[2].drawStyle",    "foot",    "bird.leftLeg.foot",
          "octopus.leg[4].suctionCup[2].material"

     SbStringgetPartString(constSoBase*part)
          Given a node or a path to a node, checks if the part exists in the nodekit, in a nested nodekit, or an
          element  of a list part. If so, returns a string describing the part name; otherwise, returns an empty
          string ("").

     virtualSoNodeKitPath*createPathToPart(constSbName&partName,SbBoolmakeIfNeeded,constSoPath*pathToExtend=NULL)
          Returns a path that begins at this nodekit and ends at partName. Searching for the part is the same as
          in  getPart().  NULL is returned if partName cannot be found, or if makeIfNeeded is FALSE and the part
          is not yet built. If the the part is retrieved  and  the  argument  pathToExtend  is  NULL,  the  path
          returned  begins at this and ends at partName. If pathToExtend is not NULL, the path created is a copy
          of pathToExtend with entries appended all the way down to partName. It is okay for pathToExtend to  go
          beyond  the  nodekit;  extra  nodes  will  be  popped off the tail before continuing from this down to
          partName.

     virtualSbBoolsetPart(constSbName&partName,SoNode*newPart)
          Inserts the given node (not a copy) as the new part specified  by  partName.  See  getPart()  for  the
          syntax  of  partName.  This  method  adds  any  extra  nodes needed to fit the part into the nodekit's
          catalog. For example, if you call:
               mySepKit->setPart("childList[0]",myNewChild);
          the kit may need to create the part childList before it can install myNewChild. Run-time type checking
          verifies that the node type of newPart matches the type  called  for  by  partName.  For  example,  if
          partName  was  a  material  for  an SoSeparatorKit, but newPart was an SoTransform node, then the node
          would not be installed, and FALSE would be returned.

          If newPart is NULL, then the node specified by partName is removed. If this renders any private  parts
          useless  (as  occurs  when  you  remove the last child of an SoGroup node), they will also be removed.
          Hence nodekits do not retain unnecessary nodes.

          TRUE is returned on success, and FALSE upon error.

     SbBoolset(char*partName,char*parameters)SbBoolset(char*nameValuePairs)
          These functions allow field values of parts (nodes) to be set. If partName and  parameters  are  used,
          then  a single part is specified by partName; the field values are specified in parameters. The format
          of paramaters is the Inventor File Format syntax.  For example,
               mySepKit->set("material","diffuseColor100shininess0.6");
          sets the part material to the values "diffuseColor100shininess0.6". The values used in parameters
          must of course be appropriate for the node-type to which partName belongs. In this case,  the  nodekit
          SoSeparatorKit has a part named material which is of type SoMaterial.

          The  nameValuePairs  syntax  can  be  used  to  set  the  field  values  in  several  different  parts
          simultaneously.  In  this  case,  the  argument  string,  nameValuePairs  contains  name-value  pairs:
          "partName1{parameters1}...partNameN{parametersN}".

          For example,
               mySepKit->set("material{diffuseColor111}transform{translation43.6}");mySepKit->set("childList[0].material{ambientColor.5.5.5}");staticSbBoolisSearchingChildren()staticvoidsetSearchingChildren(SbBoolnewVal)
          Sets  and  queries  if nodekit children are searched during SoSearchAction traversal. By default, they
          are not.

     staticSoTypegetClassTypeId()
          Returns type identifier for this class.

       SoBaseKit — base class for all node kits

(SoNodeKitListPart)callbackList
          This is the only part that the base class SoBaseKit creates. It is a public part that is inherited  by
          all  nodekits.  It  provides an easy way to add callbacks for a nodekit to use during action traversal
          (e.g.  SoHandleEventAction).  It  is  a  list  part  and  may  contain  numerous   SoCallback   and/or
          SoEventCallback nodes.

SoAppearanceKit,SoCameraKit,SoLightKit,SoNodeKit,SoNodeKitDetail,SoNodeKitListPart,SoNodeKitPath,SoNodekitCatalog,SoSceneKit,SoSeparatorKit,SoShapeKit,SoWrapperKitSoBaseKit(3IV)()

#include<Inventor/nodekits/SoBaseKit.h>

          Parts from class SoBaseKit:

     (SoNodeKitListPart)callbackList

          Methods from class SoBaseKit:

                              SoBaseKit()staticconstSoNodekitCatalog*getClassNodekitCatalog()constvirtualconstSoNodekitCatalog*getNodekitCatalog()constvirtualSoNode*getPart(constSbName&partName,SbBoolmakeIfNeeded)SbStringgetPartString(constSoBase*part)virtualSoNodeKitPath*createPathToPart(constSbName&partName,SbBoolmakeIfNeeded,constSoPath*pathToExtend=NULL)virtualSbBoolsetPart(constSbName&partName,SoNode*newPart)SbBoolset(char*partName,char*parameters)SbBoolset(char*nameValuePairs)staticSbBoolisSearchingChildren()staticvoidsetSearchingChildren(SbBoolnewVal)staticSoTypegetClassTypeId()

          Methods from class SoNode:

     voidsetOverride(SbBoolstate)SbBoolisOverride()constSoNode*copy(SbBoolcopyConnections=FALSE)constvirtualSbBoolaffectsState()conststaticSoNode*getByName(constSbName&name)staticintgetByName(constSbName&name,SoNodeList&list)

          Methods from class SoFieldContainer:

     voidsetToDefaults()SbBoolhasDefaultValues()constSbBoolfieldsAreEqual(constSoFieldContainer*fc)constvoidcopyFieldValues(constSoFieldContainer*fc,SbBoolcopyConnections=FALSE)voidget(SbString&fieldDataString)virtualintgetFields(SoFieldList&resultList)constvirtualSoField*getField(constSbName&fieldName)constSbBoolgetFieldName(constSoField*field,SbName&fieldName)constSbBoolisNotifyEnabled()constSbBoolenableNotify(SbBoolflag)

          Methods from class SoBase:

     voidref()voidunref()constvoidunrefNoDelete()constvoidtouch()virtualSoTypegetTypeId()constSbBoolisOfType(SoTypetype)constvirtualvoidsetName(constSbName&name)virtualSbNamegetName()const

          Macros from class SoBaseKit:

     SO_GET_PART(kit,partName,partClass)SO_CHECK_PART(kit,partName,partClass)