JAL-1953 more javadoc comments

[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..bfd3211 100644 (file)
--- 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<Long> getMatchingNodes();
+  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();
@@ -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();
 
 }