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;

  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;

  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);

  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);

  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);

  vtkMRMLNode* AddAndObserveNodeReferenceID(const char* referenceRole , const char* referencedNodeID, vtkIntArray *events=nullptr);

  vtkMRMLNode* SetAndObserveNthNodeReferenceID(const char* referenceRole, int n, const char *referencedNodeID, vtkIntArray *events=nullptr);

  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 SetEvents(vtkIntArray* events);
    vtkIntArray* GetEvents() const;

    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> Events;
  };

  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);

  virtual void UpdateNthNodeReference(const char* referenceRole, int n);

  vtkMRMLNode* UpdateNodeReferenceEventObserver(vtkMRMLNode *oldReferencedNode, vtkMRMLNode *newReferencedNode,
    vtkIntArray *newEvents, vtkMRMLNodeReference* referenceToIgnore);

  void GetUpdatedReferencedNodeEventList(int& oldReferencedNodeUseCount, int& newReferencedNodeUseCount,
    vtkIntArray* oldConsolidatedEventList, vtkIntArray* newConsolidatedEventList,
    vtkMRMLNode* oldReferencedNode, vtkMRMLNode* newReferencedNode,
    vtkMRMLNodeReference* referenceToIgnore, vtkIntArray* newEvents);

  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;

  typedef std::map< std::string, vtkSmartPointer<vtkIntArray> > 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