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: import java.awt.event.ActionEvent;
f@0: import java.awt.event.InputEvent;
f@0: import java.awt.event.KeyEvent;
f@0: import java.awt.event.MouseEvent;
f@0: import java.io.InputStream;
f@0: import java.text.MessageFormat;
f@0: import java.util.ArrayList;
f@0: import java.util.List;
f@0: import java.util.ResourceBundle;
f@0: 
f@0: import javax.swing.AbstractAction;
f@0: import javax.swing.JOptionPane;
f@0: import javax.swing.JTree;
f@0: import javax.swing.KeyStroke;
f@0: import javax.swing.event.TreeModelEvent;
f@0: import javax.swing.event.TreeModelListener;
f@0: import javax.swing.tree.DefaultMutableTreeNode;
f@0: import javax.swing.tree.TreeNode;
f@0: import javax.swing.tree.TreePath;
f@0: import javax.swing.tree.TreeSelectionModel;
f@0: 
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramElement;
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramTreeNode;
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramNode;
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.EdgeReferenceMutableTreeNode;
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.NodeReferenceMutableTreeNode;
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.TreeModel;
f@0: import uk.ac.qmul.eecs.ccmi.diagrammodel.TypeMutableTreeNode;
f@0: import uk.ac.qmul.eecs.ccmi.network.Command;
f@0: import uk.ac.qmul.eecs.ccmi.network.DiagramEventActionSource;
f@0: import uk.ac.qmul.eecs.ccmi.sound.PlayerListener;
f@0: import uk.ac.qmul.eecs.ccmi.sound.SoundEvent;
f@0: import uk.ac.qmul.eecs.ccmi.sound.SoundFactory;
f@0: import uk.ac.qmul.eecs.ccmi.speech.Narrator;
f@0: import uk.ac.qmul.eecs.ccmi.speech.NarratorFactory;
f@0: import uk.ac.qmul.eecs.ccmi.speech.SpeechUtilities;
f@0: import uk.ac.qmul.eecs.ccmi.utils.InteractionLog;
f@0: 
f@0: 
f@0: @SuppressWarnings("serial")
f@0: public class DiagramTree extends JTree {
f@0: 	/**
f@0: 	 * Creates a new diagram tree. The model of this tree is set to the tree model 
f@0: 	 * held by the instance of {@code Diagram} passed as argument. The model is retrieved by a call 
f@0: 	 * to {@code getTreeModel()} on the diagram.
f@0: 	 * <p>
f@0: 	 * The tree doesn't allow interaction via the mouse. It can be navigated via the keyboard using 
f@0: 	 * the arrow keys. When a node is selected, cursoring up and down allows the user to go through
f@0: 	 * all the sibling of the selected node. Cursoring right will expand the selected node (if it has children)
f@0: 	 * and select its first child. Cursoring left will collapse a node and select its father. All the motions
f@0: 	 * trigger a text to speech utterance (possibly accompanied by sound) about the new selected node.       
f@0: 	 * 
f@0: 	 * @param diagram a reference to the diagram holding the tree model for this tree. 
f@0: 	 */
f@0: 	public DiagramTree(Diagram diagram){
f@0: 		super(diagram.getTreeModel());
f@0: 		this.diagram = diagram;
f@0: 		resources = ResourceBundle.getBundle(EditorFrame.class.getName());
f@0: 		
f@0: 		TreePath rootPath = new TreePath((DiagramTreeNode)diagram.getTreeModel().getRoot());
f@0: 		setSelectionPath(rootPath);
f@0: 		collapsePath(rootPath);
f@0: 		selectedNodes = new ArrayList<Node>();
f@0: 		setEditable(false);
f@0: 	    getSelectionModel().setSelectionMode(TreeSelectionModel.SINGLE_TREE_SELECTION);
f@0: 	    overwriteTreeKeystrokes();
f@0: 	    /* don't use the swing focus system as we provide one on our own */
f@0: 	    setFocusTraversalKeysEnabled(false);
f@0: 	    getAccessibleContext().setAccessibleName("tree");
f@0: 	}
f@0: 	
f@0: 	@SuppressWarnings("unchecked")
f@0: 	@Override
f@0: 	public TreeModel<Node,Edge> getModel(){
f@0: 		return (TreeModel<Node,Edge>)super.getModel();
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * @see javax.swing.JTree#setModel(javax.swing.tree.TreeModel)
f@0: 	 * 
f@0: 	 * @param newModel the new model for this tree
f@0: 	 */
f@0: 	public void setModel(TreeModel<Node,Edge> newModel){
f@0: 		DiagramTreeNode selectedTreeNode = (DiagramTreeNode)getSelectionPath().getLastPathComponent();
f@0: 		super.setModel(newModel);
f@0: 		collapseRow(0);
f@0: 		setSelectionPath(new TreePath(selectedTreeNode.getPath()));
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Set a new diagram for this tree. As a result of this call the tree model 
f@0: 	 * of this tree will be set to the model return by {@code diagram.getTreeModel()} 
f@0: 	 *	
f@0: 	 * @param diagram the new diagram for this tree 
f@0: 	 */
f@0: 	public void setDiagram(Diagram diagram){
f@0: 		this.diagram = diagram;
f@0: 		setModel(diagram.getTreeModel());
f@0: 	}
f@0: 	
f@0: 	private void selectNode(final Node n){
f@0: 		selectedNodes.add(n);
f@0: 		treeModel.valueForPathChanged(new TreePath(n.getPath()),n.getName());
f@0: 		
f@0: 		SoundFactory.getInstance().play(SoundEvent.OK,new PlayerListener(){
f@0: 			@Override
f@0: 			public void playEnded() {
f@0: 				NarratorFactory.getInstance().speak(MessageFormat.format(resources.getString("speech.node_selected"),n.spokenText()));
f@0: 			}
f@0: 		});
f@0: 		InteractionLog.log(INTERACTIONLOG_SOURCE,"node selected for edge",n.getName());
f@0: 	}
f@0: 	
f@0: 	private void unselectNode(final Node n){
f@0: 		selectedNodes.remove(n);
f@0: 		treeModel.valueForPathChanged(new TreePath(n.getPath()),n.getName());
f@0: 		
f@0: 		SoundFactory.getInstance().play(SoundEvent.OK,new PlayerListener(){
f@0: 			@Override
f@0: 			public void playEnded() {
f@0: 				NarratorFactory.getInstance().speak(MessageFormat.format(resources.getString("speech.node_unselected"),n.spokenText()));
f@0: 			}
f@0: 		});
f@0: 		InteractionLog.log(INTERACTIONLOG_SOURCE,"node unselected for edge",DiagramElement.toLogString(n));
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Returns an array containing the references to all the nodes that have so far been selected 
f@0: 	 * for edge creation. A new array is created each time this method is called. 
f@0: 	 * 
f@0: 	 * @return an array of nodes
f@0: 	 */
f@0: 	public DiagramNode[] getSelectedNodes(){
f@0: 		DiagramNode[] array = new DiagramNode[selectedNodes.size()]; 
f@0: 		return selectedNodes.toArray(array);
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Makes all the nodes selected for edge creation unselected. This method should 
f@0: 	 * be called after an edge has been created, to get the user restart 
f@0: 	 * go over the selection process again.   
f@0: 	 * 
f@0: 	 */
f@0: 	public void clearNodeSelections(){
f@0: 		ArrayList<Node> tempList = new ArrayList<Node>(selectedNodes);
f@0: 		selectedNodes.clear();
f@0: 		for(Node n : tempList){
f@0: 			treeModel.valueForPathChanged(new TreePath(n.getPath()),n.getName());
f@0: 			diagram.getModelUpdater().yieldLock(n, Lock.MUST_EXIST, new DiagramEventActionSource(DiagramEventSource.TREE,Command.Name.INSERT_EDGE,n.getId(),n.getName()));
f@0: 		}
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Returns a string for a text to speech synthesizer, describing the currently selected 
f@0: 	 * tree node. The one that is at the end of the current selection path. 
f@0: 	 * 
f@0: 	 * @return a description string suitable for text to speech synthesis 
f@0: 	 */
f@0: 	public String currentPathSpeech(){
f@0: 		TreePath path =	getSelectionPath();
f@0: 		DiagramTreeNode selectedPathTreeNode = (DiagramTreeNode)path.getLastPathComponent();
f@0: 		if(selectedNodes.contains(selectedPathTreeNode))
f@0: 			/* add information about the fact that the node is selected */
f@0: 			return MessageFormat.format(resources.getString("speech.node_selected"), selectedPathTreeNode.spokenText());
f@0: 		else
f@0: 			return selectedPathTreeNode.spokenText();
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Changes the selected tree path from the current to one defined by 
f@0: 	 * the {@code JumpTo enum} 
f@0: 	 * 
f@0: 	 * @see JumpTo
f@0: 	 * 
f@0: 	 * @param jumpTo a {@code JumpTo enum}
f@0: 	 */
f@0: 	public void jump(JumpTo jumpTo){
f@0: 		final Narrator narrator = NarratorFactory.getInstance();
f@0: 		TreePath oldPath;
f@0: 		switch(jumpTo){
f@0: 		case REFERENCE :
f@0: 			oldPath = getSelectionPath();
f@0: 			DiagramTreeNode selectedTreeNode = (DiagramTreeNode)oldPath.getLastPathComponent();
f@0: 			if(selectedTreeNode instanceof NodeReferenceMutableTreeNode){
f@0: 				final Node n = (Node)((NodeReferenceMutableTreeNode)selectedTreeNode).getNode();
f@0: 				setSelectionPath(new TreePath(n.getPath()));
f@0: 				SoundFactory.getInstance().play(SoundEvent.JUMP, new PlayerListener(){
f@0: 					   @Override
f@0: 					   public void playEnded() {
f@0: 						   narrator.speak(MessageFormat.format(resources.getString("speech.jump"),n.spokenText()));
f@0: 					   }
f@0: 				});
f@0: 			}else if(selectedTreeNode instanceof EdgeReferenceMutableTreeNode){
f@0: 				final Edge e = (Edge)((EdgeReferenceMutableTreeNode)selectedTreeNode).getEdge();
f@0: 				setSelectionPath(new TreePath(e.getPath()));
f@0: 				SoundFactory.getInstance().play(SoundEvent.JUMP,new PlayerListener(){
f@0: 					   @Override
f@0: 					   public void playEnded() {
f@0: 						   narrator.speak(MessageFormat.format(resources.getString("speech.jump"),e.spokenText()));
f@0: 					   }
f@0: 				   });
f@0: 			}
f@0: 			/* assume the referee has only root in common with the reference and collapse everything up to the root (excluded) */
f@0: 			collapseAll(selectedTreeNode, (DiagramTreeNode)selectedTreeNode.getPath()[1]);
f@0: 			break;
f@0: 		case ROOT :
f@0: 			final DiagramTreeNode from =(DiagramTreeNode)getSelectionPath().getLastPathComponent();
f@0: 			setSelectionRow(0);
f@0: 			collapseAll(from,from.getRoot());
f@0: 			SoundFactory.getInstance().play(SoundEvent.JUMP, new PlayerListener(){
f@0: 				   @Override
f@0: 				   public void playEnded() {
f@0: 					   narrator.speak(MessageFormat.format(resources.getString("speech.jump"),from.getRoot().spokenText()));
f@0: 				   }
f@0: 			   });
f@0: 			break;
f@0: //		case TYPE : // jumps to the ancestor type node of the current node, never used
f@0: //			oldPath = getSelectionPath();
f@0: //			int index = 0;
f@0: //			Object[] pathComponents = oldPath.getPath();
f@0: //			for(int i=0;i<pathComponents.length;i++){
f@0: //				if(pathComponents[i] instanceof TypeMutableTreeNode){
f@0: //					index=i;
f@0: //					break;
f@0: //				}
f@0: //			}
f@0: //			final DiagramTreeNode typeTreeNode = (DiagramTreeNode)oldPath.getPathComponent(index); 
f@0: //			setSelectionPath(new TreePath(typeTreeNode.getPath()));
f@0: //			collapseAll((DiagramTreeNode)oldPath.getLastPathComponent(),typeTreeNode);
f@0: //			SoundFactory.getInstance().play(SoundEvent.JUMP, new PlayerListener(){
f@0: //				   @Override
f@0: //				   public void playEnded() {
f@0: //					   narrator.speak(MessageFormat.format(resources.getString("speech.jump"),typeTreeNode.spokenText()));
f@0: //				   }
f@0: //			   });
f@0: //			break;
f@0: 		case SELECTED_TYPE :
f@0: 			DiagramTreeNode root = (DiagramTreeNode)getModel().getRoot();
f@0: 			Object[] types = new Object[root.getChildCount()];
f@0: 			for(int i=0; i< root.getChildCount();i++)
f@0: 				types[i] = ((TypeMutableTreeNode)root.getChildAt(i)).getName();//not to spokenText as it would be too long
f@0: 			oldPath = getSelectionPath();
f@0: 			/* initial value is the type node whose branch node is currently selected */
f@0: 			/* it is set as the first choice in the selection dialog */
f@0: 			Object initialValue;
f@0: 			if(oldPath.getPath().length < 2)
f@0: 				initialValue = types[0];
f@0: 			else
f@0: 				initialValue = oldPath.getPathComponent(1);//type tree  node
f@0: 			/* the selection from the OptionPane is the stering returned by getName() */
f@0: 			InteractionLog.log(INTERACTIONLOG_SOURCE,"open select type to jump dialog","");
f@0: 			final String selectedValue = (String)SpeechOptionPane.showSelectionDialog(
f@0: 					SpeechOptionPane.getFrameForComponent(this),
f@0: 					"select type to jump to", 
f@0: 					types, 
f@0: 					initialValue);
f@0: 			if(selectedValue == null){
f@0: 				/* it speaks anyway as we set up the playerListener in the EditorFrame class. No need to use narrator then */
f@0: 				SoundFactory.getInstance().play(SoundEvent.CANCEL);
f@0: 				InteractionLog.log(INTERACTIONLOG_SOURCE,"cancel select type to jump dialog","");
f@0: 				return;
f@0: 			}
f@0: 			/* we search in the root which type tree node has getName() equal to the selected one */
f@0: 			TypeMutableTreeNode typeNode = null;
f@0: 			for(int i = 0; i< root.getChildCount(); i++){
f@0: 				TypeMutableTreeNode temp = (TypeMutableTreeNode)root.getChildAt(i);
f@0: 				if(temp.getName().equals(selectedValue)){
f@0: 					typeNode = temp;
f@0: 					break;
f@0: 				}
f@0: 			}
f@0: 			setSelectionPath(new TreePath(typeNode.getPath()));
f@0: 			if(oldPath.getPath().length >= 2)
f@0: 				collapseAll((DiagramTreeNode)oldPath.getLastPathComponent(), (DiagramTreeNode)initialValue);
f@0: 			SoundFactory.getInstance().play(SoundEvent.JUMP, new PlayerListener(){
f@0: 				   @Override
f@0: 				   public void playEnded() {
f@0: 					   narrator.speak(MessageFormat.format(resources.getString("speech.jump"),selectedValue));
f@0: 				   }
f@0: 			   });
f@0: 			break;
f@0: 		case BOOKMARK :
f@0: 			TreeModel<Node,Edge> treeModel = getModel(); 
f@0: 			
f@0: 			if(treeModel.getBookmarks().size() == 0){
f@0: 				SoundFactory.getInstance().play(SoundEvent.ERROR ,new PlayerListener(){
f@0: 					   @Override
f@0: 					   public void playEnded() {
f@0: 						   narrator.speak(resources.getString("speech.no_bookmarks"));
f@0: 					   }
f@0: 				   });
f@0: 				InteractionLog.log(INTERACTIONLOG_SOURCE,"no bookmarks available","");
f@0: 				return;
f@0: 			}
f@0: 
f@0: 			String[] bookmarkArray = new String[treeModel.getBookmarks().size()];
f@0: 			bookmarkArray = treeModel.getBookmarks().toArray(bookmarkArray);
f@0: 
f@0: 			InteractionLog.log(INTERACTIONLOG_SOURCE,"open select bookmark dialog","");
f@0: 			String bookmark = (String)SpeechOptionPane.showSelectionDialog(
f@0: 					JOptionPane.getFrameForComponent(this), 
f@0: 					"Select bookmark",
f@0: 					bookmarkArray,
f@0: 					bookmarkArray[0]
f@0: 			);
f@0: 
f@0: 			if(bookmark != null){
f@0: 				oldPath = getSelectionPath();
f@0: 				DiagramTreeNode treeNode = treeModel.getBookmarkedTreeNode(bookmark);
f@0: 				collapseAll((DiagramTreeNode)oldPath.getLastPathComponent(), (DiagramTreeNode)treeModel.getRoot());
f@0: 				setSelectionPath(new TreePath(treeNode.getPath()));
f@0: 				final String currentPathSpeech = currentPathSpeech();
f@0: 				SoundFactory.getInstance().play(SoundEvent.JUMP, new PlayerListener(){
f@0: 					   @Override
f@0: 					   public void playEnded() {
f@0: 						   narrator.speak(currentPathSpeech);
f@0: 					   }
f@0: 				   });
f@0: 				InteractionLog.log(INTERACTIONLOG_SOURCE,"bookmark selected",bookmark);
f@0: 			}else{
f@0: 				/* it speaks anyway, as we set up the speech in the EditorFrame class. no need to use the narrator then */
f@0: 				SoundFactory.getInstance().play(SoundEvent.CANCEL);
f@0: 				InteractionLog.log(INTERACTIONLOG_SOURCE,"cancel select bookmark dialog","");
f@0: 				return;
f@0: 			}
f@0: 			break;
f@0: 			
f@0: 		}
f@0: 		InteractionLog.log(INTERACTIONLOG_SOURCE,"jumped to "+jumpTo.toString(),((DiagramTreeNode)getSelectionPath().getLastPathComponent()).getName());
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Changes the selected tree path from the current to the one from the root
f@0: 	 * to the {@code Diagramelement} passed as argument. Note that a {@code Diagramelement}
f@0: 	 * is also an instance of {@code DuagramTreeNode} and it's placed in a {@code TreeModel}
f@0: 	 * when it's inserted into a {@code DiagramModel}
f@0: 	 * 
f@0: 	 * @param de the diagram element to be selected on the tree 
f@0: 	 */
f@0: 	public void jumpTo(final DiagramElement de){
f@0: 		TreePath oldPath = getSelectionPath();
f@0: 		collapseAll((DiagramTreeNode)oldPath.getLastPathComponent(),de);
f@0: 		setSelectionPath(new TreePath(de.getPath()));
f@0: 		SoundFactory.getInstance().play( SoundEvent.JUMP, new PlayerListener(){
f@0: 			@Override
f@0: 			public void playEnded() {
f@0: 				NarratorFactory.getInstance().speak(MessageFormat.format(resources.getString("speech.jump"),de.spokenText()));
f@0: 			}
f@0: 		});
f@0: 	}
f@0: 	
f@0: 	/* collapse all the nodes in the path from "from" to "to" upwards(with the same direction as going from a leaf to the root)*/
f@0: 	private void collapseAll(DiagramTreeNode from, DiagramTreeNode to){
f@0: 		DiagramTreeNode currentNode = from;
f@0: 		while(currentNode.getParent() != null && currentNode != to){
f@0: 			currentNode = currentNode.getParent();
f@0: 			collapsePath(new TreePath(currentNode.getPath()));
f@0: 		}
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Mouse events are ignored by this tree. This is just a blank method.
f@0: 	 * 
f@0: 	 * @param e a mouse event
f@0: 	 */
f@0: 	@Override
f@0: 	protected  void	processMouseEvent(MouseEvent e){
f@0: 		//do nothing as the tree does not have to be editable with mouse
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Allows only cursor keys, tab key, delete, and actions (CTRL+something)
f@0: 	 * 
f@0: 	 * @param e a key event 
f@0: 	 */
f@0: 	@Override
f@0: 	protected void processKeyEvent(KeyEvent e){
f@0: 		/* allow only cursor keys, tab key, delete, and actions (CTRL+something) */
f@0: 		if(e.getKeyChar() == KeyEvent.CHAR_UNDEFINED 
f@0: 				|| e.getKeyCode() == KeyEvent.VK_TAB
f@0: 					|| e.getKeyCode() == KeyEvent.VK_SPACE
f@0: 				 			|| e.isControlDown()
f@0: 				 				|| e.isAltDown())
f@0: 			super.processKeyEvent(e);
f@0: 	}
f@0: 	
f@0: 	private void overwriteTreeKeystrokes() {
f@0: 		   /* overwrite the keys. up and down arrow are overwritten so that it loops when the top and the  */
f@0: 		   /* bottom are reached rather than getting stuck                               */ 
f@0: 		   
f@0: 		   /* Overwrite keystrokes up,down,left,right arrows and space, shift, ctrl */
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_DOWN,0),"down");
f@0: 		   getActionMap().put("down", new AbstractAction(){
f@0: 				@Override
f@0: 				public void actionPerformed(ActionEvent evt) {
f@0: 					DiagramTreeNode treeNode = (DiagramTreeNode)getLastSelectedPathComponent();
f@0: 					/* look if we've got a sibling node after (we are not at the bottom) */
f@0: 					DiagramTreeNode nextTreeNode = treeNode.getNextSibling(); 
f@0: 					SoundEvent loop = null;
f@0: 					if(nextTreeNode == null){
f@0: 						DiagramTreeNode parent = treeNode.getParent();
f@0: 						if(parent == null) /* root node, just stay there */
f@0: 							nextTreeNode = treeNode;
f@0: 						else /* loop = go to first child of own parent */
f@0: 							nextTreeNode = (DiagramTreeNode)parent.getFirstChild();
f@0: 						loop = SoundEvent.LIST_BOTTOM_REACHED;
f@0: 					}
f@0: 					setSelectionPath(new TreePath(nextTreeNode.getPath()));
f@0: 					final InputStream finalSound  = getTreeNodeSound(nextTreeNode);
f@0: 					final String currentPathSpeech = currentPathSpeech();
f@0: 					SoundFactory.getInstance().play(loop, new PlayerListener(){
f@0: 						public void playEnded() {
f@0: 							SoundFactory.getInstance().play(finalSound);
f@0: 							NarratorFactory.getInstance().speak(currentPathSpeech);
f@0: 						}
f@0: 					});
f@0: 					InteractionLog.log(INTERACTIONLOG_SOURCE,"move down",nextTreeNode.toString());
f@0: 				}});
f@0: 		   
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_UP,0),"up");
f@0: 		   getActionMap().put("up", new AbstractAction(){
f@0: 				@Override
f@0: 				public void actionPerformed(ActionEvent evt) {
f@0: 					DiagramTreeNode treeNode = (DiagramTreeNode)getLastSelectedPathComponent();
f@0: 					DiagramTreeNode previousTreeNode = treeNode.getPreviousSibling();
f@0: 					SoundEvent loop = null;
f@0: 					if(previousTreeNode == null){
f@0: 						DiagramTreeNode parent = treeNode.getParent();
f@0: 						if(parent == null) /* root node */
f@0: 							previousTreeNode = treeNode;
f@0: 						else 
f@0: 							previousTreeNode = (DiagramTreeNode)parent.getLastChild();
f@0: 						loop = SoundEvent.LIST_TOP_REACHED;
f@0: 					}
f@0: 					setSelectionPath(new TreePath(previousTreeNode.getPath()));
f@0: 					final InputStream finalSound  = getTreeNodeSound(previousTreeNode);
f@0: 					final String currentPathSpeech = currentPathSpeech();
f@0: 					SoundFactory.getInstance().play(loop, new PlayerListener(){
f@0: 						public void playEnded() {
f@0: 							SoundFactory.getInstance().play(finalSound);
f@0: 							NarratorFactory.getInstance().speak(currentPathSpeech);
f@0: 						}
f@0: 					});
f@0: 					InteractionLog.log(INTERACTIONLOG_SOURCE,"move up",previousTreeNode.toString());
f@0: 				}});
f@0: 		   
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_RIGHT,0),"right");
f@0: 		   getActionMap().put("right", new AbstractAction(){
f@0: 			   @Override
f@0: 			   public void actionPerformed(ActionEvent evt) {
f@0: 				   TreePath path = getSelectionPath();
f@0: 				   DiagramTreeNode treeNode = (DiagramTreeNode)path.getLastPathComponent();
f@0: 				   if(treeNode.isLeaf()){
f@0: 					   notifyBorderReached(treeNode);
f@0: 					   InteractionLog.log(INTERACTIONLOG_SOURCE,"move right","border reached");
f@0: 				   }
f@0: 				   else{
f@0: 					   expandPath(path);
f@0: 					   setSelectionPath(new TreePath(((DiagramTreeNode)treeNode.getFirstChild()).getPath()));
f@0: 					   final String currentPathSpeech = currentPathSpeech();
f@0: 					   SoundFactory.getInstance().play(SoundEvent.TREE_NODE_EXPAND,new PlayerListener(){
f@0: 						@Override
f@0: 						public void playEnded() {
f@0: 							NarratorFactory.getInstance().speak(currentPathSpeech);
f@0: 						}
f@0: 					   });
f@0: 					   InteractionLog.log(INTERACTIONLOG_SOURCE,"move right",((DiagramTreeNode)treeNode.getFirstChild()).toString());
f@0: 				   }
f@0: 			   }
f@0: 		   });
f@0: 		   
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_LEFT,0),"left");
f@0: 		   getActionMap().put("left", new AbstractAction(){
f@0: 			   @Override
f@0: 			   public void actionPerformed(ActionEvent evt) {
f@0: 				   TreePath path = getSelectionPath();
f@0: 				   DiagramTreeNode treeNode = (DiagramTreeNode)path.getLastPathComponent();
f@0: 				   DiagramTreeNode parent = treeNode.getParent();
f@0: 				   if(parent == null){/* root node */
f@0: 					   notifyBorderReached(treeNode);
f@0: 					   InteractionLog.log(INTERACTIONLOG_SOURCE,"move left","border reached");
f@0: 				   }
f@0: 				   else{
f@0: 					   TreePath newPath = new TreePath(((DiagramTreeNode)parent).getPath());
f@0: 					   setSelectionPath(newPath);
f@0: 					   collapsePath(newPath);
f@0: 					   final String currentPathSpeech = currentPathSpeech(); 
f@0: 					   SoundFactory.getInstance().play(SoundEvent.TREE_NODE_COLLAPSE,new PlayerListener(){
f@0: 							@Override
f@0: 							public void playEnded() {
f@0: 								NarratorFactory.getInstance().speak(currentPathSpeech);
f@0: 							}
f@0: 					   });
f@0: 					   InteractionLog.log(INTERACTIONLOG_SOURCE,"move left",((DiagramTreeNode)parent).toString());
f@0: 				   }
f@0: 			   }
f@0: 		   });
f@0: 		   
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_SPACE,0),"space");
f@0: 		   getActionMap().put("space",new AbstractAction(){
f@0: 			   @Override
f@0: 			   public void actionPerformed(ActionEvent arg0) {
f@0: 				   NarratorFactory.getInstance().speak(currentPathSpeech());
f@0: 				   InteractionLog.log(INTERACTIONLOG_SOURCE,"info requested","");
f@0: 			   }
f@0: 		   });
f@0: 		   
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_SPACE,InputEvent.CTRL_DOWN_MASK),"ctrlspace");
f@0: 		   getActionMap().put("ctrlspace",new AbstractAction(){
f@0: 			   @Override
f@0: 			   public void actionPerformed(ActionEvent arg0) {
f@0: 				  /*//this code snippet reads out the whole path from the root to the selected node
f@0: 				   * StringBuilder builder = new StringBuilder();
f@0: 				   * TreePath path =	getSelectionPath();
f@0: 				   * for(Object o : path.getPath()){
f@0: 				   * 		builder.append(((DiagramModelTreeNode)o).spokenText());
f@0: 				   *		builder.append(", ");
f@0: 				   * 	}
f@0: 				   *  Narrator.getInstance().speak(builder.toString(), null);
f@0: 				   */  
f@0: 				   TreePath path = getSelectionPath();
f@0: 				   DiagramTreeNode treeNode = (DiagramTreeNode)path.getLastPathComponent();
f@0: 				   NarratorFactory.getInstance().speak(treeNode.detailedSpokenText());
f@0: 				   InteractionLog.log(INTERACTIONLOG_SOURCE,"detailed info requested","");
f@0: 			   }
f@0: 		   });
f@0: 		   
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_SHIFT,InputEvent.SHIFT_DOWN_MASK),"shift");
f@0: 		   getActionMap().put("shift",new AbstractAction(){
f@0: 			   @Override
f@0: 			   public void actionPerformed(ActionEvent evt) {
f@0: 				   if(getSelectionPath().getLastPathComponent() instanceof Node){
f@0: 					   Node node = (Node)getSelectionPath().getLastPathComponent();
f@0: 					   if(selectedNodes.contains(node)){
f@0: 						   unselectNode(node);
f@0: 						   diagram.getModelUpdater().yieldLock(node, Lock.MUST_EXIST,new DiagramEventActionSource(DiagramEventSource.TREE,Command.Name.UNSELECT_NODE_FOR_EDGE_CREATION,node.getId(),node.getName()));
f@0: 					   }else{
f@0: 						   if(!diagram.getModelUpdater().getLock(node, Lock.MUST_EXIST,new DiagramEventActionSource(DiagramEventSource.TREE,Command.Name.SELECT_NODE_FOR_EDGE_CREATION,node.getId(),node.getName()))){
f@0: 							   InteractionLog.log(INTERACTIONLOG_SOURCE,"Could not get lock on node fro edge creation selection",DiagramElement.toLogString(node));
f@0: 							   SpeechOptionPane.showMessageDialog(
f@0: 									   SpeechOptionPane.getFrameForComponent(DiagramTree.this), 
f@0: 									   resources.getString("dialog.lock_failure.must_exist"), 
f@0: 									   SpeechOptionPane.INFORMATION_MESSAGE);
f@0: 							   SoundFactory.getInstance().play(SoundEvent.MESSAGE_OK, new PlayerListener(){
f@0: 								   @Override
f@0: 								   public void playEnded() {
f@0: 									   NarratorFactory.getInstance().speak(currentPathSpeech());
f@0: 								   }
f@0: 							   });
f@0: 							   return;
f@0: 						   }
f@0: 						   selectNode(node);
f@0: 					   }
f@0: 				   }
f@0: 			   }
f@0: 		   });
f@0: 		   
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_CONTROL,InputEvent.CTRL_DOWN_MASK),"ctrldown");
f@0: 		   getActionMap().put("ctrldown",SpeechUtilities.getShutUpAction());
f@0: 		   
f@0: 		   /* make the tree ignore the page up and page down keys */
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_PAGE_UP,0),"none");
f@0: 		   getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_PAGE_DOWN,0),"none");
f@0: 	   }
f@0: 	
f@0: 	private static InputStream getTreeNodeSound(DiagramTreeNode node){
f@0: 		InputStream sound = null;
f@0: 		TreeNode[] newPath = node.getPath();
f@0: 		if(!node.isRoot()){
f@0: 			if(node.getChildCount() > 0){ // check whether it's the folder containing Node/Edge references
f@0: 				if(node.getChildAt(0) instanceof EdgeReferenceMutableTreeNode){
f@0: 					sound = ((EdgeReferenceMutableTreeNode)node.getChildAt(0)).getEdge().getSound();
f@0: 				}else{
f@0: 					sound = ((TypeMutableTreeNode)newPath[1]).getPrototype().getSound();
f@0: 				}
f@0: 			}else{
f@0: 				if(node instanceof NodeReferenceMutableTreeNode){
f@0: 					sound = ((NodeReferenceMutableTreeNode)node).getNode().getSound();
f@0: 				}else if(node instanceof EdgeReferenceMutableTreeNode){
f@0: 					sound = ((EdgeReferenceMutableTreeNode)node).getNode().getSound();
f@0: 				}else{
f@0: 					sound = ((TypeMutableTreeNode)newPath[1]).getPrototype().getSound();
f@0: 				}
f@0: 			}
f@0: 		}
f@0: 		return sound;
f@0: 	}
f@0: 	
f@0: 	@Override
f@0: 	public void setSelectionPath(TreePath path){
f@0: 		super.setSelectionPath(path);
f@0: 		scrollPathToVisible(path);
f@0: 	}
f@0: 	
f@0: 	private void notifyBorderReached(DiagramTreeNode n) {
f@0: 		SoundFactory.getInstance().play(SoundEvent.ERROR);
f@0: 	}
f@0: 	
f@0: 	@Override
f@0: 	public String convertValueToText(Object value,
f@0:             boolean selected,
f@0:             boolean expanded,
f@0:             boolean leaf,
f@0:             int row,
f@0:             boolean hasFocus){
f@0: 		StringBuilder builder = new StringBuilder(super.convertValueToText(value, selected, expanded, leaf, row, hasFocus));
f@0: 		if(selectedNodes != null)
f@0: 			if(selectedNodes.contains(value)){
f@0: 				builder.insert(0, SELECTED_NODE_MARK_BEGIN);
f@0: 				builder.append(SELECTED_NODE_MARK_END);
f@0: 			}
f@0: 		return builder.toString();
f@0: 	}
f@0: 	
f@0: 	@Override
f@0: 	protected TreeModelListener createTreeModelListener(){
f@0: 		return new DiagramTreeModelHandler();
f@0: 	}
f@0: 	
f@0: 
f@0: 	private List<Node> selectedNodes;
f@0: 	private Diagram diagram;
f@0: 	private ResourceBundle resources;
f@0: 	private static final char SELECTED_NODE_MARK_BEGIN = '<';
f@0: 	private static final char SELECTED_NODE_MARK_END = '>';
f@0: 	private static final String INTERACTIONLOG_SOURCE = "TREE";
f@0: 	/**
f@0: 	 * A list of possible destination for a jump (a change of the selected path without 
f@0: 	 * using the navigation arrow keys)   
f@0: 	 */
f@0: 	public static enum JumpTo {
f@0: 		/**
f@0: 		 * if the current selection is a edge/node reference tree node, the jump destination 
f@0: 		 * is the referee tree node (see {@link uk.ac.qmul.eecs.ccmi.diagrammodel.NodeReferenceMutableTreeNode} and 
f@0: 		 * {@link uk.ac.qmul.eecs.ccmi.diagrammodel.EdgeReferenceMutableTreeNode }) 
f@0: 		 */
f@0: 		REFERENCE,
f@0: 		/**
f@0: 		 * the destination is the root of the diagram
f@0: 		 */
f@0: 		ROOT,
f@0: 		/**
f@0: 		 * the destination will be a node or edge type selected 
f@0: 		 * (via a selection dialog) by the user
f@0: 		 */
f@0: 		SELECTED_TYPE, 
f@0: 		 /**	
f@0: 		  * the destination will be a bookmark selected (via a selection dialog) by the user 
f@0: 		  */
f@0: 		BOOKMARK}
f@0: 	
f@0: 	/* the methods of the TreeModelHandler are overwritten in order to provide a consistent way 
f@0: 	 * of updating the tree selection upon tree change. Bear in mind that the tree can possibly be changed
f@0: 	 * by another peer on a network, and therefore not only as a response to a user's action.  
f@0: 	 * The algorithm works as follows (being A the tree node selected before any handler method M being called):
f@0: 	 * 
f@0: 	 * if A ain't deleted as a result of M : do nothing
f@0: 	 * if A's deleted as a result of M's execution : say A was the n-th sibling select the new n-th sibling 
f@0: 	 *   or, if now the sibling nodes are less than n, select the one with highest index 
f@0: 	 * if no sibling nodes are still connected to the tree select the parent or the closest ancestor connected to the tree   
f@0: 	 */
f@0: 	private class DiagramTreeModelHandler extends JTree.TreeModelHandler{
f@0: 
f@0: 		@Override
f@0: 		public void treeStructureChanged(final TreeModelEvent e) {
f@0: 			/* check first if what we're removing is in the selection path */
f@0: 			TreePath path = e.getTreePath();
f@0: 			boolean isInSelectionPath = false;
f@0: 			for(Object t : getSelectionPath().getPath()){
f@0: 				if(path.getLastPathComponent() == t){
f@0: 					isInSelectionPath = true;
f@0: 					break;
f@0: 				}
f@0: 			}
f@0: 
f@0: 			if(isInSelectionPath){
f@0: 				Object[] pathArray = getSelectionPath().getPath();
f@0: 				DefaultMutableTreeNode root = (DefaultMutableTreeNode)getModel().getRoot();
f@0: 				/* go along the path from the selected node to the root looking for a node *
f@0: 				 * attached to the tree or with sibling nodes attached to the tree         */
f@0: 				for(int i=pathArray.length-1;i>=0;i--){
f@0: 					DiagramTreeNode onPathTreeNode = (DiagramTreeNode)pathArray[i];
f@0: 					if(onPathTreeNode.isNodeRelated(root)){// if can reach the root from here a.k.a. the node is still part of the tree 
f@0: 						super.treeStructureChanged(e);
f@0: 						setSelectionPath(new TreePath(onPathTreeNode.getPath()));
f@0: 						break;
f@0: 					}else{
f@0: 						/* check sibling nodes*/
f@0: 						DefaultMutableTreeNode parent = (DiagramTreeNode)pathArray[i-1];
f@0: 						if(parent.isNodeRelated(root) && parent.getChildCount() > 0){
f@0: 							super.treeStructureChanged(e);
f@0: 							setSelectionPath(new TreePath(((DefaultMutableTreeNode)parent.getLastChild()).getPath()));
f@0: 							break;
f@0: 						}
f@0: 					}
f@0: 				}
f@0: 			}else
f@0: 				super.treeStructureChanged(e);
f@0: 			repaint();
f@0: 		}
f@0: 
f@0: 		@Override
f@0: 		public void treeNodesChanged(final TreeModelEvent e){
f@0: 			TreePath path = getSelectionPath();
f@0: 			super.treeNodesChanged(e);
f@0: 			setSelectionPath(path);
f@0: 		}
f@0: 
f@0: 		@Override
f@0: 		public void treeNodesRemoved(final TreeModelEvent e){
f@0: 			/* check first if what we're removing is in the selecton path */
f@0: 			TreePath path = e.getTreePath();
f@0: 			DiagramTreeNode removedTreeNode = (DiagramTreeNode)e.getChildren()[0];
f@0: 			boolean isInSelectionPath = false;
f@0: 			for(Object t : getSelectionPath().getPath()){
f@0: 				if(removedTreeNode == t){
f@0: 					isInSelectionPath = true;
f@0: 					break;
f@0: 				}
f@0: 			}
f@0: 			DiagramTreeNode parentTreeNode = (DiagramTreeNode)path.getLastPathComponent(); 
f@0: 			/* update the selection only if the tree node involved is in the selection path *
f@0: 			 * this always holds true for tree nodes deleted from the tree                  */
f@0: 			if(isInSelectionPath){
f@0: 				if(e.getSource() instanceof TreeModel){
f@0: 					/* update the path only if the node has been removed from the tree or         *
f@0: 					 * if the currently selected tree node is going to be removed by this action  *
f@0: 					 * Need to call collapsePath only if the source of the deletion is the tree   *
f@0: 					 * as otherwise the selected node is always a leaf  						  */
f@0: 					collapsePath(path);
f@0: 					setSelectionPath(path);
f@0: 				}else{ 
f@0: 					/* if we deleted from another source, then select the first non null node in the path *
f@0: 					 * including the deleted node. E.g. if we're deleting the first child of a parent     *
f@0: 					 * and the node has siblings than the new first sibling will be selected              */
f@0: 					int limitForParentDeletion = (parentTreeNode instanceof Edge) ? 1 : 0; // an edge with one node is to be deleted
f@0: 					if(parentTreeNode.getChildCount() > limitForParentDeletion){
f@0: 						setSelectionPath(new TreePath(((DiagramTreeNode)parentTreeNode.getChildAt(
f@0: 								/* select the n-th sibling node (see algorithm description above or the highest index sibling node */
f@0: 								Math.min(e.getChildIndices()[0],parentTreeNode.getChildCount()-1)
f@0: 						)).getPath()));
f@0: 					}else{
f@0: 						/* the deleted node had no siblings, thus select the node checking from the parent up in the path to the first still existing node */
f@0: 						Object[] pathArray = path.getPath();
f@0: 						for(int i=path.getPathCount()-1;i>=0;i--){
f@0: 							DiagramTreeNode itr = (DiagramTreeNode)pathArray[i];
f@0: 							if(itr.getPath()[0] == getModel().getRoot()){
f@0: 								TreePath newPath = new TreePath(itr.getPath()); 
f@0: 								setSelectionPath(newPath);
f@0: 								collapsePath(newPath);
f@0: 								break;
f@0: 							}
f@0: 						}
f@0: 					}
f@0: 				}
f@0: 			}else
f@0: 				super.treeNodesRemoved(e);
f@0: 
f@0: 			/* if the node was selected for edge creation, then remove it from the list */
f@0: 			DiagramTreeNode removedNode = (DiagramTreeNode)e.getChildren()[0];
f@0: 			selectedNodes.remove(removedNode);
f@0: 		}		
f@0: 	}
f@0: }