JAL-1953 some more comments, moved JalviewBinding

[jalview.git] / src / jalview / ext / treeviewer / TreeViewerBindingI.java

diff --git a/src/jalview/ext/treeviewer/TreeViewerBindingI.java b/src/jalview/ext/treeviewer/TreeViewerBindingI.java
index da999c6..afbceab 100644 (file)
--- a/src/jalview/ext/treeviewer/TreeViewerBindingI.java
+++ b/src/jalview/ext/treeviewer/TreeViewerBindingI.java
@@ -28,11 +28,13 @@ import jalview.structure.SelectionSource;
 
 import java.awt.event.ActionListener;
 import java.awt.event.MouseListener;
+import java.util.Map;
 
 /**
  * 
- * Interface for binding a tree viewer to Jalview alignments. Assumes a tree
- * viewer will both want to receive and send selection events.
+ * Interface for associating the nodes of a tree viewer with Jalview alignment
+ * sequences and communicating between the two. Assumes a tree viewer will both
+ * want to receive and send selection events.
  * 
  * @author kjvanderheide
  *
@@ -43,20 +45,76 @@ public interface TreeViewerBindingI
         SelectionSource
 {
   /**
+   * Gets the mapping for sequences with their associated tree nodes
+   * 
+   * @return
+   */
+  public Map<SequenceI, TreeNodeI> getAlignmentWithNodes();
+
+  /**
+   * Gets the mapping for tree nodes with their associated sequences
+   * 
+   * @return
+   */
+  public Map<TreeNodeI, SequenceI> getNodesWithAlignment();
+
+  /**
+   * Triggers a tree partition from the specified x coordinate.
+   * 
+   * @param x
+   * 
+   */
+  public void partitionTree(final int x);
+
+  /**
+   * Looks up the given TreeNodeI in the tree and highlights Jalview sequences
+   * that belong to it or its descendants.
+   * 
+   * @param parentNode
+   *          node from where the descendants should get matched, this node
+   *          should be internal.
+   */
+  public void showMatchingChildSequences(TreeNodeI parentNode);
+
+  /**
+   * Highlights the Jalview sequence belonging to the given TreeNodeI (if
+   * possible).
+   * 
+   * @param nodeToMatch
+   */
+  public void showMatchingSequence(TreeNodeI nodeToMatch);
+
+  /**
    * If a node is selected in the tree panel this method highlights the
    * corresponding sequence in the Jalview alignment view. If an internal node
    * is selected all child sequences get highlighted as well.
    */
   public void showNodeSelectionOnAlign(TreeNodeI node);
 
-  public void treeSelectionChanged(SequenceI sequence);
-
-  public void showMatchingSequence(TreeNodeI nodeToMatch);
-
-  public void showMatchingChildSequences(TreeNodeI parentNode);
+  /**
+   * Sorts the given alignment by the order in which the sequences appear in the
+   * tree.
+   * 
+   * @param alignPanel
+   *          panel containing the alignment to be sorted.
+   * @return the sorting Command
+   */
+  public CommandI sortAlignmentIn(AlignmentPanel alignPanel);
 
+  /**
+   * This should be triggered when the user wants to sort the Jalview alignment
+   * by the sequence order of the tree.
+   */
   public void sortByTree_actionPerformed();
 
-  public CommandI sortAlignmentIn(AlignmentPanel alignPanel);
+  /**
+   * If the nodes that should be matched have changed (different one selected by
+   * the user), this method notifies the Jalview alignment view that the
+   * matching sequences have changed as well.
+   * 
+   * @param sequence
+   *          the new SequenceI that should be matched.
+   */
+  public void treeSelectionChanged(SequenceI sequence);
 
 }