From 46d18401c788a01ef8ad5340547d0209cbf2186d Mon Sep 17 00:00:00 2001 From: kjvdheide Date: Sun, 28 Jan 2018 15:55:54 +0000 Subject: [PATCH] JAL-1953 more javadoc comments --- src/jalview/ext/archaeopteryx/AptxTreePanel.java | 9 ++- src/jalview/ext/archaeopteryx/JalviewBinding.java | 7 ++- src/jalview/ext/archaeopteryx/Tree.java | 5 +- .../ext/treeviewer/LoadedTreeAssociationI.java | 7 +-- src/jalview/ext/treeviewer/TreeFrameI.java | 4 ++ src/jalview/ext/treeviewer/TreeI.java | 19 +++++- src/jalview/ext/treeviewer/TreeNodeI.java | 22 +++++++ src/jalview/ext/treeviewer/TreePanelI.java | 66 +++++++++++++++++++- src/jalview/ext/treeviewer/TreeParserI.java | 5 ++ src/jalview/ext/treeviewer/TreeViewerBindingI.java | 3 +- src/jalview/ext/treeviewer/TreeViewerConfigI.java | 6 -- src/jalview/ext/treeviewer/TreeViewerUtils.java | 23 +++++++ 12 files changed, 151 insertions(+), 25 deletions(-) delete mode 100644 src/jalview/ext/treeviewer/TreeViewerConfigI.java diff --git a/src/jalview/ext/archaeopteryx/AptxTreePanel.java b/src/jalview/ext/archaeopteryx/AptxTreePanel.java index 77b2ddd..05c5cab 100644 --- a/src/jalview/ext/archaeopteryx/AptxTreePanel.java +++ b/src/jalview/ext/archaeopteryx/AptxTreePanel.java @@ -73,7 +73,7 @@ public class AptxTreePanel implements TreePanelI } @Override - public Set getMatchingNodes() + public Set getMatchingNodesIds() { return treeView.getFoundNodes0(); } @@ -220,4 +220,11 @@ public class AptxTreePanel implements TreePanelI treeView.setPreferredSize(preferredSize); } + + @Override + public void addToMatchingNodes(TreeNodeI matchedNode) + { + treeView.getFoundNodes0().add(matchedNode.getId()); + + } } diff --git a/src/jalview/ext/archaeopteryx/JalviewBinding.java b/src/jalview/ext/archaeopteryx/JalviewBinding.java index f0c2866..b38ac1c 100644 --- a/src/jalview/ext/archaeopteryx/JalviewBinding.java +++ b/src/jalview/ext/archaeopteryx/JalviewBinding.java @@ -298,7 +298,7 @@ public final class JalviewBinding .get(selectedSequence); if (matchingNode != null) { - treeView.getMatchingNodes().add(matchingNode.getId()); + treeView.addToMatchingNodes(matchingNode); // if (!matchingNode.getBranchData().isHasBranchColor()) @@ -323,6 +323,7 @@ public final class JalviewBinding /** * Partially refactored from TreeCanvas */ + @Override public void partitionTree(final int x) { TreeI tree = treeView.getTree(); @@ -554,7 +555,7 @@ public final class JalviewBinding if (matchingSequence != null) { long nodeId = nodeToMatch.getId(); - addOrRemoveInSet(treeView.getMatchingNodes(), nodeId); + addOrRemoveInSet(treeView.getMatchingNodesIds(), nodeId); treeSelectionChanged(matchingSequence); parentAvport.sendSelection(); @@ -575,7 +576,7 @@ public final class JalviewBinding if (matchingSequence != null) { long nodeId = childNode.getId(); - addOrRemoveInSet(treeView.getMatchingNodes(), nodeId); + addOrRemoveInSet(treeView.getMatchingNodesIds(), nodeId); treeSelectionChanged(matchingSequence); diff --git a/src/jalview/ext/archaeopteryx/Tree.java b/src/jalview/ext/archaeopteryx/Tree.java index 20c428d..616ea4b 100644 --- a/src/jalview/ext/archaeopteryx/Tree.java +++ b/src/jalview/ext/archaeopteryx/Tree.java @@ -21,9 +21,6 @@ public class Tree implements TreeI { private final Phylogeny tree; - // alternative to static maps in TreeNode - // private Map originalNodes = new HashMap<>(500); - // private Map wrappedNodes = new HashMap<>(500); public Tree() { @@ -112,7 +109,7 @@ public class Tree implements TreeI } @Override - public double getHeight(boolean adjustForCollapsedSubtrees) + public double getMaximumLength(boolean adjustForCollapsedSubtrees) { return tree.calculateHeight(adjustForCollapsedSubtrees); } diff --git a/src/jalview/ext/treeviewer/LoadedTreeAssociationI.java b/src/jalview/ext/treeviewer/LoadedTreeAssociationI.java index 6252a57..34367e9 100644 --- a/src/jalview/ext/treeviewer/LoadedTreeAssociationI.java +++ b/src/jalview/ext/treeviewer/LoadedTreeAssociationI.java @@ -23,16 +23,15 @@ public interface LoadedTreeAssociationI public void associateNodesToSequences(); /** - * See - * {@link jalview.ext.treeviewer.TreeViewerBindingI#getAlignmentWithNodes()} + * @see jalview.ext.treeviewer.TreeViewerBindingI#getAlignmentWithNodes() * * */ public Map getAlignmentWithNodes(); /** - * See - * {@link jalview.ext.treeviewer.TreeViewerBindingI#getNodesWithAlignment()} + * @see jalview.ext.treeviewer.TreeViewerBindingI#getNodesWithAlignment() + * * * */ diff --git a/src/jalview/ext/treeviewer/TreeFrameI.java b/src/jalview/ext/treeviewer/TreeFrameI.java index beadceb..51c897e 100644 --- a/src/jalview/ext/treeviewer/TreeFrameI.java +++ b/src/jalview/ext/treeviewer/TreeFrameI.java @@ -15,6 +15,10 @@ import javax.swing.event.InternalFrameListener; * viewer. Note that this extends many interfaces shared with Swing frames but * doesn't demand that an implementation actually is a Swing frame. * + * Frames should be added to Jalview's desktop via + * {@link TreeViewerUtils#addTreeViewFrameToJalview(TreeFrameI)} to ensure that + * they are registered as an active tree view. + * * @author kjvanderheide * */ diff --git a/src/jalview/ext/treeviewer/TreeI.java b/src/jalview/ext/treeviewer/TreeI.java index fbda8f1..08c3d04 100644 --- a/src/jalview/ext/treeviewer/TreeI.java +++ b/src/jalview/ext/treeviewer/TreeI.java @@ -8,8 +8,7 @@ import java.util.Iterator; import java.util.List; /** - * Interface for a generic phylogenetic tree, this does not necessarily have to - * be part of a tree panel. + * Interface for implementing a phylogenetic tree. * * @author kjvanderheide * @@ -29,9 +28,23 @@ public interface TreeI public TreeNodeI[] getAllNodes(); + /** + * Gets the node that has the maximum branch length from the root (or top + * level node if tree is unrooted). + * + * @return + */ public TreeNodeI getFurthestNode(); - public double getHeight(boolean adjustForCollapsedSubtrees); + /** + * Returns the longest total branch length from the root to a leaf node. + * + * @param adjustForCollapsedSubtrees + * true if nodes part of a collapsed (hidden) subtree should be + * considered. + * @return + */ + public double getMaximumLength(boolean adjustForCollapsedSubtrees); public List getNodeSequences(); diff --git a/src/jalview/ext/treeviewer/TreeNodeI.java b/src/jalview/ext/treeviewer/TreeNodeI.java index 0ea76f7..d14f97f 100644 --- a/src/jalview/ext/treeviewer/TreeNodeI.java +++ b/src/jalview/ext/treeviewer/TreeNodeI.java @@ -5,6 +5,13 @@ import jalview.datamodel.SequenceI; import java.awt.Color; import java.util.List; +/** + * Interface for implementing a tree node, these nodes might -but do not have + * to- be part of a {@link TreeI}. + * + * @author kjvanderheide + * + */ public interface TreeNodeI { @@ -12,8 +19,19 @@ public interface TreeNodeI public List getAllDescendants(); + /** + * Returns only the immediate descendants of this node, so any nodes whose + * parent is this node. + * + * @return + */ public List getDirectChildren(); + /** + * Gets just the nodes downwards from this node that are external/leafs. + * + * @return + */ public List getExternalDescendants(); public long getId(); @@ -26,6 +44,10 @@ public interface TreeNodeI public float getYcoord(); + /** + * + * @return True if the node is internal, false if it's external (a leaf). + */ public boolean isInternal(); public void setBranchColor(Color branchColor); diff --git a/src/jalview/ext/treeviewer/TreePanelI.java b/src/jalview/ext/treeviewer/TreePanelI.java index e3d5800..bfd3211 100644 --- a/src/jalview/ext/treeviewer/TreePanelI.java +++ b/src/jalview/ext/treeviewer/TreePanelI.java @@ -10,20 +10,45 @@ import java.util.Set; import javax.accessibility.Accessible; +/** + * Interface for a panel that supports viewing a phylogenetic tree, should + * probably be part of a {@link TreeFrameI}. Does not necessarily have to be a + * Swing JPanel. + * + * Implementations must always contain a {@link TreeI}. + * + * @author kjvanderheide + * + */ public interface TreePanelI extends Accessible, MenuContainer { - - public void addMouseListener(MouseListener listener); + /** + * Look for a tree node at the specified coordinates inside the panel. + * + * @param x + * X coordinate on the panel to look at. + * @param y + * Y coordinate on the panel to look at. + * @return The tree node if one was found, otherwise null. + */ public abstract TreeNodeI findNode(int x, int y); public int getHeight(); - public abstract Set getMatchingNodes(); + public void addToMatchingNodes(TreeNodeI matchedNode); + + public abstract Set getMatchingNodesIds(); public MouseListener[] getMouseListeners(); + /** + * Gets the current partitioning threshold which is the ratio of the + * partitioning x coordinate to the total panel width. + * + * @return The partition threshold. + */ public float getPartitionThreshold(); public abstract TreeI getTree(); @@ -34,14 +59,41 @@ public interface TreePanelI extends Accessible, MenuContainer public int getWidth(); + /** + * Method for triggering PaintRefresher refreshes with the actual tree panel + * using the sequence set id the panel was registered with. + * + * @see jalview.gui.PaintRefresher#Refresh(java.awt.Component, String, + * boolean, boolean) + * @param alignmentChanged + * @param validateSequences + */ public void notifyPaintRefresher(boolean alignmentChanged, boolean validateSequences); + /** + * Method for triggering PaintRefresher refreshes with the actual tree panel + * using a new sequence set id. + * + * @see jalview.gui.PaintRefresher#Refresh(java.awt.Component, String, + * boolean, boolean) + * @param newSeqSetIdentifier + * @param alignmentChanged + * @param validateSequences + */ public void notifyPaintRefresher(String newSeqSetIdentifier, boolean alignmentChanged, boolean validateSequences); public abstract void paintToFile(Graphics2D pg, int width, int height); + /** + * Registers the actual tree viewing panel used with PaintRefresher, this + * method is necessary as panels cannot be registered at this interface level + * because there is no guarantee an implementation will be a Component. + * + * @see jalview.gui.PaintRefresher#Register(java.awt.Component, String) + * @param sequenceSetIdentifier + */ public void registerWithPaintRefresher(String sequenceSetIdentifier); public void removeMouseListener(MouseListener listener); @@ -56,8 +108,16 @@ public interface TreePanelI extends Accessible, MenuContainer public void setPreferredSize(Dimension preferredSize); + /** + * + * @param file + */ public abstract void setTreeFile(File file); + /** + * + * @return + */ public boolean showingSubTree(); } diff --git a/src/jalview/ext/treeviewer/TreeParserI.java b/src/jalview/ext/treeviewer/TreeParserI.java index b339615..1f53ff5 100644 --- a/src/jalview/ext/treeviewer/TreeParserI.java +++ b/src/jalview/ext/treeviewer/TreeParserI.java @@ -2,6 +2,11 @@ package jalview.ext.treeviewer; import java.io.IOException; +/** + * + * @author kjvanderheide + * + */ public interface TreeParserI { public String getName(); diff --git a/src/jalview/ext/treeviewer/TreeViewerBindingI.java b/src/jalview/ext/treeviewer/TreeViewerBindingI.java index bb6eb19..8642703 100644 --- a/src/jalview/ext/treeviewer/TreeViewerBindingI.java +++ b/src/jalview/ext/treeviewer/TreeViewerBindingI.java @@ -59,9 +59,10 @@ public interface TreeViewerBindingI public Map getNodesWithAlignment(); /** + * Triggers a tree partition from the specified x coordinate. * * @param x - * coordinate that functions as the clustering threshold + * */ public void partitionTree(final int x); diff --git a/src/jalview/ext/treeviewer/TreeViewerConfigI.java b/src/jalview/ext/treeviewer/TreeViewerConfigI.java deleted file mode 100644 index 29e4895..0000000 --- a/src/jalview/ext/treeviewer/TreeViewerConfigI.java +++ /dev/null @@ -1,6 +0,0 @@ -package jalview.ext.treeviewer; - -public interface TreeViewerConfigI -{ - -} diff --git a/src/jalview/ext/treeviewer/TreeViewerUtils.java b/src/jalview/ext/treeviewer/TreeViewerUtils.java index d5c1327..d065662 100644 --- a/src/jalview/ext/treeviewer/TreeViewerUtils.java +++ b/src/jalview/ext/treeviewer/TreeViewerUtils.java @@ -10,10 +10,25 @@ import java.io.File; import java.util.HashMap; import java.util.Map; +/** + * Static class containing generic methods for + * + * @author kjvanderheide + * + */ public final class TreeViewerUtils { + /** + * All tree viewers should be added to this map so that Jalview saves them to + * its project. + */ private static Map activeViews = new HashMap<>(); + /** + * + * @param treeFrame + * @return + */ public static TreeFrameI addTreeViewFrameToJalview( final TreeFrameI treeFrame) { @@ -41,6 +56,14 @@ public final class TreeViewerUtils } + /** + * + * @param treeFrame + * @param jalviewAlignViewport + * @param alignMappedToNodes + * @param nodesMappedToAlign + * @return + */ public static TreeViewerBindingI associateNodesWithJalviewSequences( final TreeFrameI treeFrame, final AlignmentViewport jalviewAlignViewport, -- 1.7.10.2