SoBaseKit.h

/*=======================================================================
 * Copyright 1991-1996, Silicon Graphics, Inc.
 * ALL RIGHTS RESERVED
 *
 * UNPUBLISHED -- Rights reserved under the copyright laws of the United
 * States.   Use of a copyright notice is precautionary only and does not
 * imply publication or disclosure.
 *
 * U.S. GOVERNMENT RESTRICTED RIGHTS LEGEND:
 * Use, duplication or disclosure by the Government is subject to restrictions
 * as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights
 * in Technical Data and Computer Software clause at DFARS 252.227-7013 and/or
 * in similar or successor clauses in the FAR, or the DOD or NASA FAR
 * Supplement.  Contractor/manufacturer is Silicon Graphics, Inc.,
 * 2011 N. Shoreline Blvd. Mountain View, CA 94039-7311.
 *
 * THE CONTENT OF THIS WORK CONTAINS CONFIDENTIAL AND PROPRIETARY
 * INFORMATION OF SILICON GRAPHICS, INC. ANY DUPLICATION, MODIFICATION,
 * DISTRIBUTION, OR DISCLOSURE IN ANY FORM, IN WHOLE, OR IN PART, IS STRICTLY
 * PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SILICON
 * GRAPHICS, INC.
**=======================================================================*/
/*=======================================================================
** Author      : Paul Isaacs (MMM yyyy)
** Modified by : Thad Beier (MMM yyyy)
**=======================================================================*/
/*=======================================================================
 *** THE CONTENT OF THIS WORK IS PROPRIETARY TO FEI S.A.S, (FEI S.A.S.),            ***
 ***              AND IS DISTRIBUTED UNDER A LICENSE AGREEMENT.                     ***
 ***                                                                                ***
 ***  REPRODUCTION, DISCLOSURE,  OR USE,  IN WHOLE OR IN PART,  OTHER THAN AS       ***
 ***  SPECIFIED  IN THE LICENSE ARE  NOT TO BE  UNDERTAKEN  EXCEPT WITH PRIOR       ***
 ***  WRITTEN AUTHORIZATION OF FEI S.A.S.                                           ***
 ***                                                                                ***
 ***                        RESTRICTED RIGHTS LEGEND                                ***
 ***  USE, DUPLICATION, OR DISCLOSURE BY THE GOVERNMENT OF THE CONTENT OF THIS      ***
 ***  WORK OR RELATED DOCUMENTATION IS SUBJECT TO RESTRICTIONS AS SET FORTH IN      ***
 ***  SUBPARAGRAPH (C)(1) OF THE COMMERCIAL COMPUTER SOFTWARE RESTRICTED RIGHT      ***
 ***  CLAUSE  AT FAR 52.227-19  OR SUBPARAGRAPH  (C)(1)(II)  OF  THE RIGHTS IN      ***
 ***  TECHNICAL DATA AND COMPUTER SOFTWARE CLAUSE AT DFARS 52.227-7013.             ***
 ***                                                                                ***
 ***                   COPYRIGHT (C) 1996-2020 BY FEI S.A.S,                        ***
 ***                        BORDEAUX, FRANCE                                        ***
 ***                      ALL RIGHTS RESERVED                                       ***
**=======================================================================*/
/*=======================================================================
** Modified by : VSG (MMM YYYY)
**=======================================================================*/
 
 
#ifndef  _SO_BASE_KIT_
#define  _SO_BASE_KIT_
 
#include <Inventor/misc/SoChildList.h>
#include <Inventor/fields/SoFieldData.h>
#include <Inventor/nodes/SoNode.h>
#include <Inventor/fields/SoSFName.h>
#include <Inventor/fields/SoSFBool.h>
#include <Inventor/nodes/SoNode.h>
#include <Inventor/nodekits/SoNodekitParts.h>
#include <Inventor/nodekits/SoSubKit.h>
#include <Inventor/SoNodeKitPath.h>
#include <Inventor/SbViewportRegion.h>
 
class SoSeparator;
class SbBox3f;
class SbDict;
class SoGroup;

//    Class: SoBaseKit -- 
//
//  This is the base class for all node kits.
//
// NOTE TO DEVELOPERS:
//     For info about the structure of SoBaseKit:
//     [1] compile: /usr/share/src/Inventor/samples/ivNodeKitStructure
//     [2] type:    ivNodeKitStructure SoBaseKit.
//     [3] The program prints a diagram of the scene graph and a table with 
//         information about each part.
//
//  It contains only 'this' and a callbackList beneath it.
//  It's catalog is made to describe the following structure:
//
//                            this
//                              |
//                            "callbackList"
//

class  SoBaseKit : public SoNode, public SoGetView {
 
  // Instead of calling SO_KIT_HEADER(className) here,
  // which is the norm for all nodekits, explicitly write the contents
  // of that macro, so as to expose the base class virtual function
  // getNodekitCatalog for the C-api...
  //
  SO_NODE_HEADER(SoBaseKit);
 
public:
  SoSFBool boundingBoxIgnoring;
 
 private:
  /* design of this class */
  static SoNodekitCatalog *nodekitCatalog;
  /* parent design */
  static const SoNodekitCatalog **parentNodekitCatalogPtr;
 
 public:
  static const SoNodekitCatalog *getClassNodekitCatalog();

  /* Returns an SoNodekitCatalog for the node */
  virtual const SoNodekitCatalog *getNodekitCatalog() const;
  // ...end of contents of SO_KIT_HEADER
 
 private:
  static const SoNodekitCatalog **getClassNodekitCatalogPtr();
 
  // Define fields for the new parts of the kit...
  SO_KIT_CATALOG_ENTRY_HEADER(callbackList);
 
 public:

  SoBaseKit();

  virtual SoNode *getPart( const SbName &partName, SbBool makeIfNeeded );

  template<typename PartType>
  PartType* getPart( const SbName& partName )
  {
    SoNode* part = getPart( partName, TRUE );
    #if defined(_DEBUG)
    part = typeCheck<PartType>( partName, part );
    #endif
    return static_cast<PartType*>(part);
  }

  template<typename PartType>
  PartType* checkPart( const SbName& partName )
  {
    SoNode* part = getPart( partName, FALSE );
    #if defined(_DEBUG)
    part = typeCheck<PartType>( partName, part );
    #endif
    return static_cast<PartType*>(part);
  }

  SbString getPartString( const SoBase *part );
                     
                     
  virtual SoNodeKitPath *createPathToPart( const SbName &partName, 
                                           SbBool makeIfNeeded, const SoPath *pathToExtend = NULL );
                   
  virtual SbBool setPart( const SbName &partName, SoNode *newPart );

  SoNONUNICODE SbBool set(char *nameValuePairListString);

  SbBool set( const SbString& nameValuePairListString);

  SoNONUNICODE SbBool set(const char *partNameString, const char *parameterString);

  SbBool set( const SbString& partNameString, const SbString& parameterString);

  static void   setSearchingChildren( SbBool newVal );

  static SbBool isSearchingChildren() { return searchingChildren; }
 
 private:

  inline virtual SbBool isBoundingBoxIgnoring() const
  { return boundingBoxIgnoring.getValue(); }
 
  virtual void doAction( SoAction *action );
  // These functions implement all actions for nodekits.
  virtual void callback( SoCallbackAction *action );
  virtual void GLRender( SoGLRenderAction *action );
  virtual void getBoundingBox( SoGetBoundingBoxAction *action );
  virtual void getMatrix(SoGetMatrixAction *action );
  virtual void handleEvent( SoHandleEventAction *action );
  virtual void rayPick( SoRayPickAction *action );
  virtual void search( SoSearchAction *action );
  virtual void write( SoWriteAction *action );
  virtual void getPrimitiveCount (SoGetPrimitiveCountAction *action);
 
 private:
  static void initClass();
  static void exitClass();
 
  // Convenient method to remove warning (conversion from const char* to char*)
  // in set("...", "...");
  // So set(const char*, const char*) replaces set(char*, char*) and 
  // set(char*, char*) becomes deprecated/internal
  SbBool set(char *partNameString, char *parameterString) 
    { return set((const char*)partNameString, (const char*)parameterString); };
 
  // Returns pointer to children
  virtual SoChildList *getChildren() const;
 
  static SoNode *typeCheck( const SbName &partName, const SoType &partType, 
                            SoNode *node );

  template<typename PartType>
  static SoNode* typeCheck( const SbName& partName, SoNode* node )
  {
    return typeCheck( partName, PartType::getClassTypeId(), node );
  }
 
  void printDiagram();
  void printSubDiagram( const SbName &rootName, int level );
  void printTable();
 
  // Overrides the default method to use countMyFields() instead of 
  // the regular SoFieldData writing mechanism.
  virtual void        addWriteReference(SoOutput *out,
                                        SbBool isFromField = FALSE);
 
  friend class SoNodekitCatalogEntry;
  friend class SoNodekitParts;
  friend class SoV1BaseKit;
 
  // This returns TRUE if the nodekit intends to write out.
  //   [a] call shouldWrite(). If TRUE, trivial return.
  //   [b] If the kit thinks it shouldn't write, it first does a recursive
  //       call to its children.  If any children must write, then so must
  //       the kit.
  //   [c] If kit has changed its mind because of [b], then add a writeRef.
  //
  //   [d] If kit should not write, it will delete the fieldDataForWriting, 
  //       since there will no writing pass applied to take care of this.
  SbBool forceChildDrivenWriteRefs( SoOutput *out );
 
  // enable/disable callbacks.
  static void enableNotification(SbBool);
  static SbBool isEnabledNotification();
 
  virtual SbBool setAnyPart( const SbName &partName, SoNode *from, SbBool anyPart = TRUE );
 
  SoNode *internalGetAnyPart( const SbName &partName, SbBool makeIfNeeded, 
    SbBool leafCheck = FALSE, SbBool publicCheck = FALSE );
 
  // Internal child management following inheritance of classes.
  virtual void internalRemoveChild( int index )                          { removeChild(index); }
  virtual void internalRemoveChild( SoNode *child  )                     { removeChild(findChild(child)); }
  virtual void internalRemoveAllChildren()                               { removeAllChildren(); }
  virtual void internalAddChild( SoNode *child )                         { addChild(child); }
  virtual int internalFindChild( const SoNode *child ) const             { return findChild(child); }
  virtual void internalInsertChild( SoNode *child, int newChildIndex )   { insertChild(child, newChildIndex); }
  virtual SoNode *internalGetChild( int index) const                     { return getChild(index); }
  virtual void internalReplaceChild( int index, SoNode *newChild)        { replaceChild(index, newChild); }
  virtual void internalReplaceChild( SoNode *oldChild, SoNode *newChild) { replaceChild(oldChild,newChild); }
 
  // Redefines this to add this node and all part nodes to the dictionary
  virtual SoNode *    addToCopyDict() const;
 
  // Copies the contents of the given nodekit into this instance
  virtual void        copyContents(const SoFieldContainer *fromFC,
                                   SbBool copyConnections);
 
 private:
 
  SoChildList *children;
 
  // Returns the containerNode within the SoNodeKitListPart given 
  // by listName.
  SoGroup *getContainerNode( const SbName &listName,
                             SbBool makeIfNeeded = TRUE );

  virtual SoNode *getAnyPart( const SbName &partName, SbBool makeIfNeeded, 
                              SbBool leafCheck = FALSE, SbBool publicCheck = FALSE );

  template<typename PartType>
  PartType* getAnyPart( const SbName& partName )
  {
    SoNode* part = getAnyPart( partName, TRUE, FALSE, FALSE );
    #if defined(_DEBUG)
    part = typeCheck<PartType>( partName, part );
    #endif
    return static_cast<PartType*>(part);
  }

  template<typename PartType>
  PartType* checkAnyPart( const SbName& partName )
  {
    SoNode* part = getAnyPart( partName, FALSE, FALSE, FALSE );
    #if defined(_DEBUG)
    part = typeCheck<PartType>( partName, part );
    #endif
    return static_cast<PartType*>(part);
  }
 
  virtual SoNodeKitPath *createPathToAnyPart(const SbName &partName, 
                                             SbBool makeIfNeeded, 
                                             SbBool leafCheck = FALSE, SbBool publicCheck = FALSE,
                                             const SoPath *pathToExtend = NULL );
 
  // parts list.
  SoNodekitParts      *nodekitPartsList;
 
  // called during construction to create parts list
  void createNodekitPartsList();
  // called during construction to create any parts that are created by
  // default (such as the cube in the SoCubeKit)
  virtual void createDefaultParts();
 
  // Return the node's partsList
  const SoNodekitParts *getNodekitPartsList() const 
    { return nodekitPartsList; };
 
  // Prints an Error when there's trouble building a catalog.
  void catalogError();
 
  // detach/attach any sensors, callbacks, and/or field connections.
  // Called by:            start/end of SoBaseKit::readInstance
  // and on new copy by:   start/end of SoBaseKit::copyContents.
  // Classes that redefine must call setUpConnections(TRUE,TRUE) 
  // at the end of constructor to add their own connections to the ones already
  // connected by the base classes.
  // The doItAlways flag can force the method to do the work.
  // But if (doItAlways == FALSE && onOff == connectionsSetUp), then
  // the method will return immediately without doing anything.
  // Returns the state of the node when this was called.
  virtual SbBool setUpConnections( SbBool onOff, SbBool doItAlways = FALSE );
  SbBool connectionsSetUp;
 
  // Reads in from file. Takes care of setting parts and stuff.
  virtual SbBool readInstance(SoInput *in, unsigned short flags);
    
  // This is called during countMyFields() method. It calls setDefault()
  // on those fields we do not wish to write out. setDefault does not change
  // the field value, but it sets a flag indicating that the field should
  // not get written by this node.
  // Fields that we do not write are [a] parts that are NULL and are defined
  // in the catalog to be NULL by default. [b] non-leaf parts for which
  // isNodeFieldValuesImportant() is FALSE.
  // [c] leaf parts that are empty groups, empty separators, 
  // [d] leaf parts that are empty lists (but they must have group or 
  //     separator container nodes.
  virtual void setDefaultOnNonWritingFields();
 
  // This is called during addWriteReference() to write the fields.
  // It sometimes treats fields for parts of the nodekit in a special way.
  // Under normal circumstances, they write like other fields.
  // The special case is when a part-field has a non-NULL value, but has 
  // also been set to default, indicating that we would rather not write it.
  // If the part is a regular node, we give it a field-connection style
  // write ref.  So it only writes if some other instances of the node forces
  // a write.
  // If the part is a nodekit, then we additionally write ref the fields of 
  // the nodekit, using this same method.
  // Later, in the WRITE stage, the kit-part will be written if at least
  // one of its fields or ancestor parts has shouldWrite() ==TRUE.
  // This way, if a nodekit part or any of its ancestors has non-NULL fields,
  // it will later be forced to write, even though it has been set to default.
  // Example: 
  //   Parent draggers attempt not to write out child draggers.
  //   But the parentDragger must at least traverse the childDragger to see 
  //   if any of the part geometry has been changed from its default. Such 
  //   changes must be written to file.
  void countMyFields(SoOutput *out);
 
  virtual ~SoBaseKit();
 
  static SbBool m_enableBaseKitNotification;
 
private:
 
  // end basekit writing.
  void endWrite( SoOutput* out );
 
private:
  void skipWhiteSpace(char *&string);
 
  // Returns FALSE if every field has either [a] hasDefaultValue() == TRUE or
  // [b] isDefault() == TRUE
  SbBool isNodeFieldValuesImportant( SoNode *n );
 
  // This creates a copy of fieldData with a few changes that make
  // it write out 'prettier'
  void createFieldDataForWriting();
 
  // Used to store field data during writing. Need this because a temporary
  // version of fieldData is made that differs from the real thing.
  SoFieldData *fieldDataForWriting;
 
  // This list contains pointers to fields whose default 
  // flag has been changed so they won't write out.
  
  SbPList savedList;
 
  // Called by the readInstance routine...
  SbBool readMyFields(SoInput *in, SoFieldData *&unknownFieldData );
 
  // Called by write() after the (virtual) setDefaultOnNonWritingNodes() 
  // method.  This method looks at the part fields which have isDefault()
  // set to TRUE.    This method will setDefault(FALSE) on any part fields
  // that MUST write.   
  //     This happens when the part-field is for a part whose parent 
  //     is going to write out anyway. Therefore, it will appear in file as 
  //     a node within this kit, so we better write out the part field to 
  //     explain where the node belongs in the kit.
  void undoSetDefaultOnFieldsThatMustWrite();
 
  // Only nodekits themselves can access the private children.
  int  getNumChildren() const { return (children->getLength()); }
  void removeChild( int index );
  void removeChild( SoNode *child  ) { removeChild(findChild(child)); }
  void removeAllChildren();
  void addChild( SoNode *child );
  int  findChild( const SoNode *child ) const;
  void insertChild( SoNode *child, int newChildIndex );
  SoNode *getChild( int index) const { return (*children)[index]; }
  void replaceChild( int index, SoNode *newChild);
  void replaceChild( SoNode *oldChild, SoNode *newChild)
    { replaceChild(findChild(oldChild),newChild); }
 
  static SbBool searchingChildren;
};
 
// Macro for getting at parts without doing type casting yourself:
// for example, the code:
//  xf = (SoTransform *) myKit->getPart("transform",
//                                      SoTransform::getClassTypeId(), TRUE);
// becomes:
//  xf = SO_GET_PART( myKit, "transform", SoTransform );
//      
// The macro SO_CHECK_PART will not build the part if it is not already in the
// kit, since it sends 'FALSE' as the 'makeIfNeeded' argument.
//
// CAUTION:  These macros will not work in the C-api, and nothing will be
//           gained from making them.  So, don't make them.
 
 
#if defined(_DEBUG)
#define SO_GET_PART( kitContainingPart, partName, partClassName )              \
        ((partClassName *) SoBaseKit::typeCheck( partName,                     \
                               partClassName::getClassTypeId(),               \
                               kitContainingPart->getPart( partName, TRUE )))
 
#define SO_CHECK_PART( kitContainingPart, partName, partClassName )            \
        ((partClassName *) SoBaseKit::typeCheck( partName,                    \
                               partClassName::getClassTypeId(),               \
                               kitContainingPart->getPart( partName, FALSE )))
 
#define SO_GET_ANY_PART( kitContainingPart, partName, partClassName )         \
        ((partClassName *) SoBaseKit::typeCheck( partName,                    \
                partClassName::getClassTypeId(),                              \
                kitContainingPart->getAnyPart( partName, TRUE, FALSE, FALSE )))
 
#define SO_CHECK_ANY_PART( kitContainingPart, partName, partClassName )       \
        ((partClassName *) SoBaseKit::typeCheck( partName,                    \
                partClassName::getClassTypeId(),                              \
                kitContainingPart->getAnyPart( partName, FALSE, FALSE, FALSE )))
#else
 
#define SO_GET_PART( kitContainingPart, partName, partClassName )             \
        ((partClassName *) kitContainingPart->getPart( partName, TRUE ))
#define SO_CHECK_PART( kitContainingPart, partName, partClassName )           \
        ((partClassName *) kitContainingPart->getPart( partName, FALSE ))
#define SO_GET_ANY_PART( kitContainingPart, partName, partClassName )        \
        ((partClassName *) kitContainingPart->getAnyPart( partName, TRUE,    \
                                                          FALSE, FALSE ))
#define SO_CHECK_ANY_PART( kitContainingPart, partName, partClassName )      \
        ((partClassName *) kitContainingPart->getAnyPart( partName, FALSE,   \
                                                          FALSE, FALSE ))
#endif
 
#endif  /* _SO_BASE_KIT_ */