ENH: 2727. Implemented new generic MRML node reference API in the vtkMRMLNode class. Implemented vtkMRMLDisplayableNode, vtkMRMLStorableNode, vtkMRMLTransformNode node using new API. Added tests to Libs/MRML/Core/Testing/vtkMRMLNodeTest1.cxx. See below for more details on the API.

== Goal ==
This page explains how to create a MRML node that reference and observes
other MRML nodes.

== History ==
In Slicer4.2 prior to March of 2013 each MRML node that contained
references to other MRML nodes (for example each vtkMRMLDispalyableNode contained
a reference to an instance vtkMRMLDisplayNode) was responsible for
managing the references internally. This involved complicated logic and
bookkeeping to maintain the references in sync when importing scenes,
adding/deleting nodes, modifying referenced nodes, etc.

When creating a new node with the reference to another node the following
methods needed to be created/updated to handle the references:

• Copy
• PrintSelf
• ReadXMLAttributes
• WriteXML
• ProcessMRMLEvents
• UpdateReferenceIS
• SetSceneRefeecnes
• UpdateScene
• UpdateReferences
• SetAndObserveReferenedNode

== New API ==
The new node reference API automatically takes care of read/write/copy of
node references, updating references on scene import, adding and deleting
nodes. All that functionality in implemented the vtkMRMLNode base
class. The only thing that needs to happen in the derived MRML node class
(usually in the constructor of the class)
is a call to vtkMRMLNode::AddNodeReferenceRole(const char referenceRole,
const char mrmlAttributeName)
that takes a unique string defining the reference role between this node
and the referenced node, and a MRML attribute name for storing the
reference in the .mrml file.

The only other call that is needed is either:
vtkMRMLNode SetAndObserveNodeReferenceID(const char referenceRole , const
char referencedNodeID, vtkIntArray events=0);
or
vtkMRMLNode AddAndObserveNodeReferenceID(const char referenceRole , const
char referencedNodeID, vtkIntArray events=0);
if the multiple instances of this reference are allowed.

vtkMRMLNode also provides virtual callbacks that can be extended in the
derived calsses:

• OnNodeReferenceAdded(vtkMRMLNodeReference *reference)
• OnNodeReferenceRemoved(vtkMRMLNodeReference *reference)
• OnNodeReferenceModified(vtkMRMLNodeReference *reference)

By default those methods generate the following events:

• vtkMRMLNode::ReferenceAddedEvent
• vtkMRMLNode::ReferenceRemovedEvent
• vtkMRMLNode::ReferenceModifiedEvent

In the derived classes those methods could be extended using vtkMRMLNode
API that allows querying of node's references:

• char GetNthNodeReferenceID(const char referenceRole, int n);
• vtkMRMLNode GetNthNodeReference(const char referenceRole, int n);
• int GetNumberOfNodeReferences(const char* referenceRole);
• etc.

For full API see:

http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLNode.h?view=log

Currently the following MRML nodes are implemented using new API:

• vtkMRMLStorableNode
• vtkMRMLTransformableNode
• vtkMRMLDisplayableNode

Other references to MRML nodes such as to vtkMRMLColorTableNode, vtkMRMLDiffusionTensorDisplayPropertiesNode are currently not using new API.

Module parameter nodes that contain references to input/output Volume/Model, etc. nodes may or may not require a new API since not all of them contain logic to deal with reference changes.

== Examples ==

• vtkMRMLTransformableNode implementation:
  http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLTransformableNode.h?view=log
• vtkMRMLDisplayableNodeimplementation:
  http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLDisplayableNode.h?view=log
• vtkMRMLStorableNodeimplementation:
  http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLStorableNode.h?view=log

git-svn-id: http://svn.slicer.org/Slicer4/trunk@21810 3bd1e089-480b-0410-8dfb-8563597acbee