7.5. About Parts

This section describes the parameters that define a part. the section called “Case Study: The Parts of SoSeparatorKit” shows the values for these parameters as they are used in the catalog for SoSeparatorKit SoSeparatorKit SoSeparatorKit .

Anatomy of a Part

Node-kit catalogs are made up of parts in a particular arrangement. A part is completely described by the following parameters:

SbName

name

This parameter is the name used to refer to this part, such as “shape,” “material,” “leg,” and so on. The part corresponding to the node kit itself is always given the name “this” in its own catalog.

SoType

type

This parameter is the node type identifier for this part, such as SoTransform::getClassTypeId(). The type may be the type of an abstract node. It is checked whenever a user attempts to get or set a part. For example, if a user calls

setPart("partName", newNode),

the setPart() method first checks that newNode belongs to a class derived from type. The node is only installed as “partName” if it passes this type-checking test.

SoType

defaultType

This parameter is used only when the node kit needs to build a part, but that part's type is the type of an abstract node. For example, in SoShapeKit SoShapeKit SoShapeKit , the part “shape” has a type equal to that of SoShape SoShape SoShape (an abstract class), but the defaultType is SoCube SoCube SoCube . If the user calls getPart(), but the part has not yet been created, then the kit creates and returns an SoCube SoCube SoCube (the defaultType). However, when calling setPart(), any node of a type derived from SoShape SoShape SoShape (the value of type) is permissible.

SbBool

nullByDefault

This parameter specifies whether a part is NULL by default. If FALSE, the part is always created by the SO_KIT_INIT_INSTANCE() macro for the node kit that uses this catalog.

SbBool

isLeaf This parameter is not explicitly set by you as the designer of the node kit. It is calculated automatically as you add parts to the node-kit catalog. If isLeaf is TRUE, then the part has no children within the catalog. So in the SoAppearanceKit SoAppearanceKit SoAppearanceKit shown in Figure 7.5, “ Catalog Diagram for SoAppearanceKit ”, all parts except for “this” would have isLeaf set to TRUE.

Leaf parts are the only ones in the catalog that the end user of the node kit can retrieve through calls like getPart() and createPathToPart(). All other parts are considered internal to the node kit. (Of course, not every leaf part can be returned. See isPublic on SbBool .)

Note that a part can still have children in a scene graph without having children within the catalog. For example, any public leaf part in the catalog whose type is derived from SoGroup SoGroup SoGroup can be retrieved with getPart(). Following this, children can be added. The result is that in the scene graph, this part is not a leaf node. But it is still a leaf part in the catalog.

Some parts, such as the “childList” part in SoSeparatorKit SoSeparatorKit SoSeparatorKit , are list parts. A list part is always of type SoNodeKitList, a special type of group node, and the node kit ensures that only certain types of nodes are added to it as children. So, in a scene graph, it may very well have children. But in the catalog, it does not.

Finally, imagine using an SoAppearanceKit SoAppearanceKit SoAppearanceKit as a leaf part in a higher level node kit such as an SoSeparatorKit SoSeparatorKit SoSeparatorKit . Children may be added to the “appearance” part through calls such as:

myKit->setPart("appearance.material", myMtl)

This could add a child to the part “appearance,” but the appearance part would remain a leaf part in the catalog.

SbName

parentName

This parameter is the name of the catalog part that is the parent of this part. The parentName of the part “this” is always the empty string ("").

SbName

rightSiblingName

This parameter is the name of the catalog part that is the right sibling of this part. If a part does not have any right siblings in the catalog, then the rightSiblingName is the empty string ("").

SbBool

isList

If this parameter is TRUE, then the part is treated as a list and will be an SoNodeKitList node. The children of this part are restricted to certain classes of nodes. Whenever you add a child to a node-kit list, it checks to see if that child is of the correct type. If the type is not allowed, the child is not added. Use the standard methods for adding, removing, replacing, and inserting children in the node-kit list.

SoType

listContainerType

This parameter has meaning only if isList is TRUE. The SoNodeKitList keeps a hidden child of type SoGroup SoGroup SoGroup below itself and above its children. This extra node is the container node, and its type is given by the listContainerType parameter. The container node can be any SoGroup SoGroup SoGroup (for example, separator, switch, or group).

SbPList

listItemTypes

This parameter has meaning only if isList is TRUE. It is a list of the types permitted as children of the part. For example,

addChild("myList", newChild)

works only if newChild is derived from one of the types in the listItemTypes for the part “myList.”

SbBool

isPublic

This parameter indicates whether a user can request this part. If isPublic is TRUE, then the part can be accessed. Otherwise, it is considered internal to the node kit. Note that if the part is not a leaf part, then isPublic is always FALSE.

For example, consider the hypothetical PublicSpherePrivateSphereKit illustrated in Figure 7.1, “ Hypothetical PublicSpherePrivateSphereKit. If “privateAppearance” were a private part of type SoAppearanceKit SoAppearanceKit SoAppearanceKit , then the user could not call

setPart("privateAppearance.material", newNode)

because both “privateAppearance” and its material part are considered private.

Hypothetical PublicSpherePrivateSphereKit

Figure 7.1.  Hypothetical PublicSpherePrivateSphereKit



Case Study: The Parts of SoSeparatorKit

Figure 7.2, “ Catalog Diagram for SoSeparatorKit ” and Tables 7-1 through 7-3 show the parts of SoSeparatorKit SoSeparatorKit SoSeparatorKit . This kit is the base class for SoShapeKit SoShapeKit SoShapeKit and SoWrapperKit SoWrapperKit SoWrapperKit . Both subclasses inherit the parts in the SoSeparatorKit SoSeparatorKit SoSeparatorKit 's catalog. The parts in this catalog are as follows:

“callbackList”

a list part that can contain either SoCallback SoCallback SoCallback or SoEventCallback SoEventCallback SoEventCallback nodes. If you want to make your instance of an SoSeparatorKit SoSeparatorKit SoSeparatorKit respond to events, you can create callback nodes and add them to this list. This part is inherited from SoBaseKit SoBaseKit SoBaseKit .

“topSeparator”

a separator node that is required to prevent the property nodes from influencing nodes outside the node kit.

The “pickStyle,” “appearance,” “units,” “transform,” and “texture2Transform” parts are all composed of property nodes. Note that “appearance” is, in turn, a node kit.

“childList”

a list of SoSeparatorKits. By using the “childList” and the “transform” parts, you can create motion hierarchies.

Catalog Diagram for SoSeparatorKit

Figure 7.2.  Catalog Diagram for SoSeparatorKit



Table 7.1. Type Parameters of SoSeparatorKit Parts

name

type

defaultType

“this”

SoSeparatorKit

same

“callbackList”

SoNodeKitList

same

“topSeparator”

SoSeparator

same

“pickStyle”

SoPickStyle

same

“appearance”

SoAppearanceKit

same

“units”

SoUnits

same

“transform”

SoTransform

same

“texture2Transform”

SoTexture2Transform

same

“childList”

SoNodeKitList

same

Table 7.2.  Catalog Layout Parameters of SoSeparatorKit Parts

name

isLeaf

parentName

rightSibling

“this”

FALSE

“ ”

“ ”

“callbackList”

TRUE

“this”

“topSeparator”

“topSeparator”

FALSE

“this”

“ ”

“pickStyle”

TRUE

“topSeparator”

“appearance”

“appearance”

TRUE

“topSeparator”

“units”

“units”

TRUE

“topSeparator”

“transform”

“transform”

TRUE

“topSeparator”

“texture2Transform”

“texture2Transform”

TRUE

“topSeparator”

“childList”

“childList”

TRUE

“topSeparator”

“ ”

Table 7.3.  Behavior Parameters of SoSeparatorKit Parts

name

isList

listContainer- Type

listItemTypes

isPublic

“this”

FALSE

--

--

FALSE

“callbackList”

TRUE

SoSeparator

SoCallback and

SoEventCallback

TRUE

“topSeparator”

FALSE

--

--

FALSE

“pickStyle”

FALSE

--

--

TRUE

“appearance”

FALSE

--

--

TRUE

“units”

FALSE

--

--

TRUE

“transform”

FALSE

--

--

TRUE

“texture2-

Transform”

FALSE

--

--

TRUE

“childList”

TRUE

SoSeparator

SoSeparatorKit

TRUE