diff java/src/uk/ac/qmul/eecs/ccmi/gui/Diagram.java @ 3:9e67171477bc

PHANTOM Omni Heptic device release

--- a/java/src/uk/ac/qmul/eecs/ccmi/gui/Diagram.java	Mon Feb 06 12:54:06 2012 +0000
+++ b/java/src/uk/ac/qmul/eecs/ccmi/gui/Diagram.java	Wed Apr 25 17:09:09 2012 +0100
@@ -24,40 +24,113 @@
 import uk.ac.qmul.eecs.ccmi.diagrammodel.CollectionModel;
 import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramElement;
 import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramModel;
-import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramModelTreeNode;
+import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramTreeNode;
 import uk.ac.qmul.eecs.ccmi.diagrammodel.NodeProperties;
 import uk.ac.qmul.eecs.ccmi.diagrammodel.TreeModel;
 import uk.ac.qmul.eecs.ccmi.gui.persistence.PrototypePersistenceDelegate;
+import uk.ac.qmul.eecs.ccmi.network.AwarenessMessage;
+import uk.ac.qmul.eecs.ccmi.network.DiagramEventActionSource;
 
 /**
- * This Diagram class holds all the data needed for a representation of the diagram. It is used by component classes 
+ * The {@code Diagram} class holds all the data needed for a representation of the diagram. It is used by component classes 
  * such as {@link GraphPanel} and {@link DiagramTree} to draw the diagram by accessing the diagram model or by 
  * {@link EditorTabbedPane} to assign a title to the tabs out of the diagram name. 
- * 
  *
  */
 public abstract class Diagram implements Cloneable {
 	
+	/**
+	 * Crates a new instance of a Diagram. The diagram created through this method is not shared with any peer via 
+	 * a server. 
+	 * @param name the name of the diagram.
+	 * @param nodes an array of node prototypes. Nodes inserted by users in the diagram will be created by cloning these nodes. 
+	 * @param edges an array of edge prototypes. Edges inserted by users in the diagram will be created by cloning these edges.
+	 * @param prototypePersistenceDelegate a delegate class to handle nodes and edges persistence.
+	 * @return a new instance of {@code Diagram}
+	 */
 	public static Diagram newInstance(String name, Node[] nodes, Edge[] edges, PrototypePersistenceDelegate prototypePersistenceDelegate){
 		return new LocalDiagram(name,nodes,edges,prototypePersistenceDelegate);
 	}
 	
+	/**
+	 * Returns the name of the diagram. The name identifies the diagram uniquely in the editor. There cannot
+	 * be two diagrams with the same name open at the same time. This makes things easier when sharing diagrams
+	 * with other users via the network.
+	 * 
+	 * @return the name of the diagram
+	 */
 	public abstract String getName();
 
+	/**
+	 * Assign this diagram a new name. 
+	 * @param name the new name of the diagram
+	 */
 	public abstract void setName(String name);
 
+	/**
+	 * Returns an array with the node prototypes. Node prototypes are used when creating new node 
+	 * instances via the {@code clone()} method. 
+	 * 
+	 * @return an array of nodes 
+	 */
 	public abstract Node[] getNodePrototypes();
 
+	/**
+	 * Returns an array with the edge prototypes. Edge prototypes are used when creating new edge 
+	 * instances via the {@code clone()} method.
+	 * 
+	 * @return an array of edges
+	 */
 	public abstract Edge[] getEdgePrototypes();
 
+	/**
+	 * Returns the tree model of this diagram. Note that each diagram holds a {@code DiagramModel} 
+	 * which has  two sub-models ({@code TreeModel} and {@code CollectionModel}). Changes on one 
+	 * sub-model will affect the other model as well. 
+	 * 
+	 * @return the tree model of this diagram 
+	 * 
+	 * @see uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramModel uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramModel
+	 */
 	public abstract TreeModel<Node,Edge> getTreeModel();
 
+	/**
+	 * Returns the collection model of this diagram. Note that each diagram holds a {@code DiagramModel} 
+	 * which has  two sub-models ({@code TreeModel} and {@code CollectionModel}). Changes on one 
+	 * sub-model will affect the other model as well. 
+	 * 
+	 * @return the tree model of this diagram 
+	 * 
+	 * @see uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramModel uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramModel
+	 */
 	public abstract CollectionModel<Node,Edge> getCollectionModel();
 
+	/**
+	 * Returns the model updater of this diagram. The model updater is the delegate for all the 
+	 * update operations affecting the diagram model.
+	 * 
+	 * @return the model updater for this diagram
+	 */
 	public abstract DiagramModelUpdater getModelUpdater();
 	
+	/**
+	 * Returns the label of the diagram. The label is slightly different from the name as it's the string 
+	 * appearing in the tabbed pane of the editor. It includes asterisk character at the end when the {@code DiagramModel}
+	 * of this class has been changed and not  yet saved on hard disk.   
+	 *  
+	 * @return a label for this diagram
+	 */
 	public abstract String getLabel();
 	
+	/**
+	 * Returns the delegates for this diagram for nodes and edges prototypes persistence. 
+	 * When saving a diagram to an xml file each node and edge of the prototypes is encoded  
+	 * in the xml file. Indeed the template of a diagram is made of of its prototypes. 
+	 * In the template is held the general attributes common to all the nodes and edges, like 
+	 * for instance the type of a node but not its current position. 
+	 *  
+	 * @return the PrototypePersistenceDelegate for this diagram 
+	 */
 	public abstract PrototypePersistenceDelegate getPrototypePersistenceDelegate();
 
 	@Override
@@ -130,6 +203,9 @@
 			return prototypePersistenceDelegate;
 		}
 		
+		/**
+		 * Creates a new {@code Diagram} by clonation.  
+		 */
 		@Override
 		public Object clone(){
 			LocalDiagram clone = (LocalDiagram)super.clone();
@@ -152,111 +228,114 @@
 		private class InnerModelUpdater implements DiagramModelUpdater {
 
 			@Override
-			public boolean getLock(DiagramModelTreeNode treeNode, Lock lock) {
+			public boolean getLock(DiagramTreeNode treeNode, Lock lock, DiagramEventActionSource source) {
 				/* using a non shared diagram requires no actual lock, therefore the answer is always yes */
 				return true;
 			}
 			
 			@Override
-			public void yieldLock(DiagramModelTreeNode treeNode, Lock lock) {}
+			public void yieldLock(DiagramTreeNode treeNode, Lock lock, DiagramEventActionSource actionSource) {}
 
+			@Override 
+			public void sendAwarenessMessage(AwarenessMessage.Name awMsgName, Object source){}
+			
 			@Override
-			public void insertInCollection(DiagramElement element) {
+			public void insertInCollection(DiagramElement element,DiagramEventSource source) {
 				if(element instanceof Node)
-					diagramModel.getDiagramCollection().insert((Node)element);
+					diagramModel.getDiagramCollection().insert((Node)element,source);
 				else
-					diagramModel.getDiagramCollection().insert((Edge)element);
+					diagramModel.getDiagramCollection().insert((Edge)element,source);
 			}
 
 			@Override
 			public void insertInTree(DiagramElement element) {
 				if(element instanceof Node)
-					diagramModel.getTreeModel().insertTreeNode((Node)element);
+					diagramModel.getTreeModel().insertTreeNode((Node)element,DiagramEventSource.TREE);
 				else
-					diagramModel.getTreeModel().insertTreeNode((Edge)element);
+					diagramModel.getTreeModel().insertTreeNode((Edge)element,DiagramEventSource.TREE);
 			}
 
 			@Override
-			public void takeOutFromCollection(DiagramElement element) {
-				diagramModel.getDiagramCollection().takeOut(element);
+			public void takeOutFromCollection(DiagramElement element, DiagramEventSource source) {
+				diagramModel.getDiagramCollection().takeOut(element,source);
 			}
 
 			@Override
 			public void takeOutFromTree(DiagramElement element) {
-				diagramModel.getDiagramCollection().takeOut(element);
+				diagramModel.getTreeModel().takeTreeNodeOut(element,DiagramEventSource.TREE);
 			}
 
 			@Override
-			public void setName(DiagramElement element, String name) {
-				element.setName(name);
+			public void setName(DiagramElement element, String name,DiagramEventSource source) {
+				element.setName(name,source);
 			}
 
 			@Override
-			public void setNotes(DiagramModelTreeNode treeNode, String notes) {
-				diagramModel.getTreeModel().setNotes(treeNode, notes);
+			public void setNotes(DiagramTreeNode treeNode, String notes,DiagramEventSource source) {
+				diagramModel.getTreeModel().setNotes(treeNode, notes,source);
 			}
 
 			@Override
 			public void setProperty(Node node, String type, int index,
-					String value) {
-				node.setProperty(type, index, value);
+					String value,DiagramEventSource source) {
+				node.setProperty(type, index, value,source);
 			}
 
 			@Override
-			public void setProperties(Node node, NodeProperties properties) {
-				node.setProperties(properties);
+			public void setProperties(Node node, NodeProperties properties,DiagramEventSource source) {
+				node.setProperties(properties,source);
 			}
 
 			@Override
-			public void clearProperties(Node node) {
-				node.clearProperties();
+			public void clearProperties(Node node,DiagramEventSource source) {
+				node.clearProperties(source);
 			}
 
 			@Override
-			public void addProperty(Node node, String type, String value) {
-				node.addProperty(type, value);
+			public void addProperty(Node node, String type, String value,DiagramEventSource source) {
+				node.addProperty(type, value,source);
 			}
 
 			@Override
-			public void removeProperty(Node node, String type, int index) {
-				node.removeProperty(type, index);
+			public void removeProperty(Node node, String type, int index,DiagramEventSource source) {
+				node.removeProperty(type, index,source);
 			}
 
 			@Override
 			public void setModifiers(Node node, String type, int index,
-					Set<Integer> modifiers) {
-				node.setModifierIndexes(type, index, modifiers);				
+					Set<Integer> modifiers,DiagramEventSource source) {
+				node.setModifierIndexes(type, index, modifiers,source);				
 			}
 
 			@Override
-			public void setEndLabel(Edge edge, Node node, String label) {
-				edge.setEndLabel(node, label);
+			public void setEndLabel(Edge edge, Node node, String label,DiagramEventSource source) {
+				edge.setEndLabel(node, label,source);
 			}
 
 			@Override
 			public void setEndDescription(Edge edge, Node node,
-					int index) {
-				edge.setEndDescription(node, index);
+					int index,DiagramEventSource source) {
+				edge.setEndDescription(node, index,source);
 			}
 
 			@Override
-			public void translate(GraphElement ge, Point2D p, double x, double y) {
-				ge.translate(p, x, y);
+			public void translate(GraphElement ge, Point2D p, double x, double y,DiagramEventSource source) {
+				ge.translate(p, x, y,source);
 			}
 
 			@Override
-			public void startMove(GraphElement ge, Point2D p) {
-				ge.startMove(p);
+			public void startMove(GraphElement ge, Point2D p,DiagramEventSource source) {
+				ge.startMove(p,source);
 			}
 
 			@Override
-			public void bend(Edge edge, Point2D p) {
-				edge.bend(p);
+			public void bend(Edge edge, Point2D p,DiagramEventSource source) {
+				edge.bend(p,source);
 			}
 
 			@Override
-			public void stopMove(GraphElement ge) {
-				ge.stopMove();
+			public void stopMove(GraphElement ge,DiagramEventSource source) {
+				ge.stopMove(source);
 			}
 		}
 	}