documentation (JAL-859, JAL-816, JAL-621)

[jalview.git] / src / jalview / javascript / MouseOverStructureListener.java

diff --git a/src/jalview/javascript/MouseOverStructureListener.java b/src/jalview/javascript/MouseOverStructureListener.java
index 2f28820..41af88e 100644 (file)
--- a/src/jalview/javascript/MouseOverStructureListener.java
+++ b/src/jalview/javascript/MouseOverStructureListener.java
@@ -12,6 +12,29 @@ import jalview.structure.StructureListener;
 import jalview.structure.StructureMapping;\r
 import jalview.structure.StructureSelectionManager;\r
 \r
+/**\r
+ * Propagate events involving PDB structures associated with sequences to a\r
+ * javascript function. Generally, the javascript handler is called with a\r
+ * series of arguments like (eventname, ... ). As of Jalview 2.7, the following\r
+ * different types of events are supported:\r
+ * <ul>\r
+ * <li>mouseover: javascript function called with arguments <pre>\r
+ * ['mouseover',String(pdb file URI), String(pdb file chain ID), String(residue\r
+ * number moused over), String(atom index corresponding to residue)]</pre></li>\r
+ * <li>colourstruct: javascript function called with arguments <pre>\r
+ * ['colourstruct',String(alignment view id),String(number of javascript message\r
+ * chunks to collect),String(length of first chunk in set of messages - or zero\r
+ * for null message)]</pre><br>\r
+ * The message contains a series of Jmol script commands that will colour\r
+ * structures according to their associated sequences in the current view. Use\r
+ * jalview\r
+ * .javascript.JalviewLiteJsApi.getJsMessage('colourstruct',String(alignment\r
+ * view id)) to retrieve successive chunks of the message.</li>\r
+ * </ul>\r
+ * \r
+ * @author Jim Procter (jprocter)\r
+ * \r
+ */\r
 public class MouseOverStructureListener extends JSFunctionExec implements\r
         JsCallBack, StructureListener\r
 {\r
@@ -113,7 +136,7 @@ public class MouseOverStructureListener extends JSFunctionExec implements
   {\r
     final Object source = srce;\r
     StructureSelectionManager ssm = StructureSelectionManager\r
-            .getStructureSelectionManager();\r
+            .getStructureSelectionManager(jvlite);\r
     // if (jvlite.debug)\r
     // {\r
     // ssm.reportMapping();\r
@@ -160,23 +183,28 @@ public class MouseOverStructureListener extends JSFunctionExec implements
       final String[] colcommands = JmolCommands.getColourBySequenceCommand(\r
               ssm, modelSet, sequence, sr, fr,\r
               ((AlignmentViewPanel) source).getAlignment());\r
+      if (colcommands==null)\r
+      {\r
+        // \r
+        return;\r
+      }\r
       String mclass,mhandle;\r
       if (jvlite.isJsMessageSetChanged(mclass="colourstruct",mhandle=((jalview.appletgui.AlignmentPanel) source).av\r
               .getViewId(), colcommands)) {\r
       jvlite.setJsMessageSet(mclass, mhandle , colcommands);\r
       // and notify javascript handler\r
-      String st[] = new String[0];\r
+      String st[] = new String[]\r
+                                                  {\r
+              "colourstruct",\r
+              ""\r
+                      + ((jalview.appletgui.AlignmentPanel) source).av\r
+                              .getViewId(), ""+colcommands.length, ""+(colcommands[0]!=null ? colcommands[0].length() : 0)};\r
       try\r
       {\r
         executeJavascriptFunction(\r
                 true,\r
-                _listenerfn,\r
-                st = new String[]\r
-                {\r
-                    "colourstruct",\r
-                    ""\r
-                            + ((jalview.appletgui.AlignmentPanel) source).av\r
-                                    .getViewId(), ""+colcommands.length, "" });\r
+                _listenerfn,st\r
+);\r
       } catch (Exception ex)\r
       {\r
         System.err.println("Couldn't execute callback with "\r
@@ -243,9 +271,15 @@ public class MouseOverStructureListener extends JSFunctionExec implements
     return _listenerfn;\r
   }\r
 \r
+  public void finalise()\r
+  {\r
+    jvlite=null;\r
+    super.finalize();\r
+  }\r
   @Override\r
   public void releaseReferences(Object svl)\r
   {\r
+    \r
     // TODO Auto-generated method stub\r
 \r
   }\r