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.diagrammodel;
f@0: 
f@0: import java.util.LinkedHashMap;
f@0: import java.util.List;
f@0: import java.util.Map;
f@0: 
f@0: /**
f@0:  * This class represent an edge in the diagram model. Note that this class is 
f@0:  * a tree node.
f@0:  *
f@0:  */
f@0: @SuppressWarnings("serial")
f@0: public abstract class DiagramEdge extends DiagramElement {
f@0: 	/**
f@0: 	 * 
f@0: 	 * @param type the type of the edge 
f@0: 	 * @param availableEndDescriptions the end descriptions this edge allows 
f@0: 	 */
f@0: 	public DiagramEdge(String type, String[] availableEndDescriptions){
f@0: 		setType(type);
f@0: 		this.availableEndDescriptions = availableEndDescriptions;
f@0: 		endLabels = new LinkedHashMap<DiagramNode,String>();
f@0: 		endDescriptions = new LinkedHashMap<DiagramNode,Integer>();
f@0: 	}
f@0: 
f@0: 	/**
f@0: 	 * Returns a more detailed description of the edge than {@link #spokenText()}.
f@0: 	 * the description includes which nodes this edge is connecting 
f@0: 	 * 
f@0: 	 *  @return a description of the edge
f@0: 	 */
f@0: 	@Override
f@0: 	public String detailedSpokenText(){
f@0: 		final String and = " and ";
f@0: 		StringBuilder b = new StringBuilder(getType());
f@0: 		b.append(' ').append(spokenText());
f@0: 		b.append(". Connecting ");
f@0: 		for(int i=0; i<getChildCount();i++){
f@0: 			b.append(((DiagramTreeNode)getChildAt(i)).getName());
f@0: 			b.append(and);
f@0: 		}
f@0: 		// remove the last " and "
f@0: 		b.delete(b.length()-and.length(), b.length());
f@0: 		return  b.toString();
f@0: 	}
f@0: 
f@0: 	/**
f@0: 	 * Set a label related to a node. On a graphical representation of the diagram 
f@0: 	 * the label would be put in proximity of the node. 
f@0: 	 * 
f@0: 	 * @param n the node,at whose end the label is located 
f@0: 	 * @param label the label
f@0: 	 * @param source the source of the action that triggered this method 
f@0: 	 */
f@0: 	public void setEndLabel(DiagramNode n, String label, Object source){
f@0: 		if(label == null)
f@0: 			label = "";
f@0: 		endLabels.put(n, label);
f@0: 		notifyChange(new ElementChangedEvent(this,n,"endLabel",source));
f@0: 	}
f@0: 
f@0: 	/**
f@0: 	 * Returns the end label related to a node. On a graphical representation of the diagram 
f@0: 	 * the label would be put in proximity of the node.
f@0: 	 * 
f@0: 	 * @param n the node, at whose end the label is located 
f@0: 	 * 
f@0: 	 * @return the label at the specified end 
f@0: 	 */
f@0: 	public String getEndLabel(DiagramNode n){
f@0: 		String s = endLabels.get(n);
f@0: 		if(s == null)
f@0: 			return "";
f@0: 		return s;
f@0: 	}
f@0: 
f@0: 	/**
f@0: 	 * Returns an array with all the available end description this edge can be 
f@0: 	 * assigned. 
f@0: 	 * @return an array of string available end description 
f@0: 	 */
f@0: 	public String[] getAvailableEndDescriptions(){
f@0: 		return this.availableEndDescriptions;
f@0: 	}   
f@0: 	
f@0: 	/**
f@0: 	 * Set a string describing the end related to a node. On a visual diagram this 
f@0: 	 * corresponds to an arrow.
f@0: 	 * 
f@0: 	 * @param n the node at the edge end whose description will be set
f@0: 	 * @param index an index of the array returned by getAvailableEndDescriptions(). The 
f@0: 	 * edge end description will be set with the string at that position in the array.
f@0: 	 * if index is equal to NO_END_DESCRIPTION_INDEX, then the description will be set 
f@0: 	 * as the empty string.
f@0: 	 * @param source the source of the action that triggered this method 
f@0: 	 * 
f@0: 	 */
f@0: 	public void setEndDescription(DiagramNode n, int index, Object source){
f@0: 		endDescriptions.put(n, index);
f@0: 		notifyChange(new ElementChangedEvent(this,n,"arrowHead",source));
f@0: 	}
f@0: 
f@0: 	/**
f@0: 	 * Returns a string describing the end related to a node. On a visual diagram this 
f@0: 	 * corresponds to an arrow.
f@0: 	 *    
f@0: 	 * @param n the node at the edge end whose description will be returned   
f@0: 	 * @return a description string
f@0: 	 */
f@0: 	public String getEndDescription(DiagramNode n){
f@0: 		Integer index = endDescriptions.get(n);
f@0: 		if(index == null || index == NO_END_DESCRIPTION_INDEX)
f@0: 			return "";
f@0: 		return availableEndDescriptions[endDescriptions.get(n)];
f@0: 	}
f@0: 
f@0: 	/**
f@0: 	 * Returns the connected node at the specified index  
f@0: 	 * @param index an index into node's list
f@0: 	 * @return the connected node at the specified index
f@0: 	 */
f@0: 	public abstract DiagramNode getNodeAt(int index);
f@0: 
f@0: 	/**
f@0: 	 * Returns the number of nodes this edge is connecting
f@0: 	 * @return the number of nodes this edge is connecting
f@0: 	 */
f@0: 	public abstract int getNodesNum();
f@0: 
f@0: 	/**
f@0: 	 * Removes a node from this edge. On a graphical representation of the diagram 
f@0: 	 * this would mean that the node is no longer connected to the other nodes via this edge. 
f@0: 	 * @param n the node to be removed
f@0: 	 * @param source the source of this action
f@0: 	 * @return true if the inner collection changed as a result of the call
f@0: 	 */
f@0: 	public abstract boolean removeNode(DiagramNode n, Object source);
f@0: 	
f@0: 	/**
f@0: 	 * Connect a list of nodes with this edge 
f@0: 	 * @param nodes a list of nodes to connect 
f@0: 	 * @throws ConnectNodesException if the number of nodes in the list is different 
f@0: 	 * from the number allowed by this edge.  
f@0: 	 */
f@0: 	public abstract void connect(List<DiagramNode> nodes) throws ConnectNodesException;
f@0: 
f@0: 	/**
f@0: 	 * An index to be passed to {@link #setEndDescription(DiagramNode, int, Object)} in order 
f@0: 	 * to set the edge with no description at the end related to that diagram node  
f@0: 	 */
f@0: 	public static int NO_END_DESCRIPTION_INDEX = -1;
f@0: 	private Map<DiagramNode,String> endLabels;
f@0: 	private Map<DiagramNode,Integer> endDescriptions;
f@0: 	private String[] availableEndDescriptions;
f@0: }