1SoBaseKit(3IV)() SoBaseKit(3IV)()
2
6 SoBaseKit — base class for all node kits
7
9 SoBase > SoFieldContainer > SoNode > SoBaseKit
10
12 #include <Inventor/nodekits/SoBaseKit.h>
13 Parts from class SoBaseKit:
15 (SoNodeKitListPart) callbackList
17 Methods from class SoBaseKit:
19 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 Methods from class SoNode:
39 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 Methods from class SoFieldContainer:
48 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 Methods from class SoBase:
63 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 Macros from class SoBaseKit:
74 SO_GET_PART(kit, partName, partClass)
76 SO_CHECK_PART(kit, partName, partClass)
77
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 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 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 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 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 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 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 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 Public parts in the nodekit catalog fall into three categories:
145 [1] regular nodes
147 [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 [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 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 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 Thus, a nodekit only controls a section of the scene graph. Above and
183 below that section, anything goes.
184 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 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
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
211 SoBaseKit()
212 Constructor.
213 static const SoNodekitCatalog *
215 getClassNodekitCatalog() const
216 Returns the SoNodekitCatalog for the class SoBaseKit.
217 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 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 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 Part name BNF notation:
244 partName = singleName | compoundName
246 compoundName = singleName | compoundName.singleName
248 singleName = singlePartName | singleListElementName
250 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 singleListElementName = singleListName[index]
256 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 index = integer
261 Examples of valid part names are:
263 "transform", "appearance.material", "childList[2].drawStyle",
265 "foot", "bird.leftLeg.foot", "octopus.leg[4].suctionCup[2].material"
266 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 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 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 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 TRUE is returned on success, and FALSE upon error.
305 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 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 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 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 static SoType getClassTypeId()
336 Returns type identifier for this class.
337
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 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
354 SoGLRenderAction, SoCallbackAction, SoGetBoundingBoxAction, SoHan‐
355 dleEventAction
356 Behaves like an SoGroup. Traverses each child in order.
357 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 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 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 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 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 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 [1] NULL parts only write if the catalog states they are created by
397 default.
398 [2] Empty SoGroup and SoSeparator nodes do not write.
400 [3] Non-leaf parts only write if they have non-default field values.
402 [4] List parts only write if they have children or if the container
404 node has non-default field values.
405 [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
411 ┌────────────────────────────────────────────────────────┐
412 │ All parts │
413 │ NULL by │
414 │Part Name Part Type Default Type Default │
415 │ │
416 │callbackList NodeKitListPart -- yes │
417 │ │
418 └────────────────────────────────────────────────────────┘
419 ┌───────────────────────────────────────────────────────────────┐
420 │ Extra information for list parts from above table │
421 │ │
422 │Part Name Container Type Permissible Types │
423 │ │
424 │callbackList Separator Callback, EventCallback │
425 │ │
426 └───────────────────────────────────────────────────────────────┘
428 BaseKit {
429 callbackList NULL
430 }
431
433 SoAppearanceKit, SoCameraKit, SoLightKit, SoNodeKit, SoNodeKitDetail,
434 SoNodeKitListPart, SoNodeKitPath, SoNodekitCatalog, SoSceneKit, SoSepa‐
435 ratorKit, SoShapeKit, SoWrapperKit
436 SoBaseKit(3IV)()