comparison java/src/uk/ac/qmul/eecs/ccmi/gui/DiagramEventSource.java @ 3:9e67171477bc

PHANTOM Omni Heptic device release

+/*  
+ CCmI Editor - A Collaborative Cross-Modal Diagram Editing Tool
+  
+ Copyright (C) 2011  Queen Mary University of London (http://ccmi.eecs.qmul.ac.uk/)
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/  
+package uk.ac.qmul.eecs.ccmi.gui;
+
+/**
+ * This class identifies the source of a diagram event, that is an event generated by an action
+ * in the diagram such as for instance a node insertion, deletion or renaming. The class carries informations
+ * about how the event was generated (from the tree, from the graph etc.) and if the event was 
+ * generated by the local user or another user co-editing the diagram. In either case an id of the
+ * user is conveyed as well. An id is just a String each user assigns to themselves through a user
+ * interface panel.  
+ */
+public class DiagramEventSource {
+	/**
+	 * An enumeration of the different ways an event can be generated. NONE is for when the 
+	 * information is not relevant (as normally no event listener will be triggered by the event).
+	 * PERS is for actions triggered when rebuilding a diagram from a ccmi file, so not as a consequence
+	 * of a direct user action. 
+	 */
+	public static enum Type{
+		TREE,
+		GRPH, // graph
+		HAPT, // haptics 
+		PERS, // persistence
+		NONE; 
+	}
+	
+	/* constructor used only by the static event sources */
+	private DiagramEventSource(Type type){
+		this.type = type;
+		local = true;
+	}
+	
+	/**
+	 * Creates a new DiagramEventSource out of a previous one (normally one of the static default sources).
+	 * The type of the new object will be the same as the one passed as argument. Object created through
+	 * this constructor are marked as non local 
+	 * 
+	 * @see #isLocal()
+	 * @param eventSource an instance of this class 
+	 */
+	public DiagramEventSource(DiagramEventSource eventSource){
+		this.type = eventSource.type;
+		local = false;
+	}
+
+	/**
+	 * Returns true if the event is local, that is it's has been generated from an action of 
+	 * the local user and not from a message coming from the server. 
+	 * 
+	 * @return {@code true} if the event has been generated by the local user 
+	 */
+	public boolean isLocal(){
+		return local;
+	}
+	
+	/**
+	 * Returns a copy of this event source that is marked as local.  
+	 *   
+	 * @return a local copy of this event source 
+	 * @see #isLocal()
+	 */
+	public DiagramEventSource getLocalSource(){
+		return new DiagramEventSource(type);
+	}
+	
+	/**
+	 * Returns the name of the diagram where the event happened, that has this 
+	 * object as source.  
+	 * 
+	 * @return the name of the diagram
+	 */
+	public String getDiagramName(){
+		return diagramName;
+	}
+	
+	/**
+	 * Sets the name of the diagram where the event happened, that has this 
+	 * object as source.
+	 * 
+	 * @param diagramName the name of the diagram 
+	 */
+	public void setDiagramName(String diagramName){
+		this.diagramName = diagramName;
+	}
+	
+	/**
+	 * The String representation of this object is the concatenation of the type
+	 * and the ID.
+	 * 
+	 * @return a String representing this object  
+	 */
+	@Override
+	public String toString(){
+		return (local ? ISLOCAL_CHAR : ISNOTLOCAL_CHAR )+type.toString();
+	}
+	
+	/**
+	 * Returns an instance of this class out of a string representation, such as 
+	 * returned by {@code toString()}
+	 * @param s a String representation of a {@code DiagramEventSource} instance, such as 
+	 * returned by {@code toString()}
+	 * @return a new instance of {@code DiagramEventSource} 
+	 */
+	public static DiagramEventSource valueOf(String s){
+		Type t = Type.valueOf(s.substring(1, 5));
+		DiagramEventSource toReturn = new DiagramEventSource(t);
+		toReturn.local = (s.charAt(0) == ISLOCAL_CHAR) ? true : false;
+		return toReturn;
+	}
+	
+	private boolean local;
+	public final Type type;
+	private String diagramName;
+	private static char ISLOCAL_CHAR = 'L';
+	private static char ISNOTLOCAL_CHAR = 'R';
+	
+	/** Source for events triggered by the local user through the tree. These static sources
+	 *  are used when the diagram is not shared with any other user. When it is, a new DiagramEventSource
+	 *  will be created, which includes informations about the id and locality of the user who generated the event
+	 */
+	public static DiagramEventSource TREE = new DiagramEventSource(Type.TREE);
+	/** Source for events triggered by the local user through the graph */
+	public static DiagramEventSource GRPH = new DiagramEventSource(Type.GRPH);
+	/** Source for events triggered by the local user through the haptic device  */
+	public static DiagramEventSource HAPT = new DiagramEventSource(Type.HAPT);
+	/** Source for events triggered by the local user when opening a file */
+	public static DiagramEventSource PERS = new DiagramEventSource(Type.PERS);
+	/** Source for events not relevant to model listeners */
+	public static DiagramEventSource NONE = new DiagramEventSource(Type.NONE);
+
+}