Open Inventor Reference
Macros
SoSubKit.h File Reference
#include <Inventor/nodekits/SoBaseKit.h>
#include <Inventor/nodes/SoNode.h>
#include <Inventor/fields/SoSFNode.h>
#include <Inventor/nodekits/SoNodekitCatalog.h>
#include <Inventor/nodekits/SoNodeKitListPart.h>

Go to the source code of this file.

Macros

#define SO__KIT_CATALOG_HEADER(className)
 There is a cycle of include files between SoBaseKit.h and SoSubKit.h SoBaseKit.h must be included before SO_SUB_KIT is defined.
 
#define SO_KIT_HEADER(className)
 
#define SO_KIT_CATALOG_ENTRY_HEADER(partName)
 This defines an SoSFNode field for the catalog part given.
 
#define SO__KIT_CATALOG_VARS(className)
 Macros to be called within the source file for a node subclass:
 
#define SO__KIT_CATALOG_METHODS(className)
 This implements the methods defined in SO__KIT_CATALOG_HEADER.
 
#define SO_KIT_SOURCE(className)
 These include all the definitions required at file scope.
 
#define SO__KIT_INIT_CLASS(className, classPrintName, parentClass)
 Internal initialization macros.
 
#define SO_KIT_INIT_CLASS(className, parentClass, parentPrintClass)
 This calls SO_NODE_INIT_CLASS to initialize the type identifier variables defined in SO_KIT_HEADER.
 
#define SO__KIT_INHERIT_CATALOG(className)
 This is an internal macro.
 
#define SO_KIT_CONSTRUCTOR(className)
 These are here to complete the set of subclassing macros for nodekits.
 
#define SO_KIT_IS_FIRST_INSTANCE()    SO_NODE_IS_FIRST_INSTANCE()
 
#define SO_KIT_ADD_FIELD(fieldName, defValue)    SO_NODE_ADD_FIELD(fieldName,defValue)
 
#define SO_KIT_DEFINE_ENUM_VALUE(enumType, enumValue)    SO_NODE_DEFINE_ENUM_VALUE(enumType,enumValue)
 
#define SO_KIT_SET_MF_ENUM_TYPE(fieldName, enumType)    SO_NODE_SET_MF_ENUM_TYPE(fieldName, enumType)
 
#define SO_KIT_SET_SF_ENUM_TYPE(fieldName, enumType)    SO_NODE_SET_SF_ENUM_TYPE(fieldName, enumType)
 
#define SO_KIT_ADD_CATALOG_ENTRY(partName, partClassName, nullByDefault, parentName, rightName, isPublicPart)
 This adds the info for a single new part to the SoNodekitCatalog.
 
#define SO_KIT_ADD_CATALOG_ABSTRACT_ENTRY(partName, partClassName, defaultPartClassName, nullByDefault, parentName, rightName, isPublicPart)
 This adds the info for a new part to the SoNodekitCatalog.
 
#define SO_KIT_ADD_CATALOG_LIST_ENTRY(partName, listContainerClassName, nullByDefault, parentName, rightName, listItemClassName, isPublicPart)
 This adds the info for a new part to the SoNodekitCatalog.
 
#define SO_KIT_ADD_LIST_ITEM_TYPE(partName, newListItemClassName)
 Assuming that the part 'partName' was already put in the nodekit catalog, using the macro SO_KIT_ADD_CATALOG_LIST_ENTRY(...) this macro will add 'newListItemClassName' to its listItemTypes.
 
#define SO_KIT_CHANGE_ENTRY_TYPE(partName, newPartClassName, newDefaultPartClassName)
 This changes the class of a part in the nodekit catalog.
 
#define SO_KIT_CHANGE_NULL_BY_DEFAULT(partName, newNullByDefault)
 This changes whether or not a part is NULL by default.
 
#define SO_KIT_INIT_INSTANCE()
 This must be called within the constructor of every class of nodekit.
 

Macro Definition Documentation

◆ SO__KIT_CATALOG_HEADER

#define SO__KIT_CATALOG_HEADER (   className)
Value:
private: \
static SoNodekitCatalog *nodekitCatalog; /* design of this class */ \
static const SoNodekitCatalog **parentNodekitCatalogPtr;/* parent design */\
public: \
static const SoNodekitCatalog *getClassNodekitCatalog() \
{ return nodekitCatalog; } \
/* Returns an SoNodekitCatalog for the node */ \
virtual const SoNodekitCatalog *getNodekitCatalog() const; \
protected: \
static const SoNodekitCatalog **getClassNodekitCatalogPtr() \
{ return (const SoNodekitCatalog **)&nodekitCatalog; }
SoNodekitCatalog
Nodekit catalog class.
Definition SoNodekitCatalog.h:185

Otherwise, SoBaseKit.h will not compile. Macros to be called within the class definition header for a SoBaseKit subclass: This defines a catalog describing the arrangement of the subgraph for instances of this class

Definition at line 130 of file SoSubKit.h.

◆ SO__KIT_CATALOG_METHODS

#define SO__KIT_CATALOG_METHODS (   className)
Value:
const SoNodekitCatalog * \
className::getNodekitCatalog() const \
{ \
return nodekitCatalog; \
}

Definition at line 179 of file SoSubKit.h.

◆ SO__KIT_CATALOG_VARS

#define SO__KIT_CATALOG_VARS (   className)
Value:
SoNodekitCatalog *className::nodekitCatalog = NULL; \
const SoNodekitCatalog **className::parentNodekitCatalogPtr = NULL

This declares the static variables defined in SO__KIT_CATALOG_HEADER.

Definition at line 170 of file SoSubKit.h.

◆ SO__KIT_INHERIT_CATALOG

#define SO__KIT_INHERIT_CATALOG (   className)
Value:
{ \
/* get a copy of the catalog from the base class */ \
int _value_false= 0; \
do { \
if (firstInstance) { \
if (parentNodekitCatalogPtr == nullptr) { /* only true in SoBaseKit */ \
nodekitCatalog = new SoNodekitCatalog; \
} \
else { \
nodekitCatalog \
=(*parentNodekitCatalogPtr)->clone(SoType::fromName(SO__QUOTE(className))); \
} \
} \
} while (_value_false); \
}
SO__QUOTE
#define SO__QUOTE(str)
Handy macros.
Definition SoBasic.h:69
SoNodekitCatalog::clone
SoNodekitCatalog * clone(SoType typeOfThis) const
Make a new identical copy, but you must give the node type for 'this' (where 'this' is the top level ...
SoType::fromName
static SoType fromName(SbName name)
Returns the type associated with the given name.

It initializes the SoNodekitCatalog structure defined in SO__KIT_CATALOG_HEADER. This macro is automatically called as part of SO_KIT_CONSTRUCTOR

This and other macros rely on static member variable "firstInstance" from SoSubNode.h

Definition at line 238 of file SoSubKit.h.

◆ SO__KIT_INIT_CLASS

#define SO__KIT_INIT_CLASS (   className,
  classPrintName,
  parentClass 
)
Value:
{ \
SO__NODE_INIT_CLASS(className,classPrintName,parentClass); \
int _value_false= 0; \
do { \
parentNodekitCatalogPtr = parentClass::getClassNodekitCatalogPtr(); \
} while (_value_false); \
}

Definition at line 201 of file SoSubKit.h.

◆ SO_KIT_ADD_CATALOG_ABSTRACT_ENTRY

#define SO_KIT_ADD_CATALOG_ABSTRACT_ENTRY (   partName,
  partClassName,
  defaultPartClassName,
  nullByDefault,
  parentName,
  rightName,
  isPublicPart 
)
Value:
SO_KIT_ADD_FIELD(partName,(NULL)); \
if (firstInstance && !nodekitCatalog->addEntry(SO__QUOTE(partName), \
SoType::fromName(SO__QUOTE(partClassName)), \
SoType::fromName(SO__QUOTE(defaultPartClassName)), nullByDefault,\
SO__QUOTE(parentName), SO__QUOTE(rightName), FALSE, \
SoType::badType(), SoType::badType(), isPublicPart )) \
catalogError()
FALSE
#define FALSE
Definition SbBasic.h:79
SO_KIT_ADD_FIELD
#define SO_KIT_ADD_FIELD(fieldName, defValue)
Definition SoSubKit.h:266
SoType::badType
static SoType badType()
Returns an always-illegal type. Useful for returning errors.

'partName' may be of an abstract node type.

The parameters are as follows: 

 partName:      same as SO_KIT_ADD_CATALOG_ENTRY
 partClassName: same as SO_KIT_ADD_CATALOG_ENTRY, except that
                abstract node classes are acceptable.

 defaultPartClassName:   If the nodekit is asked to construct this part,
                     using getPart, then the 'defaultPartClassName' will
                     specify what type of node to build.
                     This may NOT be an abstract class.
                     This MUST be a subclass of 'partClassName'

 nullByDefault: same as SO_KIT_ADD_CATALOG_ENTRY
 parentName:    same as SO_KIT_ADD_CATALOG_ENTRY
 rightName:     same as SO_KIT_ADD_CATALOG_ENTRY
 isPublicPart:  same as SO_KIT_ADD_CATALOG_ENTRY

For example,

SO_KIT_ADD_CATALOG_ABSTRACT_ENTRY(light,SoLight, SoDirectionalLight, TRUE, this,, TRUE);

makes a part node refered to as "light". When calling setPart, any node that is a subclass of light can be used (e.g., SoDirectionalLight, SoSpotLight, SoPointLight ) However, if the user asks for the node and it has not been created yet, (this happens, for example, in the case where there is currently no 'light' and the user calls SO_GET_PART( myKit, "light", SoLight ), then an SoDirectionalLight will be created and returned.

Definition at line 387 of file SoSubKit.h.

◆ SO_KIT_ADD_CATALOG_ENTRY

#define SO_KIT_ADD_CATALOG_ENTRY (   partName,
  partClassName,
  nullByDefault,
  parentName,
  rightName,
  isPublicPart 
)
Value:
SO_KIT_ADD_FIELD(partName,(NULL)); \
if (firstInstance && !nodekitCatalog->addEntry(SO__QUOTE(partName), \
SoType::fromName(SO__QUOTE(partClassName)), \
SoType::fromName(SO__QUOTE(partClassName)), nullByDefault,\
SO__QUOTE(parentName), \
SO__QUOTE(rightName), FALSE, SoType::badType(), \
SoType::badType(), isPublicPart )) \
catalogError()

The parameters are as follows: 

 partName:     the name used to refer to this part in nodekitCatalog
               NOTE: do not make an entry for 'this'.
                     'this' is implicitly the top of the tree when
                     building the catalog.
 partClassName: the class of node to which this part belongs.

 nullByDefault: If TRUE, the part is not created during the constructor.
                (which is the usual case.) 
                If FALSE, then it will be automatically created by the 
                constructor during the call to the 
                macro SO_KIT_INIT_INSTANCE()

 parentName:   the partName of the parent of this part within
               the nodekitCatalog
               NOTE: if this node is to be a direct descendant of 
                     'this', then parentName should be given as "this"

 rightName:    the partName of the right sibling of this part
               within the nodekitCatalog.
               NOTE: if this part is to be the rightmost child, then
               the rightName should be given as "" (the empty string).

 isPublicPart: can a user receive a pointer to this part through
               getPart?  If a part is not a leaf, this property is 
               irrelevant (non-leaf parts are always private ). But if 
               it is a leaf, the user's access can be stopped through 
               this field.

For example,

SO_KIT_ADD_CATALOG_ENTRY(material,SoMaterial,TRUE,this,, TRUE); 

  adds to the catalog a part named 'material.'  This part will be an
  SoMaterial node that is NOT created by default. It will be a direct 
  child of the nodekit part 'this.' It will be installed as the 
  rightmost child below 'this'.
  Since it is public, a user will be able to receive a pointer to this 
  part by calling getPart().

Another example: if we are making a catalog for a class SoBirdKit, and we have already created the class SoWingKit, then the following macros: SO_KIT_ADD_CATALOG_ENTRY(mainSep,SoSeparator,TRUE,this,, FALSE); SO_KIT_ADD_CATALOG_ENTRY(rightW,SoWingKit,TRUE,mainSep,, TRUE); SO_KIT_ADD_CATALOG_ENTRY(leftW,SoWingKit,TRUE,mainSep,rightWing, TRUE); describe a catalog with this structure: 

          this
            |
         mainSep
            |
      -------------
      |           |
  leftW        rightW

Definition at line 338 of file SoSubKit.h.

◆ SO_KIT_ADD_CATALOG_LIST_ENTRY

#define SO_KIT_ADD_CATALOG_LIST_ENTRY (   partName,
  listContainerClassName,
  nullByDefault,
  parentName,
  rightName,
  listItemClassName,
  isPublicPart 
)
Value:
SO_KIT_ADD_FIELD(partName,(NULL)); \
if (firstInstance && !nodekitCatalog->addEntry(SO__QUOTE(partName), \
SoNodeKitListPart::getClassTypeId(), \
SoNodeKitListPart::getClassTypeId(), nullByDefault, \
SO__QUOTE(parentName), SO__QUOTE(rightName), TRUE, \
SoType::fromName(SO__QUOTE(listContainerClassName)), \
SoType::fromName(SO__QUOTE(listItemClassName)), isPublicPart)) \
catalogError()
TRUE
#define TRUE
Definition SbBasic.h:76
SoFieldContainer::getClassTypeId
static SoType getClassTypeId()
Returns the type of this class.
Definition SoFieldContainer.h:97

'partName' refers to a part that is a LIST.

Any list in a nodekit will automatically be a node of type SoNodeKitListPart. These nodes act like subclasses of group but enforce type checking when you add children to them.

The parameters you specify will determine [a] what kind of group node holds the children (SoGroup, SoSeparator, SoSwitch, etc). [b] what single class of node will be allowable as children in the list.

Subsequent calls to SO_KIT_ADD_LIST_ITEM_TYPE allow you to add other classes of nodes that will be allowable children for the list.

The parameters are as follows: 

 partName:     Same as in SO_KIT_ADD_CATALOG_ENTRY
 listContainerClassName:
               What class will be used to hold the children in the list?
               NOTE: since this is going to have children, it MUST
                     be a subclass of SoGroup, such as SoSeparator
                     or SoSwitch.
 nullByDefault:same as SO_KIT_ADD_CATALOG_ENTRY
 parentName:   Same as in SO_KIT_ADD_CATALOG_ENTRY
 rightName:    Same as in SO_KIT_ADD_CATALOG_ENTRY

 listItemClassName: The name of the class of node that may appear in 
                    the list. Any node class is legal here.
 isPublicPart: Same as in SO_KIT_ADD_CATALOG_ENTRY

For example,

SO_KIT_ADD_CATALOG_LIST_ENTRY(subCubes,SoSeparator,TRUE,this,,SoCube, TRUE );

makes a list that may contain only SoCubes. An SoSeparator will be used to contain this list of cubes.

Definition at line 438 of file SoSubKit.h.

◆ SO_KIT_ADD_FIELD

#define SO_KIT_ADD_FIELD (   fieldName,
  defValue 
)     SO_NODE_ADD_FIELD(fieldName,defValue)

Definition at line 266 of file SoSubKit.h.

◆ SO_KIT_ADD_LIST_ITEM_TYPE

#define SO_KIT_ADD_LIST_ITEM_TYPE (   partName,
  newListItemClassName 
)
Value:
if (firstInstance) nodekitCatalog->addListItemType(SO__QUOTE(partName), \
SoType::fromName(SO__QUOTE(newListItemClassName)) )

This means that nodes of type 'newListItemClassName' will be permitted in the list, as well as any other parts that are already permitted.

Example: The macro: SO_KIT_ADD_CATALOG_LIST_ENTRY(myList, SoSeparator, TRUE, myListParent, , SoCube, TRUE ) creates a list called "myList" that accepts cubes. calling: myKit->addChild( "myList", myCube ); will work just fine, but: myKit->addChild( "myList", mySphere ); will produce an error. If, however, a subsequent call is made to: SO_KIT_ADD_LIST_ITEM_TYPE( myList, SoSphere ); then both calls to addChild will be acceptable

partName: Name of the part to add the listItemType to newListItemClassName: Name of the class to add to partName's listItemTypes

Definition at line 475 of file SoSubKit.h.

◆ SO_KIT_CATALOG_ENTRY_HEADER

#define SO_KIT_CATALOG_ENTRY_HEADER (   partName)
Value:
protected: \
SoSFNode partName
SoSFNode
Field containing a pointer to a node.
Definition SoSFNode.h:92

The field will always be a (protected) node-pointer field. It will keep track of which (hidden) child is which part.

Definition at line 155 of file SoSubKit.h.

◆ SO_KIT_CHANGE_ENTRY_TYPE

#define SO_KIT_CHANGE_ENTRY_TYPE (   partName,
  newPartClassName,
  newDefaultPartClassName 
)
Value:
if (firstInstance) nodekitCatalog->narrowTypes(SO__QUOTE(partName), \
SoType::fromName(SO__QUOTE(newPartClassName)), \
SoType::fromName(SO__QUOTE(newDefaultPartClassName)))

Both the newPartClassname and the newDefaultPartClassName must be given.

Used when creating catalogs for subclasses of other nodekits.

The parameters are as follows: 

 partName:           Same as SO_KIT_ADD_CATALOG_ENTRY

 newPartClassName:   The name of the new node class describing this part.

 newDefaultPartClassName:   
                     The new defaultPartClassName.  If asked to build a
                     new node for this part, a node of type 
                     newDefaultPartClassName will be built.

For example,

The part "shape" is entered in the nodekit catalog as a part for the SoShapeKit using the following macro call in the constructor:

SO_KIT_ADD_CATALOG_ABSTRACT_ENTRY(shape, SoShape, SoCube, FALSE, shapeSeparator, , TRUE );

If we created a subclass of SoShape, SoVertexShapeKit, then the following command might be used in the SoVertexShapeKit constructor:

SO_KIT_CHANGE_ENTRY_TYPE( shape, SoVertexShape, SoFaceSet );

This would allow any subclass of SoVertexShape to be inserted as the part "shape." If the SoVertexShapeKit were asked to build the part "shape", it would create it as an SoFaceSet, the default (and non-abstract) type.

Continuing further, the class SoFaceSetKit, subclassed from SoVertexShapeKit, might contain this command in its constructor:

SO_KIT_CHANGE_ENTRY_TYPE(shape,SoFaceSet, SoFaceSet );

This class would allow one and only one type of node for "shape", and that is the type SoFaceSet.

Definition at line 521 of file SoSubKit.h.

◆ SO_KIT_CHANGE_NULL_BY_DEFAULT

#define SO_KIT_CHANGE_NULL_BY_DEFAULT (   partName,
  newNullByDefault 
)
Value:
if (firstInstance) nodekitCatalog->setNullByDefault(SO__QUOTE(partName), \
newNullByDefault)

If TRUE, the part is NULL by default. If FALSE, the part is always created during the constructor for the nodekit that uses this catalog. In this case, construction occurs during the call to SO_KIT_INIT_INSTANCE().

Definition at line 535 of file SoSubKit.h.

◆ SO_KIT_CONSTRUCTOR

#define SO_KIT_CONSTRUCTOR (   className)
Value:
SO_NODE_CONSTRUCTOR(className); \
SO__KIT_INHERIT_CATALOG(className)
SO_NODE_CONSTRUCTOR
#define SO_NODE_CONSTRUCTOR(className)
This is included at the beginning of a constructor, to do required initializations.
Definition SoSubNode.h:328

They are just stubs to call the SO_NODE equivalents, really.

Definition at line 259 of file SoSubKit.h.

◆ SO_KIT_DEFINE_ENUM_VALUE

#define SO_KIT_DEFINE_ENUM_VALUE (   enumType,
  enumValue 
)     SO_NODE_DEFINE_ENUM_VALUE(enumType,enumValue)

Definition at line 269 of file SoSubKit.h.

◆ SO_KIT_HEADER

#define SO_KIT_HEADER (   className)
Value:
SO_NODE_HEADER(className); \
SO__KIT_CATALOG_HEADER(className)
SO_NODE_HEADER
#define SO_NODE_HEADER(className)
Non-abstract classes have everything abstract classes have, plus a way to create an instance.
Definition SoSubNode.h:170

Definition at line 143 of file SoSubKit.h.

◆ SO_KIT_INIT_CLASS

#define SO_KIT_INIT_CLASS (   className,
  parentClass,
  parentPrintClass 
)
Value:
{ \
SO_NODE_INIT_CLASS(className,parentClass,parentPrintClass); \
int _value_false= 0; \
do { \
parentNodekitCatalogPtr = parentClass::getClassNodekitCatalogPtr(); \
} while (_value_false); \
}

It should be called from within initClass(). The parentClass argument should be the class that this subclass is derived from. The parentNodekitCatalogPtr is also initialized here.

Definition at line 219 of file SoSubKit.h.

◆ SO_KIT_INIT_INSTANCE

#define SO_KIT_INIT_INSTANCE ( )
Value:
createNodekitPartsList(); \
createDefaultParts()

It should be called immediately after the catalog is defined.

It does 2 things: [1] created the nodekitPartsList, which keeps track of which parts have been created. [2] creates all parts that must be created by default (such as the cube in SoCubeKit) as specified by the nullByDefault parameter in the nodekit catalog

Definition at line 551 of file SoSubKit.h.

◆ SO_KIT_IS_FIRST_INSTANCE

#define SO_KIT_IS_FIRST_INSTANCE ( )     SO_NODE_IS_FIRST_INSTANCE()

Definition at line 263 of file SoSubKit.h.

◆ SO_KIT_SET_MF_ENUM_TYPE

#define SO_KIT_SET_MF_ENUM_TYPE (   fieldName,
  enumType 
)     SO_NODE_SET_MF_ENUM_TYPE(fieldName, enumType)

Definition at line 272 of file SoSubKit.h.

◆ SO_KIT_SET_SF_ENUM_TYPE

#define SO_KIT_SET_SF_ENUM_TYPE (   fieldName,
  enumType 
)     SO_NODE_SET_SF_ENUM_TYPE(fieldName, enumType)

Definition at line 275 of file SoSubKit.h.

◆ SO_KIT_SOURCE

#define SO_KIT_SOURCE (   className)
Value:
SO_NODE_SOURCE(className); \
SO__KIT_CATALOG_VARS(className); \
SO__KIT_CATALOG_METHODS(className)
SO_NODE_SOURCE
#define SO_NODE_SOURCE(className)
These include all the definitions required at file scope.
Definition SoSubNode.h:240

Definition at line 192 of file SoSubKit.h.