7.1. Overview

Node kits are nodes that organize their children into a particular structure. This structure is defined by parts in a catalog. To define a new node-kit class, the main task is to create a catalog for the class (in addition to the standard tasks for deriving a “regular” node). Once a catalog is established, the rest of the functionality, such as setPart(), getPart(), and createPathToPart(), is provided by the base class for all node kits, SoBaseKit SoBaseKit SoBaseKit .

SoBaseKit SoBaseKit SoBaseKit is a direct descendant of SoNode SoNode SoNode . Therefore, when creating new node kits, you follow the standard procedure for creating and using new classes of nodes, except that you use the node-kit macros in the file SoSubKit.h. (Since you have to derive from at least SoBaseKit SoBaseKit SoBaseKit , you never need to include this file directly.) The SO_KIT_HEADER() macro declares type identifier and naming variables and methods that all node-kit classes must support. It also defines the private variable nodekitCatalog and a protected virtual method for retrieving it, getNodekitCatalog(). It defines the static method getClassNodekitCatalog() as well. The SO_KIT_SOURCE() macro defines the static variables and methods declared in the SO_KIT_HEADER() macro. Other macros useful in creating new node-kit classes are mentioned in the following sections.

Beyond this, most of the work for making a node kit focuses on creating the node-kit catalog. This catalog is a static variable and is therefore shared by all instances of the class. Whenever a user requests that a part should be added or retrieved (through getPart(), setPart(), and so on), the node-kit catalog is consulted. The node-kit catalog for any given class is created once when the first instance of that class is created.

Creating a new node kit requires these steps:

  1. Select a name for the new node-kit class and determine what class it is derived from.

  2. If the node kit has fields, define and name each field.

  3. Design each part in the catalog. Use the SO_KIT_CATALOG_ENTRY_HEADER() macro to declare a name for the part in the header file (see Section 7.2, “Defining and Naming Catalog Entries”). The parts themselves are described in the constructor.

  4. Define an initClass() method to initialize the type information (see Section 7.3, “Initializing the Node-Kit Class”).

  5. Define a constructor (see Section 7.4, “Defining the Constructor”).

  6. Implement actions, if necessary. Typically, you won't need to implement additional actions for a node kit. You may, however, want to redefine the setDefaultOnNonWritingFields() method (see Section 7.8, “Writing Information About Parts”).

  7. Implement a copy() method if the node kit contains any non-field instance data (see Chapter 2).

  8. Implement an affectsState() method if this method cannot be inherited from the parent class (see Chapter 2).