fiore@0: /*  
fiore@0:  CCmI Editor - A Collaborative Cross-Modal Diagram Editing Tool
fiore@0:   
fiore@0:  Copyright (C) 2011  Queen Mary University of London (http://ccmi.eecs.qmul.ac.uk/)
fiore@0: 
fiore@0:  This program is free software: you can redistribute it and/or modify
fiore@0:  it under the terms of the GNU General Public License as published by
fiore@0:  the Free Software Foundation, either version 3 of the License, or
fiore@0:  (at your option) any later version.
fiore@0: 
fiore@0:  This program is distributed in the hope that it will be useful,
fiore@0:  but WITHOUT ANY WARRANTY; without even the implied warranty of
fiore@0:  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
fiore@0:  GNU General Public License for more details.
fiore@0: 
fiore@0:  You should have received a copy of the GNU General Public License
fiore@0:  along with this program.  If not, see <http://www.gnu.org/licenses/>.
fiore@0: */
fiore@0: package uk.ac.qmul.eecs.ccmi.diagrammodel;
fiore@0: 
fiore@0: import java.util.LinkedHashMap;
fiore@0: import java.util.List;
fiore@0: import java.util.Map;
fiore@0: 
fiore@0: /**
fiore@0:  * This class represent an edge in the diagram model. Note that this class is 
fiore@0:  * a tree node.
fiore@0:  *
fiore@0:  */
fiore@0: @SuppressWarnings("serial")
fiore@0: public abstract class DiagramEdge extends DiagramElement {
fiore@0: 	/**
fiore@0: 	 * 
fiore@0: 	 * @param type the type of the edge 
fiore@0: 	 * @param availableEndDescriptions the end descriptions this edge allows 
fiore@0: 	 */
fiore@0: 	public DiagramEdge(String type, String[] availableEndDescriptions){
fiore@0: 		setType(type);
fiore@0: 		this.availableEndDescriptions = availableEndDescriptions;
fiore@0: 		endLabels = new LinkedHashMap<DiagramNode,String>();
fiore@0: 		endDescriptions = new LinkedHashMap<DiagramNode,Integer>();
fiore@0: 	}
fiore@0: 
fiore@0: 	/**
fiore@0: 	 * Returns a more detailed description of the edge than {@link #spokenText()}.
fiore@0: 	 * the description includes which nodes this edge is connecting 
fiore@0: 	 * 
fiore@0: 	 *  @return a description of the edge
fiore@0: 	 */
fiore@0: 	@Override
fiore@0: 	public String detailedSpokenText(){
fiore@0: 		final String and = " and ";
fiore@0: 		StringBuilder b = new StringBuilder(getType());
fiore@0: 		b.append(' ').append(spokenText());
fiore@0: 		b.append(". Connecting ");
fiore@0: 		for(int i=0; i<getChildCount();i++){
fiore@3: 			b.append(((DiagramTreeNode)getChildAt(i)).getName());
fiore@0: 			b.append(and);
fiore@0: 		}
fiore@0: 		// remove the last " and "
fiore@0: 		b.delete(b.length()-and.length(), b.length());
fiore@0: 		return  b.toString();
fiore@0: 	}
fiore@0: 
fiore@0: 	/**
fiore@0: 	 * Set a label related to a node. On a graphical representation of the diagram 
fiore@0: 	 * the label would be put in proximity of the node. 
fiore@0: 	 * 
fiore@0: 	 * @param n the node,at whose end the label is located 
fiore@0: 	 * @param label the label
fiore@5: 	 * @param source the source of the action that triggered this method 
fiore@0: 	 */
fiore@3: 	public void setEndLabel(DiagramNode n, String label, Object source){
fiore@0: 		if(label == null)
fiore@0: 			label = "";
fiore@0: 		endLabels.put(n, label);
fiore@3: 		notifyChange(new ElementChangedEvent(this,n,"endLabel",source));
fiore@0: 	}
fiore@0: 
fiore@0: 	/**
fiore@0: 	 * Returns the end label related to a node. On a graphical representation of the diagram 
fiore@0: 	 * the label would be put in proximity of the node.
fiore@0: 	 * 
fiore@5: 	 * @param n the node, at whose end the label is located 
fiore@5: 	 * 
fiore@5: 	 * @return the label at the specified end 
fiore@0: 	 */
fiore@0: 	public String getEndLabel(DiagramNode n){
fiore@0: 		String s = endLabels.get(n);
fiore@0: 		if(s == null)
fiore@0: 			return "";
fiore@0: 		return s;
fiore@0: 	}
fiore@0: 
fiore@0: 	/**
fiore@0: 	 * Returns an array with all the available end description this edge can be 
fiore@0: 	 * assigned. 
fiore@0: 	 * @return an array of string available end description 
fiore@0: 	 */
fiore@0: 	public String[] getAvailableEndDescriptions(){
fiore@0: 		return this.availableEndDescriptions;
fiore@0: 	}   
fiore@0: 	
fiore@0: 	/**
fiore@0: 	 * Set a string describing the end related to a node. On a visual diagram this 
fiore@0: 	 * corresponds to an arrow.
fiore@0: 	 * 
fiore@0: 	 * @param n the node at the edge end whose description will be set
fiore@0: 	 * @param index an index of the array returned by getAvailableEndDescriptions(). The 
fiore@0: 	 * edge end description will be set with the string at that position in the array.
fiore@0: 	 * if index is equal to NO_END_DESCRIPTION_INDEX, then the description will be set 
fiore@0: 	 * as the empty string.
fiore@5: 	 * @param source the source of the action that triggered this method 
fiore@0: 	 * 
fiore@0: 	 */
fiore@3: 	public void setEndDescription(DiagramNode n, int index, Object source){
fiore@0: 		endDescriptions.put(n, index);
fiore@3: 		notifyChange(new ElementChangedEvent(this,n,"arrowHead",source));
fiore@0: 	}
fiore@0: 
fiore@0: 	/**
fiore@0: 	 * Returns a string describing the end related to a node. On a visual diagram this 
fiore@0: 	 * corresponds to an arrow.
fiore@0: 	 *    
fiore@0: 	 * @param n the node at the edge end whose description will be returned   
fiore@0: 	 * @return a description string
fiore@0: 	 */
fiore@0: 	public String getEndDescription(DiagramNode n){
fiore@0: 		Integer index = endDescriptions.get(n);
fiore@0: 		if(index == null || index == NO_END_DESCRIPTION_INDEX)
fiore@0: 			return "";
fiore@0: 		return availableEndDescriptions[endDescriptions.get(n)];
fiore@0: 	}
fiore@0: 
fiore@0: 	/**
fiore@0: 	 * Returns the connected node at the specified index  
fiore@0: 	 * @param index an index into node's list
fiore@0: 	 * @return the connected node at the specified index
fiore@0: 	 */
fiore@0: 	public abstract DiagramNode getNodeAt(int index);
fiore@0: 
fiore@0: 	/**
fiore@0: 	 * Returns the number of nodes this edge is connecting
fiore@0: 	 * @return the number of nodes this edge is connecting
fiore@0: 	 */
fiore@0: 	public abstract int getNodesNum();
fiore@0: 
fiore@0: 	/**
fiore@0: 	 * Removes a node from this edge. On a graphical representation of the diagram 
fiore@0: 	 * this would mean that the node is no longer connected to the other nodes via this edge. 
fiore@0: 	 * @param n the node to be removed
fiore@5: 	 * @param source the source of this action
fiore@0: 	 * @return true if the inner collection changed as a result of the call
fiore@0: 	 */
fiore@4: 	public abstract boolean removeNode(DiagramNode n, Object source);
fiore@0: 	
fiore@0: 	/**
fiore@0: 	 * Connect a list of nodes with this edge 
fiore@0: 	 * @param nodes a list of nodes to connect 
fiore@0: 	 * @throws ConnectNodesException if the number of nodes in the list is different 
fiore@0: 	 * from the number allowed by this edge.  
fiore@0: 	 */
fiore@0: 	public abstract void connect(List<DiagramNode> nodes) throws ConnectNodesException;
fiore@0: 
fiore@0: 	/**
fiore@3: 	 * An index to be passed to {@link #setEndDescription(DiagramNode, int, Object)} in order 
fiore@0: 	 * to set the edge with no description at the end related to that diagram node  
fiore@0: 	 */
fiore@0: 	public static int NO_END_DESCRIPTION_INDEX = -1;
fiore@0: 	private Map<DiagramNode,String> endLabels;
fiore@0: 	private Map<DiagramNode,Integer> endDescriptions;
fiore@0: 	private String[] availableEndDescriptions;
fiore@0: }