f@0: /*  
f@0:  CCmI Editor - A Collaborative Cross-Modal Diagram Editing Tool
f@0:   
f@0:  Copyright (C) 2011  Queen Mary University of London (http://ccmi.eecs.qmul.ac.uk/)
f@0: 
f@0:  This program is free software: you can redistribute it and/or modify
f@0:  it under the terms of the GNU General Public License as published by
f@0:  the Free Software Foundation, either version 3 of the License, or
f@0:  (at your option) any later version.
f@0: 
f@0:  This program is distributed in the hope that it will be useful,
f@0:  but WITHOUT ANY WARRANTY; without even the implied warranty of
f@0:  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
f@0:  GNU General Public License for more details.
f@0: 
f@0:  You should have received a copy of the GNU General Public License
f@0:  along with this program.  If not, see <http://www.gnu.org/licenses/>.
f@0: */
f@0: package uk.ac.qmul.eecs.ccmi.gui;
f@0: 
f@0: import java.awt.geom.Point2D;
f@0: import java.util.Set;
f@0: 
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramElement;
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramTreeNode;
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.NodeProperties;
f@0: import uk.ac.qmul.eecs.ccmi.network.AwarenessMessage;
f@0: import uk.ac.qmul.eecs.ccmi.network.DiagramEventActionSource;
f@0: import uk.ac.qmul.eecs.ccmi.network.NetDiagram;
f@0: 
f@0: /**
f@0:  * 
f@0:  * The DiagramModelUpdater class is used to make changes to the diagram model. The reason why 
f@0:  * changes are not made directly to the model is allowing the network-local diagram interchangeability. 
f@0:  * A NetDiagram differs from a local 
f@0:  * diagram only by its DiagramModelUpdater implementation. The rest of the operations are 
f@0:  * performed through the delegate local diagram which is passed as argument to the constructor.    
f@0:  * In this way a local diagram can be easily turned into a network diagram and vice versa.
f@0:  *
f@0:  * @see NetDiagram
f@0:  */
f@0: public interface DiagramModelUpdater {
f@0: 	
f@0: 	/**
f@0: 	 * Issues a lock request to the server for the specified tree node.
f@0: 	 * 
f@0: 	 * @param treeNode the tree node the lock is being requested for
f@0: 	 * @param lock the type of lock being requested
f@0: 	 * @param actionSource The {@code DiagramEventActionSource} that's going to be piggybacked 
f@0: 	 *  on the lock message, for awareness purposes 
f@0: 	 * @return {@code true} if the lock is successfully granted by the server
f@0: 	 */
f@0: 	public boolean getLock(DiagramTreeNode treeNode, Lock lock, DiagramEventActionSource actionSource);
f@0: 	
f@0: 	/**
f@0: 	 * Releases a lock previously acquired by this client. 
f@0: 	 *  
f@0: 	 * @param treeNode the tree node the lock is being released for
f@0: 	 * @param lock the type of lock being released
f@0: 	 * @param actionSource The {@code DiagramEventActionSource} that's going to be piggybacked 
f@0: 	 *  on the lock message, for awareness purposes.
f@0: 	 *  
f@0: 	 * @see uk.ac.qmul.eecs.ccmi.network.AwarenessMessage
f@0: 	 */
f@0: 	public void yieldLock(DiagramTreeNode treeNode, Lock lock ,DiagramEventActionSource actionSource);
f@0: 	
f@0: 	/**
f@0: 	 * Sends an awareness message to the server. 
f@0: 	 * 
f@0: 	 * @param awMsgName the type of awareness message being sent 
f@0: 	 * @param source the source of the action. Represents informations to be carried on this message.
f@0: 	 * 
f@0: 	 * @see uk.ac.qmul.eecs.ccmi.network.AwarenessMessage 
f@0: 	 */
f@0: 	public void sendAwarenessMessage(AwarenessMessage.Name awMsgName, Object source);
f@0: 	
f@0: 	/**
f@0: 	 * Inserts a {@code DiagramElement} in the {@code CollectionModel} of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param element the element to insert 
f@0: 	 * @param source the source of the insertion action. it can be used by collection listeners.   
f@0: 	 */
f@0: 	public void insertInCollection(DiagramElement element,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Inserts a {@code DiagramElement} in the {@code TreeModel} of the {@code Diagram} holding this 
f@0: 	 * model updater.
f@0: 	 * 
f@0: 	 * @param element the element to insert 
f@0: 	 */
f@0: 	public void insertInTree(DiagramElement element);
f@0: 	
f@0: 	/**
f@0: 	 * Removes an element from the {@code CollectionModel} of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param element the element to remove 
f@0: 	 * @param source the source of the insertion action. it can be used by collection listeners.   
f@0: 	 */
f@0: 	public void takeOutFromCollection(DiagramElement element,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Removes an element from the {@code TreeModel} of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param element the element to remove 
f@0: 	 */
f@0: 	public void takeOutFromTree(DiagramElement element);
f@0: 	
f@0: 	/**
f@0: 	 * Sets a new name for the element of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param element the element being renamed
f@0: 	 * @param name the new name 
f@0: 	 * @param source the source of the removal action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void setName(DiagramElement element, String name,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Sets to a new value a property of a node of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param node the node being set a new property 
f@0: 	 * @param type the type of the new property 
f@0: 	 * @param index the index of the property being set a new value  
f@0: 	 * @param value the new value for the property 
f@0: 	 * @param source source the source of the {@code setName} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void setProperty(Node node, String type, int index, String value,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Replace the whole {@code NodeProperties} object of a node of the {@code Diagram} holding this 
f@0: 	 * model updater with a new one. 
f@0: 	 * 
f@0: 	 * @param node the node being set a new {@code NodeProperties} instance
f@0: 	 * @param properties the new {@code NodeProperties} instance 
f@0: 	 * @param source source the source of the {@code setProperty} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void setProperties(Node node, NodeProperties properties,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Clears the properties of a node of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param node the node whose properties are being cleared 
f@0: 	 * @param source the source of the {@code setProperties} action. it can be used by collection listeners.
f@0: 	 * 
f@0: 	 * @see uk.ac.qmul.eecs.ccmi.diagrammodel.NodeProperties#clear()
f@0: 	 */
f@0: 	public void clearProperties(Node node,DiagramEventSource source);
f@0: 
f@0: 	/**
f@0: 	 * Set the notes for a tree node of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param treeNode the tree node whose notes are being set 
f@0: 	 * @param notes the new notes 
f@0: 	 * @param source the source of the {@code setNotes} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void setNotes(DiagramTreeNode treeNode, String notes,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Add a new property to a node's properties of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param node the node whose properties are being added to 
f@0: 	 * @param type the type of the new property being added 
f@0: 	 * @param value the value of the new property being added 
f@0: 	 * @param source the source of the {@code setProperty} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void addProperty(Node node, String type, String value,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Removes a property from a node's properties of the {@code Diagram} holding this 
f@0: 	 * model updater.  
f@0: 	 * 
f@0: 	 * @param node the node whose properties are being removed from
f@0: 	 * @param type the type of the new property being removed
f@0: 	 * @param index the index of the property being removed 
f@0: 	 * @param source the source of the {@code removeProperty} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void removeProperty(Node node, String type, int index,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Set the modifiers for a property of a node in of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param node the node whose properties whose modifiers are being 
f@0: 	 * @param type the type of the property whose modifiers are being set
f@0: 	 * @param index the index of the property whose modifiers are being set
f@0: 	 * @param modifiers the new modifiers indexes. the indexes refer to the modifiers type array. 
f@0: 	 * @param source the source of the {@code setModifiers} action. it can be used by collection listeners.
f@0: 	 */ 
f@0: 	public void setModifiers(Node node, String type, int index, Set<Integer> modifiers,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Set the end label for an edge of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param edge the edge whose label is being set 
f@0: 	 * @param node the node at the edge end where the label is being set 
f@0: 	 * @param label the new label 
f@0: 	 * @param source the source of the {@code setLabel} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void setEndLabel(Edge edge, Node node, String label,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Set the end description for an edge of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param edge the edge whose end description is being set 
f@0: 	 * @param node the node at the edge end where the end description is being set 
f@0: 	 * @param index the index of the new end description in the end description array of {@code edge}
f@0: 	 * @param source the source of the {@code setEndDescription} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void setEndDescription(Edge edge, Node node, int index, DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Translates a graph element of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 * 
f@0: 	 * @param ge the graph element being translated 
f@0: 	 * @param p the starting point of the translation 
f@0: 	 * @param x the distance to translate along the x-axis
f@0: 	 * @param y the distance to translate along the y-axis
f@0: 	 * @param source the source of the {@code translate} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void translate(GraphElement ge, Point2D p, double x, double y,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Starts the move for a graph element of the {@code Diagram} holding this 
f@0: 	 * model updater. The move can be either a translation or a bend (if {@code ge} is an Edge). 
f@0: 	 * This method must be called before such motion methods are called in turn.  
f@0: 	 * 
f@0: 	 * @param ge the graph element being translated 
f@0: 	 * @param p the starting point of the motion 
f@0: 	 * @param source the source of the {@code startMove} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void startMove(GraphElement ge, Point2D p, DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Bends an edge of the {@code Diagram} holding this  model updater.
f@0: 	 * 
f@0: 	 * @param edge the edge being bended 
f@0: 	 * @param p the starting point of the motion 
f@0: 	 * @param source the source of the {@code bend} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void bend(Edge edge, Point2D p,DiagramEventSource source);
f@0: 	
f@0: 	/**
f@0: 	 * Finishes off the motion of a graph element of the {@code Diagram} holding this 
f@0: 	 * model updater. 
f@0: 	 *  
f@0: 	 * @param ge the graph element being moved
f@0: 	 * @param source the source of the {@code stopMove} action. it can be used by collection listeners.
f@0: 	 */
f@0: 	public void stopMove(GraphElement ge,DiagramEventSource source);
f@0: }