7.6. Defining a Node-Kit Part

As mentioned in Section 7.1, “Overview”, node-kit catalogs are defined within the constructor. Three macros assist you in defining new parts for the node-kit catalog:

SO_KIT_ADD_CATALOG_ENTRY()

adds a part to the catalog

SO_KIT_ADD_CATALOG_ABSTRACT_ENTRY()

adds a part that is an abstract type to the catalog

SO_KIT_ADD_CATALOG_LIST_ENTRY()

adds a list part to the catalog

Adding a Catalog Entry

To add new parts to a catalog, use the following macro:

SO_KIT_ADD_CATALOG_ENTRY( name, className, nullByDefault, parentName, rightSiblingName, isPublicPart)

If your new part is a list part, or if the type is going to be an abstract type, see the section called “Adding a List Entry” or the section called “Adding an Entry of Abstract Type”. Note that the rightSiblingName may change if entries are added to the catalog. If you add another part later, it is possible that the rightSiblingName will change. Figures 7-3 and 7-4 illustrate this.

Right Sibling Names Before Adding the “middle” Part

Figure 7.3.  Right Sibling Names Before Adding the “middle” Part



Right Sibling Names After Adding the “middle” Part

Figure 7.4.  Right Sibling Names After Adding the “middle” Part



Suppose you want to add a part as the middle child in Figure 7.3, “ Right Sibling Names Before Adding the “middle” Part. If the new part is a public label node that is NULL by default, you use the following macro:

SO_KIT_ADD_CATALOG_ENTRY(middle, SoLabel, TRUE, this,
                         right, TRUE);

Notice that part names are not quoted in macros. Figure 7.4, “ Right Sibling Names After Adding the “middle” Part shows how the right sibling names change after this part has been added to the node kit.

Adding a List Entry

If the part you wish to add is a list part, use the following macro, which adds the argument listItemClassName. This parameter is used for type-checking when the user attempts to add new nodes as children of the list parts.

SO_KIT_ADD_CATALOG_LIST_ENTRY( name, listContainerClassName, nullByDefault, parentName, rightName, listItemClassName, isPublicPart)

If you want your list to accept more than one type of node, then use the macro SO_KIT_ADD_LIST_ITEM_TYPE(), described in the section called “Adding a Type to a List Entry”. Note that the list container class name must be a subclass of SoGroup SoGroup SoGroup .

The “childList” part of SoSeparatorKit SoSeparatorKit SoSeparatorKit is a list of other SoSeparatorKits. The part itself is an SoNodeKitListPart SoNodeKitListPart SoNodeKitListPart node, and it is the rightmost part in the catalog below “topSeparator.” The container is an SoSeparator SoSeparator SoSeparator node.

The following code adds “childList” to the catalog:

SO_KIT_ADD_CATALOG_LIST_ENTRY(childList, SoSeparator, TRUE, 
	topSeparator,  , SoSeparatorKit,
	TRUE);

Adding an Entry of Abstract Type

If you wish to add a part of abstract type, you also need to provide the parameter defaultType, to be used when the kit has to construct the part on demand. This macro adds one parameter to the regular part-creation macro. Its syntax is

SO_KIT_ADD_CATALOG_ABSTRACT_ENTRY( name, className, defaultClassName, nullByDefault, parentName, rightName, isPublicPart)

For example, suppose you want to add an abstract part “anyKit” as the rightmost child of “this.” This part can be any node kit, but the defaultType is an appearance kit. To create this part:

SO_KIT_ADD_CATALOG_ABSTRACT_ENTRY(anyKit, SoBaseKit,
	 SoAppearanceKit, TRUE, this, , TRUE);