1SoBaseKit(3IV)()                                              SoBaseKit(3IV)()
2
3
4

NAME

6       SoBaseKit — base class for all node kits
7

INHERITS FROM

9       SoBase > SoFieldContainer > SoNode > SoBaseKit
10

SYNOPSIS

12       #include <Inventor/nodekits/SoBaseKit.h>
13
14          Parts from class SoBaseKit:
15
16     (SoNodeKitListPart)  callbackList
17
18          Methods from class SoBaseKit:
19
20                              SoBaseKit()
21     static const SoNodekitCatalog *
22                              getClassNodekitCatalog() const
23     virtual const SoNodekitCatalog *
24                              getNodekitCatalog() const
25     virtual   SoNode   *         getPart(const   SbName   &partName,   SbBool
26                                   makeIfNeeded)
27     SbString                 getPartString(const SoBase *part)
28     virtual SoNodeKitPath *  createPathToPart(const SbName &partName,  SbBool
29                                   makeIfNeeded,  const SoPath *pathToExtend =
30                                   NULL)
31     virtual SbBool           setPart(const SbName &partName, SoNode *newPart)
32     SbBool                   set(char *partName, char *parameters)
33     SbBool                   set(char *nameValuePairs)
34     static SbBool            isSearchingChildren()
35     static void              setSearchingChildren(SbBool newVal)
36     static SoType            getClassTypeId()
37
38          Methods from class SoNode:
39
40     void                setOverride(SbBool state)
41     SbBool              isOverride() const
42     SoNode *            copy(SbBool copyConnections = FALSE) const
43     virtual SbBool      affectsState() const
44     static SoNode *     getByName(const SbName &name)
45     static int          getByName(const SbName &name, SoNodeList &list)
46
47          Methods from class SoFieldContainer:
48
49     void                setToDefaults()
50     SbBool              hasDefaultValues() const
51     SbBool              fieldsAreEqual(const SoFieldContainer *fc) const
52     void                copyFieldValues(const  SoFieldContainer  *fc,  SbBool
53                              copyConnections = FALSE)
54     void                get(SbString &fieldDataString)
55     virtual int         getFields(SoFieldList &resultList) const
56     virtual SoField *   getField(const SbName &fieldName) const
57     SbBool              getFieldName(const SoField *field, SbName &fieldName)
58                              const
59     SbBool              isNotifyEnabled() const
60     SbBool              enableNotify(SbBool flag)
61
62          Methods from class SoBase:
63
64     void                ref()
65     void                unref() const
66     void                unrefNoDelete() const
67     void                touch()
68     virtual SoType      getTypeId() const
69     SbBool              isOfType(SoType type) const
70     virtual void        setName(const SbName &name)
71     virtual SbName      getName() const
72
73          Macros from class SoBaseKit:
74
75     SO_GET_PART(kit, partName, partClass)
76     SO_CHECK_PART(kit, partName, partClass)
77
78

DESCRIPTION

80       This is the base class from which all nodekit nodes are derived. Nodek‐
81       its  provide  a convenient mechanism for creating groups of scene graph
82       nodes with some larger meaning. When you create a shape node such as an
83       indexed  face  set,  for  example,  you almost always precede it with a
84       coordinate node. You may also want to add a transform node  or  specify
85       properties with material, drawing style, material binding, etc. Instead
86       of creating each of these nodes individually and  then  arranging  them
87       into a subgraph, you can use a nodekit of the appropriate type (in this
88       case, SoShapeKit).
89
90       Each class of nodekit has a  nodekit  catalog  (SoNodekitCatalog)  that
91       describes  the nodes in the subgraph, referred to as parts. The catalog
92       has an entry for each part, with  information  such  as  the  partName,
93       partType,  and nullByDefault (if FALSE the constructor creates it). The
94       catalog also describes the arrangement of parts in the subgraph. (Other
95       information  is  described below; a complete description is in the SoN‐
96       odekitCatalog reference page.)
97
98       If we regard the scene graph arrangement as a branching tree, then  the
99       top  node  (root)  of the arrangement is always the nodekit itself. The
100       leaf nodes are those at  the  bottom  (containing  no  children).  Some
101       leaves of the tree are defined in the catalog to be public parts, while
102       other leaves are private. All non-leaf parts are considered internal to
103       the nodekit structure and are marked private. Public parts are accessi‐
104       ble; they may be requested, changed, or set by the programmer with mem‐
105       ber  functions  such as getPart(). Private parts are not accessible, so
106       methods such as getPart() will have no effect on them. For example,  if
107       you  call  getPart()  to retrieve a private part, NULL will be returned
108       even when the part exists.
109
110       Every nodekit reference page has a Parts section describing  the  func‐
111       tion  of  each  public  part it adds to those inherited from its parent
112       class. Also, a Catalog Parts section has tables of often-needed  infor‐
113       mation  from  the  catalog  (part type, etc.). These tables include all
114       public parts, both new and  inherited.  Only  the  public  parts  of  a
115       nodekit are described in the reference pages. Nodekits take care of the
116       rest for you; they automatically arrange  the  subgraph,  creating  and
117       deleting the private parts when necessary. (The SoNodekitCatalog refer‐
118       ence page has methods for finding out the part names and arrangement of
119       all parts, both public and private.)
120
121       The  nodekit  catalog is a template shared by all instances of a class.
122       They use the shared catalog as a guide when creating parts (i.e.,  con‐
123       structing  actual  nodes), but each instance stores its own parts sepa‐
124       rately. Moreover, nodekits are not SoGroup nodes, and parts  are  added
125       as  hidden  children;  you  can  only  access parts with the methods of
126       SoBaseKit and its derived classes.
127
128       Any public part may be retrieved with getPart(),  installed  with  set‐
129       Part(),  or  removed by giving a NULL argument to setPart(). Paths from
130       the nodekit down to a part can be created by createPathToPart().
131
132       By default, parts are not created until the user requests or sets them.
133       This  keeps the subgraph uncluttered and efficient for traversal. Addi‐
134       tionally, removing a part (setting it to NULL) has the extra effect  of
135       removing any internal parts that are no longer needed.
136
137       Since nodekits hide their children, any SoPath containing nodekits will
138       end at the topmost nodekit.  However,  since  nodekits  may  be  nested
139       within other nodekits, you may wish to cast an (SoPath *) into an (SoN‐
140       odeKitPath *). The methods of  SoNodeKitPath  allow  you  to  view  all
141       nodekits  that  lie  on the path (see the reference page for SoNodeKit‐
142       Path).
143
144       Public parts in the nodekit catalog fall into three categories:
145
146       [1] regular nodes
147
148       [2] nodekits, or nested nodekits (which may nest recursively). Any node
149       which  is  public in a nested nodekit is accessible to the higher level
150       nodekit(s) that contains it. The description of getPart()  below  shows
151       how  to  refer  to  nested parts by name (e.g., "appearance.material").
152       This works for any nodekit method that takes a part name for  an  argu‐
153       ment.
154
155       [3]  lists,  or  list  parts. These parts group together children (list
156       elements) of a particular type or types. As with nested  nodekits,  you
157       can  refer to individual elements using notation described in getPart()
158       (e.g., "childList[0]", or if the list elements are  in  turn  nodekits,
159       "childList[2].transform").
160
161       When  the  catalog  denotes  that  a part is a list, the part itself is
162       always a node of type SoNodeKitListPart. The catalog specifies a set of
163       permissible  listItemTypes  and  a  listContainerType for that part. It
164       gives this information to the SoNodeKitListPart  when  it  creates  it.
165       From  then on, the list part will enforce type checking. So even if you
166       retrieve the SoNodeKitListPart with getPart(), you will not be able  to
167       add  illegal  children.  (See  the SoNodeKitListPart reference page for
168       more information). As an example, the callbackList  part  of  SoBaseKit
169       has  an  SoSeparator  container and allows only SoCallback and SoEvent‐
170       Callback nodes in the list.  Children  may  be  added,  retrieved,  and
171       removed  from  an  SoNodeKitListPart  node  using methods that parallel
172       those of SoGroup. However, type-checking is strictly enforced.
173
174       Note that, although all public parts are leaves in the nodekit catalog,
175       you  are  free  to add children to them (assuming that they are groups,
176       nodekits, or list parts). A part's status as a leaf in the catalog just
177       means  that  the nodekit will not manage the part's children. For exam‐
178       ple, SoWrapperKit has a part called contents with a part type of SoSep‐
179       arator. You can put whatever you want underneath the separator, as long
180       as contents itself is an SoSeparator.
181
182       Thus, a nodekit only controls a section of the scene graph.  Above  and
183       below that section, anything goes.
184
185       However,  when  nodekits  are  nested, they effectively create a larger
186       `known' section of the scene graph. For example, the appearance part of
187       the  SoSeparatorKit  is  a leaf node in the SoSeparatorKit catalog. But
188       appearance is in turn an  SoAppearanceKit,  containing  parts  such  as
189       material and drawStyle. The two nodekits combine to make an even larger
190       template, which the SoSeparatorKit can examine by looking at the  cata‐
191       logs  for  both classes. So an SoSeparatorKit can successfully return a
192       part named "material"; first it finds (or creates) the appearance part,
193       then it gets the material by calling getPart() on the appearance.
194
195       When  the catalog defines the listItemTypes of a list part to be nodek‐
196       its, the name-able space expands further. For  example,  SoSeparatorKit
197       has  a  part childList which permits only SoSeparatorKits, so each list
198       element    can    be    further    searched.     Hence     the     name
199       "childList[0].childList[1].childList[2].material" is perfectly legal.
200

PARTS

202     (SoNodeKitListPart)  callbackList
203          This is the only part that the base class SoBaseKit creates. It is a
204          public part that is inherited by all nodekits. It provides  an  easy
205          way  to  add  callbacks for a nodekit to use during action traversal
206          (e.g. SoHandleEventAction). It is a list part and may contain numer‐
207          ous SoCallback and/or SoEventCallback nodes.
208
209

METHODS

211                              SoBaseKit()
212          Constructor.
213
214     static const SoNodekitCatalog *
215                              getClassNodekitCatalog() const
216          Returns the SoNodekitCatalog for the class SoBaseKit.
217
218     virtual const SoNodekitCatalog *
219                              getNodekitCatalog() const
220          Returns  the  SoNodekitCatalog for this instance of SoBaseKit. While
221          each instance of a given class creates its own distinct set of parts
222          (which  are  actual  nodes),  all  instances  share the same catalog
223          (which describes the parts but contains no actual node pointers).
224
225     virtual   SoNode   *         getPart(const   SbName   &partName,   SbBool
226                                   makeIfNeeded)
227          Searches  the nodekit catalog (and those of all nested nodekits) for
228          the part named partName. Returns a pointer to the part if a match is
229          found,  the  part is public, and the part has already been built. If
230          no match is found, or if the part is private, NULL is  returned.  If
231          partName  is  in  the  catalog (or that of one of its nested nodekit
232          parts),  but  the  part  has  not  been  built  yet,  the   argument
233          makeIfNeeded  determines  the course of action. When makeIfNeeded is
234          FALSE, NULL is returned; when makeIfNeeded is TRUE,  getPart()  will
235          create  the  part (as well as any necessary intermediary parts), put
236          it in the correct place, and return a pointer to the  newly  created
237          part.
238
239          Elements  of  list parts and parts within nested nodekits can all be
240          retrieved with getPart() The full syntax for  legal  partName  argu‐
241          ments is given below.
242
243          Part name BNF notation:
244
245          partName = singleName | compoundName
246
247          compoundName = singleName | compoundName.singleName
248
249          singleName = singlePartName | singleListElementName
250
251          singlePartName = the name of any single part in the catalog (includ‐
252          ing those that are lists or nodekits), or in the recursively  nested
253          catalogs of any of its parts.
254
255          singleListElementName = singleListName[index]
256
257          singleListName  = the name of any single list-type part in the cata‐
258          log, or in the recursively nested catalogs of any of its parts.
259
260          index = integer
261
262          Examples of valid part names are:
263
264          "transform",    "appearance.material",     "childList[2].drawStyle",
265          "foot", "bird.leftLeg.foot", "octopus.leg[4].suctionCup[2].material"
266
267     SbString                 getPartString(const SoBase *part)
268          Given  a  node or a path to a node, checks if the part exists in the
269          nodekit, in a nested nodekit, or an element of a list part.  If  so,
270          returns  a  string  describing  the part name; otherwise, returns an
271          empty string ("").
272
273     virtual SoNodeKitPath *  createPathToPart(const SbName &partName,  SbBool
274                                   makeIfNeeded,  const SoPath *pathToExtend =
275                                   NULL)
276          Returns a path that begins at this nodekit  and  ends  at  partName.
277          Searching for the part is the same as in getPart(). NULL is returned
278          if partName cannot be found, or if makeIfNeeded  is  FALSE  and  the
279          part is not yet built. If the the part is retrieved and the argument
280          pathToExtend is NULL, the path returned begins at this and  ends  at
281          partName. If pathToExtend is not NULL, the path created is a copy of
282          pathToExtend with entries appended all the way down to partName.  It
283          is  okay for pathToExtend to go beyond the nodekit; extra nodes will
284          be popped off the tail before continuing from this down to partName.
285
286     virtual SbBool           setPart(const SbName &partName, SoNode *newPart)
287          Inserts the given node (not a copy) as the  new  part  specified  by
288          partName. See getPart() for the syntax of partName. This method adds
289          any extra nodes needed to fit the part into the  nodekit's  catalog.
290          For example, if you call:
291               mySepKit->setPart("childList[0]", myNewChild);
292          the  kit may need to create the part childList before it can install
293          myNewChild. Run-time type checking verifies that the  node  type  of
294          newPart  matches  the  type  called for by partName. For example, if
295          partName was a material for an SoSeparatorKit, but  newPart  was  an
296          SoTransform  node,  then  the node would not be installed, and FALSE
297          would be returned.
298
299          If newPart is NULL, then the node specified by partName is  removed.
300          If this renders any private parts useless (as occurs when you remove
301          the last child of an SoGroup node), they will also be removed. Hence
302          nodekits do not retain unnecessary nodes.
303
304          TRUE is returned on success, and FALSE upon error.
305
306     SbBool                   set(char *partName, char *parameters)
307     SbBool                   set(char *nameValuePairs)
308          These  functions  allow  field values of parts (nodes) to be set. If
309          partName and parameters are used, then a single part is specified by
310          partName;  the  field values are specified in parameters. The format
311          of paramaters is the Inventor File Format syntax.  For example,
312               mySepKit->set("material", "diffuseColor 1 0 0 shininess 0.6");
313          sets the part material to the values "diffuseColor 1 0  0  shininess
314          0.6".  The  values  used in parameters must of course be appropriate
315          for the node-type to which  partName  belongs.  In  this  case,  the
316          nodekit  SoSeparatorKit  has  a part named material which is of type
317          SoMaterial.
318
319          The nameValuePairs syntax can be used to set  the  field  values  in
320          several  different  parts simultaneously. In this case, the argument
321          string,  nameValuePairs  contains  name-value  pairs:  "partName1  {
322          parameters1 } ... partNameN { parametersN }".
323
324          For example,
325               mySepKit->set("material { diffuseColor 1 1 1 }
326                           transform { translation 4 3 .6 }");
327               mySepKit->set("childList[0].material { ambientColor .5 .5 .5 }");
328
329
330     static SbBool            isSearchingChildren()
331     static void              setSearchingChildren(SbBool newVal)
332          Sets and queries if nodekit children are searched during SoSearchAc‐
333          tion traversal. By default, they are not.
334
335     static SoType            getClassTypeId()
336          Returns type identifier for this class.
337
338

MACROS

340       SO_GET_PART(kit, partName, partClass)
341          Calls getPart() with makeIfNeeded set to TRUE, then casts the result
342          to  the  type  partClass. Note that in the debug library, this macro
343          checks to see if the part is of type partClass,  while  the  regular
344          library does no type checking.
345
346     SO_CHECK_PART(kit, partName, partClass)
347          Calls  getPart(), but with makeIfNeeded set to FALSE, then casts the
348          result to the type partClass. Note that in the debug  library,  this
349          macro checks to see if the part is of type partClass, while the reg‐
350          ular library does no type checking.
351
352

ACTION BEHAVIOR

354       SoGLRenderAction,  SoCallbackAction,   SoGetBoundingBoxAction,   SoHan‐
355       dleEventAction
356          Behaves like an SoGroup. Traverses each child in order.
357
358     SoRayPickAction
359          Traverses each child in order. Then, for any pick containing the kit
360          on its path, makes an SoNodeKitDetail as follows: Sets the "detailN‐
361          odeKit"  (retrievable  with  SoNodeKitDetail::getNodeKit())  to be a
362          pointer to itself. Sets the "detailPart" (retrievable with  SoNodeK‐
363          itDetail::getPart())  to  be  a  pointer to the kit's leaf-most part
364          that lies on the pickPath. Sets  the  "detailPartName"  (retrievable
365          with  SoNodeKitDetail::getPartName())  to  be  the  partName of that
366          part, as found in the catalog.
367
368          Does not descend into nested nodekits. Each nodekit along  the  path
369          is  the  "detailPart"  in  its parent's detail. However, if the pick
370          path goes through a list part, a pointer to the child  is  used  for
371          the "detailPart", and "detailPartName" is of the form "listName[i]".
372
373     SoGetMatrixAction
374          Behaves  like an SoGroup. Does nothing unless the kit is in the mid‐
375          dle of the path chain the action is being applied  to.  If  so,  the
376          children  up  to  and  including the next node in the chain are tra‐
377          versed.
378
379     SoSearchAction
380          First, searches itself like an SoNode. Then,  checks  the  value  of
381          isSearchingChildren().  If TRUE, traverses the children in order. If
382          FALSE, returns.
383
384     SoWriteAction
385          Begins by writing out regular fields, then writes out the  parts.  A
386          nodekit  does  not write out its parts the way an SoGroup writes out
387          its children. Instead, it writes each part  as  an  SoSFNode  field.
388          First  the  partName  is  written, then the node being used for that
389          part.
390
391          To keep the files terse, nodekits write out as few parts  as  possi‐
392          ble.  However, nodekits always write a part if another instance or a
393          path is writing it. If this is not the  case,  parts  are  left  out
394          according to the following rules:
395
396          [1]  NULL parts only write if the catalog states they are created by
397          default.
398
399          [2] Empty SoGroup and SoSeparator nodes do not write.
400
401          [3] Non-leaf parts only write if they have non-default field values.
402
403          [4] List parts only write if they have children or if the  container
404          node has non-default field values.
405
406          [5]  Nested  nodekit  parts  only write if they need to write one or
407          more parts, or if they have non-default field values.
408
409

CATALOG PARTS

411       ┌────────────────────────────────────────────────────────┐
412All parts                        
413NULL by 
414Part Name      Part Type         Default Type   Default 
415       │                                                        │
416       │callbackList   NodeKitListPart   --               yes   │
417       │                                                        │
418       └────────────────────────────────────────────────────────┘
419       ┌───────────────────────────────────────────────────────────────┐
420Extra information for list parts from above table        
421       │                                                               │
422Part Name      Container Type   Permissible Types              
423       │                                                               │
424       │callbackList   Separator        Callback, EventCallback        │
425       │                                                               │
426       └───────────────────────────────────────────────────────────────┘

FILE FORMAT/DEFAULTS

428       BaseKit {
429          callbackList  NULL
430     }
431

SEE ALSO

433       SoAppearanceKit, SoCameraKit, SoLightKit,  SoNodeKit,  SoNodeKitDetail,
434       SoNodeKitListPart, SoNodeKitPath, SoNodekitCatalog, SoSceneKit, SoSepa‐
435       ratorKit, SoShapeKit, SoWrapperKit
436
437
438
439
440                                                              SoBaseKit(3IV)()
Impressum