Provided by: inventor-doc_2.1.5-10+dfsg-2_all bug

NAME

       SoBaseKit — base class for all node kits

INHERITS FROM

       SoBase > SoFieldContainer > SoNode > SoBaseKit

SYNOPSIS

       #include <Inventor/nodekits/SoBaseKit.h>

          Parts from class SoBaseKit:

     (SoNodeKitListPart)  callbackList

          Methods from class SoBaseKit:

                              SoBaseKit()
     static const SoNodekitCatalog *
                              getClassNodekitCatalog() const
     virtual const SoNodekitCatalog *
                              getNodekitCatalog() const
     virtual SoNode *         getPart(const SbName &partName, SbBool makeIfNeeded)
     SbString                 getPartString(const SoBase *part)
     virtual SoNodeKitPath *  createPathToPart(const SbName &partName, SbBool makeIfNeeded, const
                                   SoPath *pathToExtend = NULL)
     virtual SbBool           setPart(const SbName &partName, SoNode *newPart)
     SbBool                   set(char *partName, char *parameters)
     SbBool                   set(char *nameValuePairs)
     static SbBool            isSearchingChildren()
     static void              setSearchingChildren(SbBool newVal)
     static SoType            getClassTypeId()

          Methods from class SoNode:

     void                setOverride(SbBool state)
     SbBool              isOverride() const
     SoNode *            copy(SbBool copyConnections = FALSE) const
     virtual SbBool      affectsState() const
     static SoNode *     getByName(const SbName &name)
     static int          getByName(const SbName &name, SoNodeList &list)

          Methods from class SoFieldContainer:

     void                setToDefaults()
     SbBool              hasDefaultValues() const
     SbBool              fieldsAreEqual(const SoFieldContainer *fc) const
     void                copyFieldValues(const SoFieldContainer  *fc,  SbBool  copyConnections  =
                              FALSE)
     void                get(SbString &fieldDataString)
     virtual int         getFields(SoFieldList &resultList) const
     virtual SoField *   getField(const SbName &fieldName) const
     SbBool              getFieldName(const SoField *field, SbName &fieldName) const
     SbBool              isNotifyEnabled() const
     SbBool              enableNotify(SbBool flag)

          Methods from class SoBase:

     void                ref()
     void                unref() const
     void                unrefNoDelete() const
     void                touch()
     virtual SoType      getTypeId() const
     SbBool              isOfType(SoType type) const
     virtual void        setName(const SbName &name)
     virtual SbName      getName() const

          Macros from class SoBaseKit:

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

DESCRIPTION

       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 nodekit catalog (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 not SoGroup nodes, and
       parts are added as hidden children;  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] regular nodes

       [2] nodekits, or nested nodekits (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 list parts. These  parts  group  together  children  (list  elements)  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.

PARTS

     (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.

METHODS

                              SoBaseKit()
          Constructor.

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

     virtual const SoNodekitCatalog *
                              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).

     virtual SoNode *         getPart(const SbName &partName, SbBool makeIfNeeded)
          Searches the nodekit catalog (and those of all nested  nodekits)  for  the  part  named
          partName.  Returns  a  pointer to the part if a match is found, the part is public, and
          the part has already been built. 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  list  parts  and  parts  within nested nodekits can all be retrieved with
          getPart() The full syntax for legal partName arguments is given below.

          Part name BNF notation:

          partName = singleName | compoundName

          compoundName = singleName | compoundName.singleName

          singleName = singlePartName | singleListElementName

          singlePartName = 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"

     SbString                 getPartString(const SoBase *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 ("").

     virtual SoNodeKitPath *  createPathToPart(const SbName &partName, SbBool makeIfNeeded, const
                                   SoPath *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.

     virtual SbBool           setPart(const SbName &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.

     SbBool                   set(char *partName, char *parameters)
     SbBool                   set(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", "diffuseColor 1 0 0 shininess 0.6");
          sets the part material to the values "diffuseColor 1 0 0  shininess  0.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 { diffuseColor 1 1 1 }
                           transform { translation 4 3 .6 }");
               mySepKit->set("childList[0].material { ambientColor .5 .5 .5 }");

     static SbBool            isSearchingChildren()
     static void              setSearchingChildren(SbBool newVal)
          Sets  and  queries if nodekit children are searched during SoSearchAction traversal. By
          default, they are not.

     static SoType            getClassTypeId()
          Returns type identifier for this class.

MACROS

       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.

ACTION BEHAVIOR

       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.

CATALOG PARTS

       ┌────────────────────────────────────────────────────────┐
       │                       All parts                        │
       │                                                NULL by │
       │Part Name      Part Type         Default Type   Default │
       │                                                        │
       │callbackList   NodeKitListPart   --               yes   │
       │                                                        │
       └────────────────────────────────────────────────────────┘
       ┌───────────────────────────────────────────────────────────────┐
       │      Extra information for list parts from above table        │
       │                                                               │
       │Part Name      Container Type   Permissible Types              │
       │                                                               │
       │callbackList   Separator        Callback, EventCallback        │
       │                                                               │
       └───────────────────────────────────────────────────────────────┘

FILE FORMAT/DEFAULTS

       BaseKit {
          callbackList  NULL
     }

SEE ALSO

       SoAppearanceKit,  SoCameraKit,  SoLightKit, SoNodeKit, SoNodeKitDetail, SoNodeKitListPart,
       SoNodeKitPath, SoNodekitCatalog, SoSceneKit, SoSeparatorKit, SoShapeKit, SoWrapperKit

                                                                                 SoBaseKit(3IV)()