JAL-1953 some more comments, moved JalviewBinding

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

diff --git a/src/jalview/ext/treeviewer/TreePanelI.java b/src/jalview/ext/treeviewer/TreePanelI.java
index e3d5800..6871105 100644 (file)
--- a/src/jalview/ext/treeviewer/TreePanelI.java
+++ b/src/jalview/ext/treeviewer/TreePanelI.java
@@ -10,38 +10,102 @@ 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<Long> getMatchingNodes();
+  /**
+   * 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();
 
   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();
 
+  /**
+   * Gets the File from where the Tree originates.
+   * 
+   * @return
+   */
   public abstract File getTreeFile();
 
   public abstract Rectangle getVisibleArea();
 
   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);
@@ -58,6 +122,12 @@ public interface TreePanelI extends Accessible, MenuContainer
 
   public abstract void setTreeFile(File file);
 
+  /**
+   * Checks if the tree has been cut to display just a sub tree.
+   * 
+   * @return True if the panel is currently showing only a subtree, otherwise
+   *         false.
+   */
   public boolean showingSubTree();
 
 }