examples/jalviewLiteJs.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
   4  * Copyright (C) 2012 J Procter, AM Waterhouse, LM Lui, J Engelhardt, G Barton, M Clamp, S Searle
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  18 -->
  19 <html><!-- InstanceBegin template="/Templates/jtemplate.dwt" codeOutsideHTMLIsLocked="false" -->
  20 <head>
  21 <!-- InstanceBeginEditable name="doctitle" -->
  22 <TITLE>JalviewLite API documentation</TITLE>
  23 <!-- InstanceEndEditable -->
  24 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><meta http-equiv="keywords" content="jalview,multiple,sequence,alignment,editor,viewer,java,download,barton group,protein,dna,das,distributed annotation system">
  25 <!-- InstanceBeginEditable name="head" -->
  26 <!-- InstanceEndEditable -->
  27 <style type="text/css">
  28 <!--
  29 td {
  30         font-family: Geneva, Arial, Helvetica, sans-serif;
  31         font-size: 12px;
  32 }
  33 .plain {
  34         font-family: Verdana, Arial, Helvetica, sans-serif;
  35         font-size: 14px;
  36         text-decoration: none;
  37 }
  38 .plain:hover{
  39         background-color:#000000; color: #F2F2FF;
  40 }
  41
  42 -->
  43 </style>
  44 <script language="JavaScript">
  45 function genHref()
  46 {
  47 var s1 = "ml:ljvwr", s2 = "athpai.g", s3 = "ioe@leo ", href="";
  48 for(i=0; i<8; i++)
  49 {href = href + s1.charAt(i) + s2.charAt(i) + s3.charAt(i);      }
  50 window.location=href;
  51 }
  52 function getEventTarget(e)
  53 {
  54 if(!e)
  55 e = window.event;
  56 if(e.target)
  57 return e.target;
  58 return e.srcElement;
  59 }
  60 </script>
  61 </head>
  62 <body alink="#000000" vlink="#000000" link="#000000">
  63 <script type="text/javascript">
  64 var gaJsHost = (("https:" == document.location.protocol) ?
  65 "https://ssl." : "http://www.");
  66 document.write(unescape("%3Cscript src='" + gaJsHost +
  67 "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
  68 </script>
  69 <script type="text/javascript">
  70 try{
  71 var pageTracker = _gat._getTracker("UA-9060947-1");
  72 pageTracker._trackPageview();
  73 } catch(err) {}
  74 </script>
  75 <div align="left">
  76   <table width="805" height="100" cellpadding="5">
  77     <tr>
  78       <td background="../jalview.gif">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://www.compbio.dundee.ac.uk" target="NEW"><img src="../uodc_r1_c1.gif" width="143" height="101" border="1"></a></td>
  79     </tr>
  80   </table>
  81   <table width="805" border="0" cellpadding="5" cellspacing="5">
  82     <tr>
  83       <td width="183" valign="top" bgcolor="#F2F2FF" border="5">
  84
  85           <div align="center">
  86           <table width="182" height="386" border="0" cellpadding="0" cellspacing="0">
  87             <tr>
  88               <td align="left" valign="middle"><a href="../index.html" class="plain">Home</a></td>
  89             </tr>
  90             <tr>
  91               <td align="left" valign="middle"><a href="../overview.html" class="plain">Overview</a></td>
  92             </tr>
  93             <tr>
  94               <td align="left" valign="middle"><a href="../download.html" class="plain">Download</a></td>
  95             </tr>
  96             <tr>
  97               <td align="left" valign="middle"><a href="applets.html" class="plain">Applet
  98                 Version</a></td>
  99             </tr>
 100             <tr>
 101               <td align="left" valign="middle"><a href="examples.html" class="plain">Screenshots</a></td>
 102             </tr>
 103             <tr>
 104               <td align="left" valign="middle"><a href="../faq.html" class="plain">FAQ</a></td>
 105             </tr>
 106             <tr>
 107               <td align="left" valign="middle"><a href="../documentList.html" class="plain">Documentation</a></td>
 108             </tr>
 109             <tr>
 110               <td align="left" valign="middle" ><a href="../releaseHistory.html" class="plain">Release
 111                 history</a></td>
 112             </tr>
 113             <tr>
 114               <td align="left" valign="middle"><a href="../source/source.html" class="plain">Source
 115                 Code</a></td>
 116             </tr>
 117                         <tr>
 118               <td align="left" valign="middle"><a href="../versions.html" class="plain">Development Version</a></td>
 119             </tr>
 120                         <tr>
 121               <td align="left" valign="middle"><a href="../links.html" class="plain">Links</a></td>
 122             </tr>
 123             <tr>
 124               <td align="left" valign="middle"><a href="http://www.jalview.org/mailman/listinfo/jalview-announce" class="plain" target="NEW">News
 125                 Mailing List</a></td>
 126             </tr>
 127             <tr>
 128               <td align="left" valign="middle"><a
 129             href="http://www.jalview.org/mailman/listinfo/jalview-discuss"
 130             class="plain" target="NEW">Discussion Mailing List</a><br><br><em>Please send problems<br>and
 131             bug reports to the discussion list.</em></td>
 132             </tr>
 133             <tr></tr>
 134             <tr>
 135               <!--<td align="left" valign="middle"><br>
 136                 Please send problems<br>and
 137             bug reports to:<br><a href="#" onClick="javascript:genHref();"><img src="../help.gif" width="123" height="19" border="0"></a></td>-->
 138             </tr>
 139           </table>
 140         </div>
 141         <div align="center"> <a href="http://www.bbsrc.ac.uk/" target="NEW"><br>
 142           <img src="../bbsrc-new.gif" width="179" height="64" border="1"></a>
 143         </div>
 144         </td>
 145       <td valign="top" width="587" bgcolor="#F2F2FF"><!-- InstanceBeginEditable name="Contents" -->
 146                 <p>&nbsp;</p>
 147                 <strong>JalviewLite Javascript API<br></strong>
 148                 <p>The jalviewLite applet's application programming interface (API) includes two components. A <a href="javascript/jalview.js">JalviewLite Javascript Library</a> and the <a href="#api">public methods on the JalviewLite applet</a>.
 149                 <p>The best way to learn how to use the API is to see it in action on the demonstration pages below:</p>
 150                 <ul>
 151           <li><a href="formComplete.html">use Javascript to control and get data from JalviewLite</a></li>
 152           <li><a href="linkedapplets_ng.html">use Javascript to make two jalviewLite instances talk to each other.</a></li>
 153           <li><a href="embeddedWJmol.html">configure JalviewLite to talk to a Jmol applet on the page (EXPERIMENTAL! please provide feedback!).</a></li>
 154           <li><a href="javascriptLaunch.html">launch JalviewLite from a javascript button</a></li>
 155
 156                 </ul>
 157                 <h4>Notes</h4>
 158                 <ul>
 159                 <li>Unfortunately Javascript - Java communication is not possible
 160                 using Internet Explorer or Opera on Macs. Please use Safari or
 161                 Firefox.</li>
 162                 <li>If more than one Jalview window is open, Jalview returns the
 163                 alignment in the active window, unless you provide an AlignFrame
 164                 object reference.</li>
 165                 <li>The alignment output format can be either Fasta, PFAM, Clustal,
 166                 MSF, PIR, or BLC.</li>
 167                 <li>When referring to the Jalview applet in javascript, you must
 168                 either give Jalview a name in the applet tag or use the document.applets index.</li>
 169                 <li>When creating javascript functions that are called by jalviewLite (e.g. the <em>oninit</em> parameter, or any mouseOver, selection or structureListener handlers), ensure they complete very quickly, and do not access any jalview API methods that might result in more javascript calls (this which will cause your browser to hang). If you need to do this, we suggest that jalviewLite callbacks are used to add new javascript events to a queue (e.g. using a Jquery timer callback) to avoid any concurrency issues.
 170                 </li>
 171                 </ul>
 172                 <a name="api">
 173                 <h4>JalviewLite's Java API</h4></a>
 174                 <p>The following public methods on the jalviewLite applet are available to be called from javascript:</p>
 175                 <pre>//get list of IDs of selected sequences
 176 public String getSelectedSequences()
 177
 178 // list of IDs of selected sequences terminated by sep or, if sep is null, '&#172;' (&amp;#172;)
 179 public String getSelectedSequences(sep)
 180
 181 // get list of selected sequences from specific alignFrame. (2.7)
 182 public String getSelectedSequencesFrom(AlignFrame alf)
 183 public String getSelectedSequencesFrom(AlignFrame alf, String sep)
 184
 185 // highlight a position in a specific sequence or a column in an alignment containing it
 186 // provide ID sequence to highlight, integer (range highlighting will be supported in future versions)
 187 // and flag indicating if position is an alignment column or given according to sequence numbering (2.7)
 188 public void highlight(String sequenceId, String position, String alignedPosition)
 189 public void highlightIn(AlignFrame alf, String sequenceId, String position, String alignedPosition)
 190
 191
 192 // select regions of the currrent alignment frame using a list of sequence ids and a list of
 193 // column numbers and ranges (with minus sign indicating start-end) (separated by default separator) (2.7)
 194 public void select(String sequenceIds, String columns)
 195 public void select(String sequenceIds, String columns, String sep)
 196 public void selectIn(AlignFrame alf, String sequenceIds, String columns)
 197 public void selectIn(AlignFrame alf, String sequenceIds, String columns, String sep)
 198
 199
 200 // get selected sequences as alignment as format with or without start-end suffix
 201 public String getSelectedSequencesAsAlignment(String format, boolean suffix)
 202
 203 // get selected sequences as alignment from given view as format with or without start-end suffix
 204 public String getSelectedSequencesAsAlignmentFrom(AlignFrame alf, String format, boolean suffix)
 205
 206 // get a separator separated list of sequence IDs reflecting the order of the current alignment (2.7)
 207 public String getAlignmentOrder();
 208 public String getAlignmentOrderFrom(AlignFrame alf);
 209 public String getAlignmentOrderFrom(AlignFrame alf, String sep);
 210
 211 // re-order the current alignment using the given list of sequence IDs separated by sep
 212 // undoName - is string to use when referring to ordering action in undo buffer
 213 // returns 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
 214 // (v2.7)
 215 public String orderBy(String order, String undoName)
 216 public String orderBy(String order, String undoName, String sep)
 217 String orderAlignmentBy(AlignFrame alf, String order, String undoName, String sep)
 218
 219
 220 // get alignment as format
 221 public String getAlignment(String format)
 222
 223 // get alignment as format with jalview
 224 // start-end sequence suffix appended
 225 public String getAlignment(String format, String suffix)
 226
 227 // get alignment displayed in alf as format
 228 public String getAlignmentFrom(AlignFrame alf, String format)
 229
 230 // get alignment displayed in alf as format
 231 // with jalview start-end sequence suffix appended
 232 public String getAlignmentFrom(AlignFrame alf, String format, String suffix)
 233
 234 // add the given features or annotation to the current alignment
 235 // if features are loaded, feature display is automatically enabled
 236 public void loadAnnotation(String annotation)
 237
 238 // add the given features or annotation to the given alignment view
 239 // if features are loaded, feature display is automatically enabled
 240 public void loadAnnotationFrom(AlignFrame alf, String annotation)
 241
 242 // parse the given string as a jalview or GFF features file and optionally enable feature display on the current alignment
 243 // (v2.7.1)
 244 public abstract void loadFeatures(String features, boolean autoenabledisplay)
 245
 246 // parse the given string as a jalview or GFF features file and optionally enable feature display on the given alignment
 247 // (v2.7.1)
 248 public abstract void loadFeaturesFrom(AlignFrame alf, String features, boolean autoenabledisplay)
 249
 250 // get the sequence features in the given format (Jalview or GFF)
 251 public String getFeatures(String format)
 252
 253 // get the sequence features in alf in the given format (Jalview or GFF)
 254 public String getFeaturesFrom(AlignFrame alf, String format)
 255
 256 // get current alignment's annotation as an annotation file
 257 public String getAnnotation()
 258
 259 // get alignment view alf's annotation as an annotation file
 260 public String getAnnotationFrom(AlignFrame alf)
 261
 262 // create a new view and return the alignFrame instance
 263 public AlignFrame newView()
 264
 265 // create a new view named name and return the alignFrame instance
 266 public AlignFrame newView(String name)
 267
 268 // create a new view on alf and return the alignFrame instance
 269 public AlignFrame newViewFrom(AlignFrame alf)
 270
 271 // create a new view named name on alf
 272 // and return the alignFrame instance
 273 public AlignFrame newViewFrom(AlignFrame alf, String name)
 274
 275 // load a new alignment
 276 // remember to store the AlignFrame object reference
 277 // if you want to manipulate the new alignment view.
 278 public AlignFrame loadAlignment(String text, String title)
 279
 280
 281 // register a javascript function to handle any alignment mouseover events
 282 // listener is name of javascript function  which will be called
 283 // with arguments [jalview.appletgui.AlignFrame,String(sequence id),
 284 // String(column in alignment), String(position in sequence)]
 285 // (v2.7)
 286 public void setMouseoverListener(String listener)
 287
 288 // register a javascript function to handle mouseover events for specific alignframe
 289 // (v2.7)
 290 public void setMouseoverListener(AlignFrame af, String listener)
 291
 292 // register a javascript function to handle alignment selection events.
 293 // Events are generated when the user completes a selection event, or when
 294 // the user deselects all selected regions.
 295 // listener is name of javascript function  that will be called with arguments
 296 //  [jalview.appletgui.AlignFrame, String(sequence set id),
 297 //   String(separator separated list of sequences which were selected),
 298 //   String(separator separated list of column ranges)]
 299 // (v2.7)
 300 public void setSelectionListener(String listener)
 301
 302 // register a selection listener for a specific alignment frame
 303 // (v2.7)
 304 public void setSelectionListener(AlignFrame af, String listener)
 305
 306 // register a javascript function to handle events normally routed
 307 // to a Jmol structure viewer.
 308 // listener is a javascript function called with several different types
 309 // of arguments, dependent on the type of structure callback event.
 310 // See jalview.javascript.MouseOverStructureListener for full details or
 311 // the embedded Jmol example.
 312 // modelSet - is a separator separated list of PDB file URIs that this viewer is handling (where position in list equals model number in Jmol).
 313 // (v2.7)
 314 public void setStructureListener(String listener, String modelSet)
 315
 316 // remove any callback using the given listener function and associated with
 317 // the given alignFrame (or null for all callbacks) (v2.7)
 318 public void removeJavascriptListener(AlignFrame af, String listener)
 319
 320 // send a mouseover message to all the alignment windows associated with the
 321 // given residue in the pdbfile (v2.7)
 322 public void mouseOverStructure(String pdbResNum, String chain, String pdbfile)
 323
 324 // bind a pdb file to a sequence in the given alignFrame - this will be searched
 325 // for sequences matching sequenceId. The PDB file in pdbFile is either the contents
 326 // of a PDB file or a URI that can be used to retrieve the file, and the pdbEntryString
 327 // is the user friendly name (or PDBID) shown in jalview's user interface.
 328 // returns true if binding was as success (v2.7)
 329 public boolean addPdbFile(AlignFrame alFrame,
 330     String sequenceId, String pdbEntryString, String pdbFile)
 331
 332 // adjust horizontal/vertical scroll in alf to the make
 333 // the given location the top left hand corner for given current view (v2.7)
 334 public void scrollViewToIn(AlignFrame alf, String topRow, String leftHandColumn)
 335
 336 // adjust horizontal scroll in alf to the make
 337 // the given location the left hand corner for given current view (v2.7)
 338 public void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn)
 339
 340 // adjust horizontal/vertical scroll in alf to the make
 341 // the given location the top row for given current view (v2.7)
 342 public void scrollViewToRowIn(AlignFrame alf, String topRow)
 343
 344
 345 // return separator separated list of feature groups
 346 // on the current alignment
 347 public String getFeatureGroups()
 348
 349 // return separator separated list of feature groups on alf
 350 public String getFeatureGroupsOn(AlignFrame alf)
 351
 352 // return separator separated list of feature groups
 353 // either visible or hidden
 354 public String getFeatureGroupsOfState(boolean state)
 355
 356 // return separator separated list of feature groups
 357 // either visible or hidden on alf
 358 public String getFeatureGroupsOfStateOn(AlignFrame alf, boolean state)
 359
 360 // set the separator separated list of feature groups as
 361 // visible or hidden on the current alignment
 362 public void setFeatureGroupState(String groupList, boolean state)
 363
 364 // set the separator separated list of feature groups
 365 // as visible or hidden on alf
 366 public void setFeatureGroupStateOn(AlignFrame alf, String groupList, boolean state)
 367
 368 // helper functions
 369
 370 // Asynchronously retrieve next chunk of a large packet of data made available
 371 // for a JalviewLite event handler, or the empty string if no more data is available.
 372 // messageclass and viewId are keys used to retrieve a specific message related
 373 // to an event.
 374 // Use this in a javascript timer or GUI update thread to retrieve data without
 375 // blocking the JalviewLite applet. DO NOT USE IN THE CALLBACK THAT HANDLED THE EVENT
 376 // (v2.7)
 377 public String getJsMessage(String messageclass, String viewId)
 378
 379
 380 // convert list to a separator separated array
 381 public String arrayToSeparatorList(String[] list)
 382
 383 // get a string array from a list
 384 public String[] separatorListToArray(String list)
 385
 386 // get the current separator
 387 public String getSeparator()
 388
 389 // set the current separator
 390 public void setSeparator(String)
 391
 392 //// JalviewLite global state methods and fields
 393
 394 // return the build date as a string
 395 public static String getBuildDate()
 396
 397 // return the JalviewLite version as a string
 398 public static String getVersion()
 399
 400 // debug flag - controls output to standard out
 401 public static boolean debug
 402
 403 </pre> <!-- InstanceEndEditable --></td>
 404     </tr>
 405   </table>
 406 </div>
 407 </body>
 408 <!-- InstanceEnd --></html>