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: 
f@0: package uk.ac.qmul.eecs.ccmi.gui;
f@0: 
f@0: import java.awt.Frame;
f@0: import java.util.Collection;
f@0: 
f@0: /**
f@0:  * A template editor is used to create new types of diagrams. 
f@0:  * 
f@0:  * Template editors are run in the Event Dispatching Thread and can therefore make use of <i>Swing</i> components
f@0:  * to prompt the user with choices about the diagram to be created. The diagram created by 
f@0:  * a template editor is precisely a prototype.
f@0:  * Such prototypes diagrams will then be used 
f@0:  * to create new diagram instances (the actual diagrams operated by the user) through clonation.    
f@0:  * When a diagram prototype is created, it's added in the File->new Diagram menu. 
f@0:  */
f@0: public interface TemplateEditor {
f@0: 	
f@0: 	/**
f@0: 	 * Creates a new {@code Diagram}
f@0: 	 * 
f@0: 	 * @param frame the frame where the template editor is run
f@0: 	 * @param existingTemplates the names of already existing templates. The creation 
f@0: 	 * of a new {@code Diagram} with an already existing name must be prevented in order
f@0: 	 * to keep the consistency of the diagram templates. 
f@0: 	 * 
f@0: 	 * @return a new {@code Diagram} prototype
f@0: 	 */
f@0: 	public Diagram createNew(Frame frame, Collection<String> existingTemplates);
f@0: 	
f@0: 	/**
f@0: 	 * Edits an existing {@code Diagram} prototype.  
f@0: 	 *  
f@0: 	 * @param frame the frame where the template editor is run
f@0: 	 * @param existingTemplates the names of already existing templates. The creation 
f@0: 	 * of a new {@code Diagram} with an already existing name must be prevented in order
f@0: 	 * to keep the consistency of the diagram templates. 
f@0: 	 * @param diagram the diagram to edit 
f@0: 	 * @return a changed version of {@code diagram} 
f@0: 	 */
f@0: 	public Diagram edit(Frame frame, Collection<String> existingTemplates, Diagram diagram);
f@0: 	
f@0: 	/**
f@0: 	 * Templates editor methods are going to be called by the user via a menu item. This method
f@0: 	 * returns the label {@code createNew} menu item.
f@0: 	 * 
f@0: 	 * @return a label for the menu item which triggers the creation of a new template through this
f@0: 	 * template editor
f@0: 	 */
f@0: 	public String getLabelForNew();
f@0: 	
f@0: 	/**
f@0: 	 * Templates editor methods are going to be called by the user via a menu item. This method
f@0: 	 * returns the label {@code edit} menu item.
f@0: 	 * 
f@0: 	 * @return a label for the menu item which triggers the editing of a new template through this
f@0: 	 * template editor
f@0: 	 */
f@0: 	public String getLabelForEdit();
f@0: }