annotate java/src/uk/ac/qmul/eecs/ccmi/diagrammodel/TreeModel.java @ 8:ea7885bd9bff tip

fixed bug : render solid line as dotted/dashed when moving the stylus from dotted/dashed to solid

/*  
 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.diagrammodel;

import java.util.Set;
import java.util.concurrent.locks.ReentrantLock;

/**
 * 
 * Represents the tree side of a DiagramModel instance. 
 *
 * @param <N> a type extending DiagramNode
 * @param <E> a type extending DiagramEdge
 */
public interface TreeModel<N extends DiagramNode, E extends DiagramEdge> extends javax.swing.tree.TreeModel {
	
	/**
	 * insert a DiagramNode into the diagram model
	 * 
	 * @param treeNode the DiagramNode to be inserted in the collection
	 * @param source the source of the action. This will be reported as the source of the event 
	 * generated by this action to the registered listeners. If null the TreeModel instance
	 * itself will be used as source 
	 * @return true if the model changed as a result of the call
	 */
	boolean insertTreeNode(N treeNode, Object source);
	
	/**
	 * insert a DiagramEdge into the diagram model
	 * 
	 * @param treeNode the DiagramEdge to be inserted in the collection
	 * @param source the source of the action. This will be reported as the source of the event 
	 * generated by this action to the registered listeners. If null the TreeModel instance
	 * itself will be used as source
	 * @return true if the model changed as a result of the call
	 */
	boolean insertTreeNode(E treeNode, Object source);
	
	/**
	 * remove a DiagramElement from the model 
	 * 
	 * @param treeNode the diagramElement to be removed 
	 * @param source the source of the action. This will be reported as the source of the event 
	 * generated by this action to the registered listeners. If null the TreeModel instance
	 * itself will be used as source
	 * @return true if the model changed as a result of the call
	 */
	boolean takeTreeNodeOut(DiagramElement treeNode, Object source);
	
	/**
	 * 
	 * Add a bookmark for the specified tree node in the internal collection
	 * 
	 * @param bookmark a bookmark 
	 * @param treeNode the tree node to be bookmarked
	 * @param source the sorce of the action that triggered this method 
	 * @return previous value associated with specified key, or null if there was no mapping for key.
	 * @throws IllegalArgumentException if bookmark is null 
	 */
	DiagramTreeNode putBookmark(String bookmark, DiagramTreeNode treeNode, Object source);
	
	/**
	 * Returns a bookmarked tree node
	 * @param bookmark the bookmark associated with the tree node
	 * @return the bookmarked tree node or null if no tree node was bookmarked with the argument
	 */
	DiagramTreeNode getBookmarkedTreeNode(String bookmark);
	
	/**
	 * Returns the list of all the bookmarks of this tree model
	 * @return the list of all the bookmarks
	 */
	Set<String> getBookmarks();
	
	/**
	 * Remove the bookmark from the bookmark internal collection
	 * 
	 * @param bookmark the bookmark to remove
	 * @param source the source of the action that triggered this method 
	 * @return previous value associated with specified key, or null if there was no mapping for key.
	 */
	DiagramTreeNode removeBookmark(String bookmark, Object source);
	
	/**
	 * Set the notes for the specified tree node. Passing an empty string as notes 
	 * means actually to remove the notes from the tree node. 
	 *  
	 * @param treeNode the tree node to be noted 
	 * @param notes the notes to be assigned to the tree node 
	 * @param source the source of the action. This will be reported as the source of the event 
	 * generated by this action to the registered listeners  
	 */
	void setNotes(DiagramTreeNode treeNode, String notes, Object source);
	
	/**
	 * Add a {@code DiagramNodeListener} to this object. The listeners will be fired each time the model 
	 * goes from the unmodified to modified state. The model is modified when a either a 
	 * node or an edge are inserted or removed or changed when they are within the model.    
	 * @param l a {@code DiagramNodeListener} to add to the model  
	 */
	void addDiagramTreeNodeListener(DiagramTreeNodeListener l);
	
	/**
	 * Removes a {@code DiagramNodeListener} from this object. 
	 * @param l a {@code DiagramNodeListener} to remove from ththis object.
	 */
	void removeDiagramTreeNodeListener(DiagramTreeNodeListener l);
	
	/**
	 * Returns true if the model has been modified
	 * @return true if the model has been modified
	 */
	boolean isModified();
	
	/**
	 * Sets the model as unmodified. This entails that {@link #isModified()} will return 
	 * false unless the model doesn't get modified again. After this call a new modification
	 * of the model would trigger the associated change listeners again. 
	 */
	public void setUnmodified();
	
	/**
	 * Returns a reentrant lock that can be used to access the nodes and edges in a synchronized fashion.   
	 * @return a lock object
	 */
	public ReentrantLock getMonitor();
}