vtkMRMLNode.h

Go to the documentation of this file.

/*=auto=========================================================================
 
  Portions (c) Copyright 2005 Brigham and Women's Hospital (BWH) All Rights Reserved.
 
  See COPYRIGHT.txt
  or http://www.slicer.org/copyright/copyright.txt for details.
 
  Program:   3D Slicer
  Module:    $RCSfile: vtkMRMLNode.h,v $
  Date:      $Date: 2006/03/19 17:12:29 $
  Version:   $Revision: 1.18 $
 
=========================================================================auto=*/
 
#ifndef __vtkMRMLNode_h
#define __vtkMRMLNode_h
 
// MRML includes
#include "vtkMRML.h"
#include "vtkObserverManager.h"
#include "vtkIdTypeArray.h"
#include "vtkIntArray.h"
 
class vtkMRMLScene;
class vtkStringArray;
 
// VTK includes
#include <vtkObject.h>
#include <vtkSmartPointer.h>
#include <vtkWeakPointer.h>
class vtkCallbackCommand;
 
// Slicer VTK add-on includes
#include <vtkLoggingMacros.h>
 
// Helper macros for simplifying reading, writing, copying, and printing node properties.
#include "vtkMRMLNodePropertyMacros.h"
 
// STD includes
#include <map>
#include <set>
#include <string>
#include <vector>
 
#ifndef vtkSetMRMLObjectMacro
#define vtkSetMRMLObjectMacro(node,value)  {this->MRMLObserverManager->SetObject ( vtkObjectPointer( &(node)), (value) );};
#endif
 
#ifndef vtkSetAndObserveMRMLObjectMacro
#define vtkSetAndObserveMRMLObjectMacro(node,value)  {this->MRMLObserverManager->SetAndObserveObject ( vtkObjectPointer( &(node)), (value) );};
#endif
 
#ifndef vtkSetAndObserveMRMLObjectMacroNoWarning
#define vtkSetAndObserveMRMLObjectMacroNoWarning(node,value)  {this->MRMLObserverManager->SetAndObserveObject ( vtkObjectPointer( &(node)), (value), 0.0, false /* no warning */ );};
#endif
 
#ifndef vtkSetAndObserveMRMLObjectEventsMacro
#define vtkSetAndObserveMRMLObjectEventsMacro(node,value,events)  {this->MRMLObserverManager->SetAndObserveObjectEvents ( vtkObjectPointer( &(node)), (value), (events));};
#endif
 
#ifndef vtkSetAndObserveMRMLObjectEventsMacroNoWarning
#define vtkSetAndObserveMRMLObjectEventsMacroNoWarning(node,value,events)  {this->MRMLObserverManager->SetAndObserveObjectEvents ( vtkObjectPointer( &(node)), (value), (events), nullptr /* priorities */, false /* no warning */);};
#endif
 
#ifndef vtkObserveMRMLObjectMacro
#define vtkObserveMRMLObjectMacro(node)  {this->MRMLObserverManager->ObserveObject ( (node) );};
#endif
 
#ifndef vtkObserveMRMLObjectEventsMacro
#define vtkObserveMRMLObjectEventsMacro(node, events)  {this->MRMLObserverManager->AddObjectEvents ( (node), (events) );};
#endif
 
#ifndef vtkUnObserveMRMLObjectMacro
#define vtkUnObserveMRMLObjectMacro(node)  {this->MRMLObserverManager->RemoveObjectEvents ( (node) );};
#endif
 
#ifndef vtkSetReferenceStringBodyMacro
#define vtkSetReferenceStringBodyMacro(name) \
  vtkDebugMacro(<< this->GetClassName() << " (" << this << "): setting " << #name " to " << (_arg?_arg:"(null)") ); \
  if ( this->name == nullptr && _arg == nullptr) { return;} \
  if ( this->name && _arg && (!strcmp(this->name,_arg))) { return;} \
  std::string oldValue; \
  if (this->name) { oldValue = this->name; delete [] this->name;  } \
  if (_arg) \
    { \
    size_t n = strlen(_arg) + 1; \
    char *cp1 =  new char[n]; \
    const char *cp2 = (_arg); \
    this->name = cp1; \
    do { *cp1++ = *cp2++; } while ( --n ); \
    } \
   else \
    { \
    this->name = nullptr; \
    } \
  this->Modified(); \
  if (this->Scene && this->name) \
    { \
    if (oldValue.size() > 0) \
      { \
      this->Scene->RemoveReferencedNodeID(oldValue.c_str(), this); \
      } \
    this->Scene->AddReferencedNodeID(this->name, this); \
    }
#endif
 
#ifndef vtkSetReferenceStringMacro
#define vtkSetReferenceStringMacro(name) \
virtual void Set##name (const char* _arg) \
  { \
  vtkSetReferenceStringBodyMacro(name)\
  }
#endif
 
#ifndef vtkCxxSetReferenceStringMacro
#define vtkCxxSetReferenceStringMacro(class,name)   \
void class::Set##name (const char* _arg)            \
  {                                                 \
  vtkSetReferenceStringBodyMacro(name);             \
  }
#endif
 
#ifndef vtkMRMLNodeNewMacro
#define vtkMRMLNodeNewMacro(newClass) \
  vtkStandardNewMacro(newClass); \
  vtkMRMLNode* newClass::CreateNodeInstance() \
  { \
    return newClass::New(); \
  }
#endif
 
// Use this macro to declare that this node supports
// CopyContent.It also declares CopyContent and
// HasCopyContent methods.
//
// The use of HasCopyContent() may be needed to determine if
// a specific node class has implemented CopyContent (if only
// a parent class implemented it that may not be enough).
//
#ifndef vtkMRMLCopyContentMacro
#define vtkMRMLCopyContentMacro(thisClassName) \
    void CopyContent(vtkMRMLNode* node, bool deepCopy=true) override; \
    bool HasCopyContent() const override \
    { \
    return strcmp(#thisClassName, this->GetClassNameInternal()) == 0; \
    }
#endif
 
// Use this macro to declare that this node supports
// CopyContent by only declaring HasCopyContent without
// implementing CopyContent method
// (this is the case when parent classes copy all content).
#ifndef vtkMRMLCopyContentDefaultMacro
#define vtkMRMLCopyContentDefaultMacro(thisClassName) \
    bool HasCopyContent() const override \
    { \
    return strcmp(#thisClassName, this->GetClassNameInternal()) == 0; \
    }
#endif
 
class VTK_MRML_EXPORT vtkMRMLNode : public vtkObject
{
    friend class vtkMRMLScene;
    friend class vtkMRMLSceneViewNode;
 
public:
  vtkTypeMacro(vtkMRMLNode,vtkObject);
  void PrintSelf(ostream& os, vtkIndent indent) override;
 
  enum ContentModifiedObserveType
    {
    ContentModifiedObserveUndefined = -1, 
    ContentModifiedObserveDisabled = 0,   
    ContentModifiedObserveEnabled = 1     
    };
 
  virtual vtkMRMLNode* CreateNodeInstance() = 0;
 
  virtual bool HasCopyContent() const;
 
  virtual void ReadXMLAttributes(const char** atts);
 
  virtual void UpdateReferences();
 
  virtual void ProcessChildNode(vtkMRMLNode *){};
 
  virtual void UpdateScene(vtkMRMLScene *)
  {
    this->UpdateNodeReferences();
  };
 
  virtual void OnNodeAddedToScene()
  {
    this->UpdateNodeReferences();
  };
 
  virtual void WriteXML(ostream& of, int indent);
 
  virtual void WriteNodeBodyXML(ostream& of, int indent);
 
  virtual void Copy(vtkMRMLNode *node);
 
  virtual void CopyContent(vtkMRMLNode* node, bool deepCopy=true);
 
  virtual void CopyReferences(vtkMRMLNode* node);
 
  void CopyWithScene(vtkMRMLNode *node);
 
  virtual void Reset(vtkMRMLNode* defaultNode);
 
  virtual int StartModify()
    {
    int disabledModify = this->GetDisableModifiedEvent();
    this->DisableModifiedEventOn();
    return disabledModify;
    };
 
  virtual int EndModify(int previousDisableModifiedEventState)
    {
    this->SetDisableModifiedEvent(previousDisableModifiedEventState);
    if (!previousDisableModifiedEventState)
      {
      return this->InvokePendingModifiedEvent();
      }
    return this->ModifiedEventPending;
    };
 
 
  virtual const char* GetNodeTagName() = 0;
 
  virtual const char* GetTypeDisplayName()
  {
    return this->GetNodeTagName();
  }
 
  void SetAttribute(const char* name, const char* value);
 
  void RemoveAttribute(const char* name);
 
  const char* GetAttribute(const char* name);
 
  std::vector< std::string > GetAttributeNames();
 
  void GetAttributeNames(vtkStringArray* attributeNames);
 
  vtkGetMacro(HideFromEditors, int);
  vtkSetMacro(HideFromEditors, int);
  vtkBooleanMacro(HideFromEditors, int);
 
  vtkGetMacro(Selectable, int);
  vtkSetMacro(Selectable, int);
  vtkBooleanMacro(Selectable, int);
 
  vtkGetMacro(UndoEnabled, bool);
  vtkSetMacro(UndoEnabled, bool);
  vtkBooleanMacro(UndoEnabled, bool);
 
  virtual void ProcessMRMLEvents ( vtkObject *caller, unsigned long event, void *callData );
 
  vtkGetMacro(InMRMLCallbackFlag, int);
  void SetInMRMLCallbackFlag (int flag) {
    this->InMRMLCallbackFlag = flag;
  }
 
  vtkSetStringMacro(Description);
  vtkGetStringMacro(Description);
 
  vtkSetStringMacro(Name);
  vtkGetStringMacro(Name);
 
  //vtkSetStringMacro(ID);
  vtkGetStringMacro(ID);
 
  vtkSetStringMacro(SingletonTag);
  vtkGetStringMacro(SingletonTag);
  void SetSingletonOn()
    {
    this->SetSingletonTag("Singleton");
    }
  void SetSingletonOff()
    {
    this->SetSingletonTag(nullptr);
    }
  bool IsSingleton()
    {
    return (this->GetSingletonTag() != nullptr);
    }
 
  vtkGetMacro(SaveWithScene, int);
  vtkSetMacro(SaveWithScene, int);
  vtkBooleanMacro(SaveWithScene, int);
 
  vtkGetMacro(AddToScene, int);
  vtkSetMacro(AddToScene, int);
  vtkBooleanMacro(AddToScene, int);
  void SetAddToSceneNoModify(int value);
 
  vtkGetMacro(DisableModifiedEvent, int);
  void SetDisableModifiedEvent(int onOff)
    {
    this->DisableModifiedEvent = onOff;
    }
  void DisableModifiedEventOn()
    {
    this->SetDisableModifiedEvent(1);
    }
  void DisableModifiedEventOff()
    {
    this->SetDisableModifiedEvent(0);
    }
 
  vtkGetMacro(ModifiedEventPending, int);
 
  int GetCustomModifiedEventPending(int eventId)
    {
    std::map< int, int >::iterator it = this->CustomModifiedEventPending.find(eventId);
    if (it == this->CustomModifiedEventPending.end())
      {
      return 0;
      }
    else
      {
      return it->second;
      }
    }
 
  void Modified() override
    {
    if (!this->GetDisableModifiedEvent())
      {
      Superclass::Modified();
      }
    else
      {
      ++this->ModifiedEventPending;
      }
    }
 
  virtual int InvokePendingModifiedEvent ()
    {
    int oldModifiedEventPending = 0;
    // Invoke pending standard Modified event
    if ( this->ModifiedEventPending )
      {
      oldModifiedEventPending += this->ModifiedEventPending;
      this->ModifiedEventPending = 0;
      Superclass::Modified();
      }
    // Invoke pending custom modified events
    if (!this->CustomModifiedEventPending.empty())
      {
      // Need to make a copy of the event IDs stored in this->CustomModifiedEventPending,
      // because event invocation may add more events to this->CustomModifiedEventPending,
      // which would then make the iterator invalid.
      std::vector<int> customEventsToInvoke;
      for (std::map< int, int >::iterator it=this->CustomModifiedEventPending.begin(); it!=this->CustomModifiedEventPending.end(); ++it)
        {
        oldModifiedEventPending += it->second;
        customEventsToInvoke.push_back(it->first);
        }
      this->CustomModifiedEventPending.clear();
      for (std::vector<int>::iterator it=customEventsToInvoke.begin(); it!=customEventsToInvoke.end(); ++it)
        {
        this->InvokeEvent(*it);
        }
      }
    return oldModifiedEventPending;
    }
 
  virtual void InvokeCustomModifiedEvent(int eventId, void *callData=nullptr)
    {
    if (!this->GetDisableModifiedEvent())
      {
      // DisableModify is inactive, we immediately invoke the event
      this->InvokeEvent(eventId, callData);
      }
    else
      {
      // just remember the custom modified event and invoke it once,
      // when DisableModify is deactivated
      ++this->CustomModifiedEventPending[eventId];
      }
    }
 
  virtual vtkMRMLScene* GetScene();
 
  virtual void SetScene(vtkMRMLScene* scene);
 
  virtual void SetSceneReferences();
 
  virtual void UpdateReferenceID(const char *oldID, const char *newID);
 
  vtkGetObjectMacro(ContentModifiedEvents, vtkIntArray);
 
  const char *URLEncodeString(const char *inString);
 
  const char *URLDecodeString(const char *inString);
 
  std::string XMLAttributeEncodeString(const std::string& inString);
 
  std::string XMLAttributeDecodeString(const std::string& inString);
 
  vtkGetMacro(Selected, int);
  vtkSetMacro(Selected, int);
  vtkBooleanMacro(Selected, int);
 
  void AddNodeReferenceRole(const char *referenceRole, const char *mrmlAttributeName=nullptr,
    vtkIntArray *events=nullptr, bool observeContentModifiedEvents=false);
 
  vtkMRMLNode* SetNodeReferenceID(const char* referenceRole, const char* referencedNodeID);
 
  vtkMRMLNode* AddNodeReferenceID(const char* referenceRole , const char* referencedNodeID);
 
  vtkMRMLNode* SetNthNodeReferenceID(const char* referenceRole, int n, const char* referencedNodeID);
 
  vtkMRMLNode* SetAndObserveNodeReferenceID(const char* referenceRole , const char* referencedNodeID,
    vtkIntArray *events=nullptr, ContentModifiedObserveType observeContentModifiedEvents=ContentModifiedObserveUndefined);
 
  vtkMRMLNode* AddAndObserveNodeReferenceID(const char* referenceRole , const char* referencedNodeID,
    vtkIntArray *events=nullptr, ContentModifiedObserveType observeContentModifiedEvents=ContentModifiedObserveUndefined);
 
  vtkMRMLNode* SetAndObserveNthNodeReferenceID(const char* referenceRole, int n, const char *referencedNodeID,
    vtkIntArray *events=nullptr, ContentModifiedObserveType observeContentModifiedEvents=ContentModifiedObserveUndefined);
 
  void RemoveNthNodeReferenceID(const char* referenceRole, int n);
 
  void RemoveNodeReferenceIDs(const char* referenceRole);
 
  bool HasNodeReferenceID(const char* referenceRole, const char* referencedNodeID);
 
  int GetNumberOfNodeReferences(const char* referenceRole);
 
  const char *GetNthNodeReferenceID(const char* referenceRole, int n);
 
  const char *GetNodeReferenceID(const char* referenceRole);
 
  vtkMRMLNode* GetNthNodeReference(const char* referenceRole, int n);
 
  vtkMRMLNode* GetNodeReference(const char* referenceRole);
 
  void GetNodeReferences(const char* referenceRole, std::vector<vtkMRMLNode*> &nodes);
 
  void GetNodeReferenceIDs(const char* referenceRole,
                           std::vector<const char*> &referencedNodeIDs);
 
  void GetNodeReferenceRoles(std::vector<std::string> &roles);
 
  int GetNumberOfNodeReferenceRoles();
 
  const char* GetNthNodeReferenceRole(int n);
 
  enum
    {
      HierarchyModifiedEvent = 16000,
      IDChangedEvent = 16001,
      ReferenceAddedEvent,
      ReferenceModifiedEvent,
      ReferenceRemovedEvent,
      ReferencedNodeModifiedEvent
    };
 
 
protected:
 
  class VTK_MRML_EXPORT vtkMRMLNodeReference : public vtkObject
  {
  public:
    vtkTypeMacro(vtkMRMLNodeReference,vtkObject);
    static vtkMRMLNodeReference *New();
    void PrintSelf(ostream& vtkNotUsed(os), vtkIndent vtkNotUsed(indent)) override {};
 
  public:
    vtkSetStringMacro(ReferenceRole);
    vtkGetStringMacro(ReferenceRole);
 
    vtkSetStringMacro(ReferencedNodeID);
    vtkGetStringMacro(ReferencedNodeID);
 
    void SetStaticEvents(vtkIntArray* events);
    vtkIntArray* GetStaticEvents() const;
 
    vtkSetMacro(ObserveContentModifiedEvents, ContentModifiedObserveType);
    vtkGetMacro(ObserveContentModifiedEvents, ContentModifiedObserveType);
 
    void SetReferencingNode(vtkMRMLNode* node);
    vtkMRMLNode* GetReferencingNode() const;
 
    void SetReferencedNode(vtkMRMLNode* node);
    vtkMRMLNode* GetReferencedNode() const;
 
  protected:
    vtkMRMLNodeReference();
    ~vtkMRMLNodeReference() override;
 
    vtkMRMLNodeReference(const vtkMRMLNodeReference&);
    void operator=(const vtkMRMLNodeReference&);
 
    char*     ReferenceRole;
 
    vtkWeakPointer<vtkMRMLNode> ReferencingNode;
    vtkSmartPointer<vtkMRMLNode> ReferencedNode;
 
    char*     ReferencedNodeID;
    vtkSmartPointer<vtkIntArray> StaticEvents;
    ContentModifiedObserveType ObserveContentModifiedEvents{ vtkMRMLNode::ContentModifiedObserveUndefined };
  };
 
  vtkMRMLNode();
  ~vtkMRMLNode() override;
  vtkMRMLNode(const vtkMRMLNode&);
  void operator=(const vtkMRMLNode&);
 
  static void MRMLCallback( vtkObject *caller,
                            unsigned long eid, void *clientData, void *callData );
 
  vtkSetStringMacro( TempURLString );
  vtkGetStringMacro( TempURLString );
 
  virtual const char* GetReferenceRoleFromMRMLAttributeName(const char* attName);
 
  virtual const char* GetMRMLAttributeNameFromReferenceRole(const char* refRole);
 
  virtual bool IsReferenceRoleGeneric(const char* refRole);
 
  virtual void UpdateNodeReferences(const char* referenceRole = nullptr);
 
  void RemoveInvalidReferences(const std::set<std::string>& validNodeIDs);
 
  virtual void UpdateNthNodeReference(const char* referenceRole, int n);
 
  vtkMRMLNode* UpdateNodeReferenceEventObserver(vtkMRMLNode *oldReferencedNode, vtkMRMLNode *newReferencedNode,
    vtkIntArray *newEvents, bool newObserveContentModifiedEvents, vtkMRMLNodeReference* referenceToIgnore);
 
  void GetUpdatedReferencedNodeEventList(int& oldReferencedNodeUseCount, int& newReferencedNodeUseCount,
    vtkIntArray* oldConsolidatedEventList, vtkIntArray* newConsolidatedEventList,
    vtkMRMLNode* oldReferencedNode, vtkMRMLNode* newReferencedNode,
    vtkMRMLNodeReference* referenceToIgnore, vtkIntArray* newEvents, bool newObserveContentModifiedEvents);
 
  virtual void InvalidateNodeReferences();
 
  virtual void OnNodeReferenceAdded(vtkMRMLNodeReference *reference)
  {
    this->InvokeEvent(vtkMRMLNode::ReferenceAddedEvent, reference);
  }
 
  virtual void OnNodeReferenceModified(vtkMRMLNodeReference *reference)
  {
    this->InvokeEvent(vtkMRMLNode::ReferenceModifiedEvent, reference);
  }
 
  virtual void OnNodeReferenceRemoved(vtkMRMLNodeReference *reference)
  {
    this->InvokeEvent(vtkMRMLNode::ReferenceRemovedEvent, reference);
  }
 
  void ParseReferencesAttribute(const char *attValue, std::set<std::string> &references);
 
  vtkCallbackCommand *MRMLCallbackCommand;
 
  char *ID{nullptr};
  char *Name{nullptr};
  char *Description{nullptr};
  int HideFromEditors{0};
  int Selectable{1};
  int Selected{0};
  int AddToScene{1};
  bool UndoEnabled{false};
 
  int  SaveWithScene{true};
 
  int InMRMLCallbackFlag{0};
 
  // We don't increase the reference count of Scene when store its pointer
  // therefore we must use a weak pointer to prevent pointer dangling when
  // the scene is deleted.
  vtkWeakPointer<vtkMRMLScene> Scene;
 
  typedef std::map< std::string, std::string > AttributesType;
  AttributesType Attributes;
 
  vtkIntArray* ContentModifiedEvents;
 
  vtkObserverManager *MRMLObserverManager;
 
  typedef std::vector< vtkSmartPointer<vtkMRMLNodeReference> > NodeReferenceListType;
  typedef std::map< std::string, NodeReferenceListType > NodeReferencesType;
  NodeReferencesType NodeReferences;
 
  std::map< std::string, std::string> NodeReferenceMRMLAttributeNames;
 
  struct NodeReferenceEventList
    {
    vtkSmartPointer<vtkIntArray> StaticEvents;
    ContentModifiedObserveType ObserveContentModifiedEvents{ ContentModifiedObserveUndefined };
    };
  typedef std::map< std::string, NodeReferenceEventList> NodeReferenceEventsType;
  NodeReferenceEventsType NodeReferenceEvents; // for each role it specifies which referenced node emitted events this node should observe
 
private:
 
  void SetID(const char* newID);
 
  char *TempURLString{nullptr};
 
  char *SingletonTag{nullptr};
 
  int DisableModifiedEvent{0};
  int ModifiedEventPending{0};
  std::map<int, int> CustomModifiedEventPending; // event id, pending value (number of events grouped together)
};
 
class VTK_MRML_EXPORT MRMLNodeModifyBlocker
{
public:
  vtkWeakPointer<vtkMRMLNode> Node;
  int WasModifying;
  MRMLNodeModifyBlocker(vtkMRMLNode* node)
  {
    this->Node = node;
    if (this->Node)
      {
      this->WasModifying = this->Node->StartModify();
      }
  };
  ~MRMLNodeModifyBlocker()
  {
    if (this->Node)
      {
      this->Node->EndModify(this->WasModifying);
      }
  }
};
 
#endif