JAL-1953 some more comments, moved JalviewBinding

diff --git a/src/jalview/ext/archaeopteryx/AptxInit.java b/src/jalview/ext/archaeopteryx/AptxInit.java
index cbdd237..6bc8497 100644 (file)
--- a/src/jalview/ext/archaeopteryx/AptxInit.java
+++ b/src/jalview/ext/archaeopteryx/AptxInit.java
@@ -506,7 +506,7 @@ public final class AptxInit
     TreeViewerUtils.associateNodesWithJalviewSequences(aptxApp, jalviewAlignport,
             bindAptxNodes.getAlignmentWithNodes(),
             bindAptxNodes.getNodesWithAlignment());
-    TreeViewerUtils.addTreeViewFrameToJalview(aptxApp);
+    TreeViewerUtils.addTreeViewFrameToJalview(aptxApp, 400, 500);
 
     // adaptAptxGui(aptxApp); //moved to AptxFrame
     return aptxApp;
@@ -529,7 +529,7 @@ public final class AptxInit
     TreeViewerUtils.associateNodesWithJalviewSequences(aptxApp, jalviewAlignport,
             bindAptxNodes.getAlignmentWithNodes(),
             bindAptxNodes.getNodesWithAlignment());
-    TreeViewerUtils.addTreeViewFrameToJalview(aptxApp);
+    TreeViewerUtils.addTreeViewFrameToJalview(aptxApp, 400, 500);
 
     return aptxApp;
   }

diff --git a/src/jalview/ext/archaeopteryx/JalviewBinding.java b/src/jalview/ext/treeviewer/JalviewBinding.java
similarity index 95%
rename from src/jalview/ext/archaeopteryx/JalviewBinding.java
rename to src/jalview/ext/treeviewer/JalviewBinding.java
index b38ac1c..630d586 100644 (file)
--- a/src/jalview/ext/archaeopteryx/JalviewBinding.java
+++ b/src/jalview/ext/treeviewer/JalviewBinding.java
@@ -1,4 +1,4 @@
-package jalview.ext.archaeopteryx;
+package jalview.ext.treeviewer;
 
 import jalview.analysis.AlignmentSorter;
 import jalview.analysis.Conservation;
@@ -10,13 +10,6 @@ import jalview.datamodel.ColumnSelection;
 import jalview.datamodel.HiddenColumns;
 import jalview.datamodel.SequenceGroup;
 import jalview.datamodel.SequenceI;
-import jalview.ext.treeviewer.LoadedTreeSequenceAssociation;
-import jalview.ext.treeviewer.TreeFrameI;
-import jalview.ext.treeviewer.TreeI;
-import jalview.ext.treeviewer.TreeNodeI;
-import jalview.ext.treeviewer.TreePanelI;
-import jalview.ext.treeviewer.TreeViewerBindingI;
-import jalview.ext.treeviewer.TreeViewerUtils;
 import jalview.gui.AlignViewport;
 import jalview.gui.AlignmentPanel;
 import jalview.gui.Desktop;
@@ -37,19 +30,19 @@ import java.awt.event.ActionEvent;
 import java.awt.event.InputEvent;
 import java.awt.event.MouseEvent;
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
-import java.util.Set;
 
 import javax.swing.SwingUtilities;
 import javax.swing.event.InternalFrameAdapter;
 import javax.swing.event.InternalFrameEvent;
 
 /**
- * Class for binding the Archaeopteryx tree viewer to the Jalview alignment that
- * it originates from, meaning that selecting sequences in the tree viewer also
- * selects them in the alignment view and vice versa.
+ * Class for binding the tree viewer to the Jalview alignment that it originates
+ * from, meaning that selecting sequences in the tree viewer also selects them
+ * in the alignment view and vice versa.
  * 
  * @author kjvanderheide
  *
@@ -555,7 +548,7 @@ public final class JalviewBinding
     if (matchingSequence != null)
     {
       long nodeId = nodeToMatch.getId();
-      addOrRemoveInSet(treeView.getMatchingNodesIds(), nodeId);
+      addOrRemoveInCollection(treeView.getMatchingNodesIds(), nodeId);
       treeSelectionChanged(matchingSequence);
       parentAvport.sendSelection();
 
@@ -576,7 +569,7 @@ public final class JalviewBinding
       if (matchingSequence != null)
       {
         long nodeId = childNode.getId();
-        addOrRemoveInSet(treeView.getMatchingNodesIds(), nodeId);
+        addOrRemoveInCollection(treeView.getMatchingNodesIds(), nodeId);
 
         treeSelectionChanged(matchingSequence);
 
@@ -694,18 +687,19 @@ public final class JalviewBinding
   /**
    * TO BE MOVED
    * 
-   * @param set
-   * @param objectToCheck
+   * @param collection
+   * @param nodeId
    */
-  public static <E> void addOrRemoveInSet(Set<E> set, E objectToCheck)
+  public static <E> void addOrRemoveInCollection(Collection<Long> collection,
+          long nodeId)
   {
-    if (set.contains(objectToCheck))
+    if (collection.contains(nodeId))
     {
-      set.remove(objectToCheck);
+      collection.remove(nodeId);
     }
     else
     {
-      set.add(objectToCheck);
+      collection.add(nodeId);
     }
 
   }

diff --git a/src/jalview/ext/treeviewer/TreePanelI.java b/src/jalview/ext/treeviewer/TreePanelI.java
index bfd3211..6871105 100644 (file)
--- a/src/jalview/ext/treeviewer/TreePanelI.java
+++ b/src/jalview/ext/treeviewer/TreePanelI.java
@@ -37,6 +37,13 @@ public interface TreePanelI extends Accessible, MenuContainer
 
   public int getHeight();
 
+  /**
+   * Method for adding a tree node to the Set of nodes that are associated with
+   * some operation outside of the tree, such as nodes belonging to currently
+   * selected Jalview alignment sequences.
+   * 
+   * @param matchedNode
+   */
   public void addToMatchingNodes(TreeNodeI matchedNode);
 
   public abstract Set<Long> getMatchingNodesIds();
@@ -53,6 +60,11 @@ public interface TreePanelI extends Accessible, MenuContainer
 
   public abstract TreeI getTree();
 
+  /**
+   * Gets the File from where the Tree originates.
+   * 
+   * @return
+   */
   public abstract File getTreeFile();
 
   public abstract Rectangle getVisibleArea();
@@ -108,15 +120,13 @@ public interface TreePanelI extends Accessible, MenuContainer
 
   public void setPreferredSize(Dimension preferredSize);
 
-  /**
-   * 
-   * @param file
-   */
   public abstract void setTreeFile(File file);
 
   /**
+   * Checks if the tree has been cut to display just a sub tree.
    * 
-   * @return
+   * @return True if the panel is currently showing only a subtree, otherwise
+   *         false.
    */
   public boolean showingSubTree();
 

diff --git a/src/jalview/ext/treeviewer/TreeParserI.java b/src/jalview/ext/treeviewer/TreeParserI.java
index 1f53ff5..97db111 100644 (file)
--- a/src/jalview/ext/treeviewer/TreeParserI.java
+++ b/src/jalview/ext/treeviewer/TreeParserI.java
@@ -3,6 +3,7 @@ package jalview.ext.treeviewer;
 import java.io.IOException;
 
 /**
+ * Interface for reading in trees from a given source.
  * 
  * @author kjvanderheide
  *
@@ -13,6 +14,11 @@ public interface TreeParserI
 
   public TreeI[] getParsedTrees();
 
+  /**
+   * 
+   * @return Trees that were successfully parsed.
+   * @throws IOException
+   */
   public TreeI[] parse() throws IOException;
 
   public void setSource(Object source) throws IOException;

diff --git a/src/jalview/ext/treeviewer/TreeViewerBindingI.java b/src/jalview/ext/treeviewer/TreeViewerBindingI.java
index 8642703..afbceab 100644 (file)
--- a/src/jalview/ext/treeviewer/TreeViewerBindingI.java
+++ b/src/jalview/ext/treeviewer/TreeViewerBindingI.java
@@ -66,8 +66,22 @@ public interface TreeViewerBindingI
    */
   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);
 
   /**
@@ -82,13 +96,25 @@ public interface TreeViewerBindingI
    * tree.
    * 
    * @param alignPanel
-   *          Panel containing the alignment to be sorted.
+   *          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();
 
+  /**
+   * 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);
 
 }

diff --git a/src/jalview/ext/treeviewer/TreeViewerUtils.java b/src/jalview/ext/treeviewer/TreeViewerUtils.java
index d065662..7e1a4e9 100644 (file)
--- a/src/jalview/ext/treeviewer/TreeViewerUtils.java
+++ b/src/jalview/ext/treeviewer/TreeViewerUtils.java
@@ -1,7 +1,6 @@
 package jalview.ext.treeviewer;
 
 import jalview.datamodel.SequenceI;
-import jalview.ext.archaeopteryx.JalviewBinding;
 import jalview.util.MessageManager;
 import jalview.viewmodel.AlignmentViewport;
 
@@ -11,7 +10,10 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
- * Static class containing generic methods for
+ * Static class containing generic methods for communicating between the tree
+ * viewer frame and Jalview, currently includes adding the frame to the Jalview
+ * Desktop and triggering an association between an {@link AlignmentViewport}
+ * and {@link TreeFrameI}.
  * 
  * @author kjvanderheide
  *
@@ -25,15 +27,14 @@ public final class TreeViewerUtils
   private static Map<TreeFrameI, TreeViewerBindingI> activeViews = new HashMap<>();
 
   /**
+   * Adds the given tree frame to the Jalview {@link Desktop}.
    * 
    * @param treeFrame
-   * @return
+   * @return the same tree frame but now as part of Jalview.
    */
   public static TreeFrameI addTreeViewFrameToJalview(
-          final TreeFrameI treeFrame)
+          final TreeFrameI treeFrame, int width, int height)
   {
-    int width = 400;
-    int height = 550;
     treeFrame.setMinimumSize(new Dimension(width, height));
     // aptxApp.setFont(Desktop.instance.getFont());
     // aptxApp.getMainPanel().setFont(Desktop.instance.getFont());
@@ -57,6 +58,8 @@ public final class TreeViewerUtils
   }
 
   /**
+   * Convience method for building the association between Jalview's alignment
+   * and the tree frame.
    * 
    * @param treeFrame
    * @param jalviewAlignViewport