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: /**
f@0:  * This class identifies the source of a diagram event, that is an event generated by an action
f@0:  * in the diagram such as for instance a node insertion, deletion or renaming. The class carries informations
f@0:  * about how the event was generated (from the tree, from the graph etc.) and if the event was 
f@0:  * generated by the local user or another user co-editing the diagram. In either case an id of the
f@0:  * user is conveyed as well. An id is just a String each user assigns to themselves through a user
f@0:  * interface panel.  
f@0:  */
f@0: public class DiagramEventSource {
f@0: 	/**
f@0: 	 * An enumeration of the different ways an event can be generated. NONE is for when the 
f@0: 	 * information is not relevant (as normally no event listener will be triggered by the event).
f@0: 	 * PERS is for actions triggered when rebuilding a diagram from a ccmi file, so not as a consequence
f@0: 	 * of a direct user action. 
f@0: 	 */
f@0: 	public static enum Type{
f@0: 		TREE,
f@0: 		GRPH, // graph
f@0: 		HAPT, // haptics 
f@0: 		PERS, // persistence
f@0: 		NONE; 
f@0: 	}
f@0: 	
f@0: 	/* constructor used only by the static event sources */
f@0: 	private DiagramEventSource(Type type){
f@0: 		this.type = type;
f@0: 		local = true;
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Creates a new DiagramEventSource out of a previous one (normally one of the static default sources).
f@0: 	 * The type of the new object will be the same as the one passed as argument. Object created through
f@0: 	 * this constructor are marked as non local 
f@0: 	 * 
f@0: 	 * @see #isLocal()
f@0: 	 * @param eventSource an instance of this class 
f@0: 	 */
f@0: 	public DiagramEventSource(DiagramEventSource eventSource){
f@0: 		this.type = eventSource.type;
f@0: 		local = false;
f@0: 	}
f@0: 
f@0: 	/**
f@0: 	 * Returns true if the event is local, that is it's has been generated from an action of 
f@0: 	 * the local user and not from a message coming from the server. 
f@0: 	 * 
f@0: 	 * @return {@code true} if the event has been generated by the local user 
f@0: 	 */
f@0: 	public boolean isLocal(){
f@0: 		return local;
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Returns a copy of this event source that is marked as local.  
f@0: 	 *   
f@0: 	 * @return a local copy of this event source 
f@0: 	 * @see #isLocal()
f@0: 	 */
f@0: 	public DiagramEventSource getLocalSource(){
f@0: 		return new DiagramEventSource(type);
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Returns the name of the diagram where the event happened, that has this 
f@0: 	 * object as source.  
f@0: 	 * 
f@0: 	 * @return the name of the diagram
f@0: 	 */
f@0: 	public String getDiagramName(){
f@0: 		return diagramName;
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Sets the name of the diagram where the event happened, that has this 
f@0: 	 * object as source.
f@0: 	 * 
f@0: 	 * @param diagramName the name of the diagram 
f@0: 	 */
f@0: 	public void setDiagramName(String diagramName){
f@0: 		this.diagramName = diagramName;
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * The String representation of this object is the concatenation of the type
f@0: 	 * and the ID.
f@0: 	 * 
f@0: 	 * @return a String representing this object  
f@0: 	 */
f@0: 	@Override
f@0: 	public String toString(){
f@0: 		return (local ? ISLOCAL_CHAR : ISNOTLOCAL_CHAR )+type.toString();
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Returns an instance of this class out of a string representation, such as 
f@0: 	 * returned by {@code toString()}
f@0: 	 * @param s a String representation of a {@code DiagramEventSource} instance, such as 
f@0: 	 * returned by {@code toString()}
f@0: 	 * @return a new instance of {@code DiagramEventSource} 
f@0: 	 */
f@0: 	public static DiagramEventSource valueOf(String s){
f@0: 		Type t = Type.valueOf(s.substring(1, 5));
f@0: 		DiagramEventSource toReturn = new DiagramEventSource(t);
f@0: 		toReturn.local = (s.charAt(0) == ISLOCAL_CHAR) ? true : false;
f@0: 		return toReturn;
f@0: 	}
f@0: 	
f@0: 	private boolean local;
f@0: 	public final Type type;
f@0: 	private String diagramName;
f@0: 	private static char ISLOCAL_CHAR = 'L';
f@0: 	private static char ISNOTLOCAL_CHAR = 'R';
f@0: 	
f@0: 	/** Source for events triggered by the local user through the tree. These static sources
f@0: 	 *  are used when the diagram is not shared with any other user. When it is, a new DiagramEventSource
f@0: 	 *  will be created, which includes informations about the id and locality of the user who generated the event
f@0: 	 */
f@0: 	public static DiagramEventSource TREE = new DiagramEventSource(Type.TREE);
f@0: 	/** Source for events triggered by the local user through the graph */
f@0: 	public static DiagramEventSource GRPH = new DiagramEventSource(Type.GRPH);
f@0: 	/** Source for events triggered by the local user through the haptic device  */
f@0: 	public static DiagramEventSource HAPT = new DiagramEventSource(Type.HAPT);
f@0: 	/** Source for events triggered by the local user when opening a file */
f@0: 	public static DiagramEventSource PERS = new DiagramEventSource(Type.PERS);
f@0: 	/** Source for events not relevant to model listeners */
f@0: 	public static DiagramEventSource NONE = new DiagramEventSource(Type.NONE);
f@0: 
f@0: }