src/jalview/javascript/JalviewLiteJsApi.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$);
   3  * Copyright (C); $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * 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
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.javascript;
  22
  23 import jalview.api.AlignFrameI;
  24
  25 /**
  26  * The following public methods may be called
  27  * externally, eg via javascript in an HTML page.
  28  *
  29  * <br><em>TODO: introduce abstract interface for jalview.appletgui.AlignFrameI</em><br>
  30  *
  31  * Most function arguments are strings, which contain serialised versions of lists.
  32  * Lists of things are separated by a separator character - either the default or a user supplied one.
  33  * Ranges and positions on an alignment or sequence can be specified as a list, where an item containing a single number is a single position, and an item like 1-2 specifies columns 1 and 2 as a range.
  34  */
  35
  36 /**
  37  * @author jimp
  38  *
  39  */
  40 public interface JalviewLiteJsApi
  41 {
  42
  43   /**
  44    * @return String list of selected sequence IDs, each terminated by the
  45    *         'boolean not' character (""+0x00AC); or (&#172;);
  46    */
  47   public abstract String getSelectedSequences();
  48
  49   /**
  50    * @param sep
  51    *          separator string or null for default
  52    * @return String list of selected sequence IDs, each terminated by given
  53    *         separator string
  54    */
  55   public abstract String getSelectedSequences(String sep);
  56
  57   /**
  58    * @param alf
  59    *          AlignFrameI containing selection
  60    * @return String list of selected sequence IDs, each terminated by current
  61    *         default separator sequence
  62    *
  63    */
  64   public abstract String getSelectedSequencesFrom(AlignFrameI alf);
  65
  66   /**
  67    * get list of selected sequence IDs separated by given separator
  68    *
  69    * @param alf
  70    *          window containing selection
  71    * @param sep
  72    *          separator string to use - default is 'boolean not'
  73    * @return String list of selected sequence IDs, each terminated by the given
  74    *         separator
  75    */
  76   public abstract String getSelectedSequencesFrom(AlignFrameI alf,
  77           String sep);
  78
  79   /**
  80    *
  81    * @param sequenceId
  82    *          id of sequence to highlight
  83    * @param position
  84    *          integer position [ tobe implemented or range ] on sequence
  85    * @param alignedPosition
  86    *          true/false/empty string - indicate if position is an alignment
  87    *          column or unaligned sequence position
  88    */
  89   public abstract void highlight(String sequenceId, String position,
  90           String alignedPosition);
  91
  92   /**
  93    *
  94    * @param sequenceId
  95    *          id of sequence to highlight
  96    * @param position
  97    *          integer position [ tobe implemented or range ] on sequence
  98    * @param alignedPosition
  99    *          false, blank or something else - indicate if position is an
 100    *          alignment column or unaligned sequence position
 101    */
 102   public abstract void highlightIn(AlignFrameI alf, String sequenceId,
 103           String position, String alignedPosition);
 104
 105   /**
 106    * select regions of the currrent alignment frame
 107    *
 108    * @param sequenceIds
 109    *          String separated list of sequence ids or empty string
 110    * @param columns
 111    *          String separated list { column range or column, ..} or empty
 112    *          string
 113    */
 114   public abstract void select(String sequenceIds, String columns);
 115
 116   /**
 117    * select regions of the currrent alignment frame
 118    *
 119    * @param toselect
 120    *          String separated list { column range, seq1...seqn sequence ids }
 121    * @param sep
 122    *          separator between toselect fields
 123    */
 124   public abstract void select(String sequenceIds, String columns,
 125           String sep);
 126
 127   /**
 128    * select regions of the given alignment frame
 129    *
 130    * @param alf
 131    * @param toselect
 132    *          String separated list { column range, seq1...seqn sequence ids }
 133    * @param sep
 134    *          separator between toselect fields
 135    */
 136   public abstract void selectIn(AlignFrameI alf, String sequenceIds,
 137           String columns);
 138
 139   /**
 140    * select regions of the given alignment frame
 141    *
 142    * @param alf
 143    * @param toselect
 144    *          String separated list { column range, seq1...seqn sequence ids }
 145    * @param sep
 146    *          separator between toselect fields
 147    */
 148   public abstract void selectIn(AlignFrameI alf, String sequenceIds,
 149           String columns, String sep);
 150
 151   /**
 152    * get sequences selected in current AlignFrameI and return their alignment in
 153    * format 'format' either with or without suffix
 154    *
 155    * @param alf
 156    *          - where selection is
 157    * @param format
 158    *          - format of alignment file
 159    * @param suffix
 160    *          - "true" to append /start-end string to each sequence ID
 161    * @return selected sequences as flat file or empty string if there was no
 162    *         current selection
 163    */
 164   public abstract String getSelectedSequencesAsAlignment(String format,
 165           String suffix);
 166
 167   /**
 168    * get sequences selected in alf and return their alignment in format 'format'
 169    * either with or without suffix
 170    *
 171    * @param alf
 172    *          - where selection is
 173    * @param format
 174    *          - format of alignment file
 175    * @param suffix
 176    *          - "true" to append /start-end string to each sequence ID
 177    * @return selected sequences as flat file or empty string if there was no
 178    *         current selection
 179    */
 180   public abstract String getSelectedSequencesAsAlignmentFrom(
 181           AlignFrameI alf,
 182           String format, String suffix);
 183
 184   /**
 185    * get a separator separated list of sequence IDs reflecting the order of the
 186    * current alignment
 187    *
 188    * @return
 189    */
 190   public abstract String getAlignmentOrder();
 191
 192   /**
 193    * get a separator separated list of sequence IDs reflecting the order of the
 194    * alignment in alf
 195    *
 196    * @param alf
 197    * @return
 198    */
 199   public abstract String getAlignmentOrderFrom(AlignFrameI alf);
 200
 201   /**
 202    * get a sep separated list of sequence IDs reflecting the order of the
 203    * alignment in alf
 204    *
 205    * @param alf
 206    * @param sep
 207    *          - separator to use
 208    * @return
 209    */
 210   public abstract String getAlignmentOrderFrom(AlignFrameI alf,
 211           String sep);
 212
 213   /**
 214    * re-order the current alignment using the given list of sequence IDs
 215    *
 216    * @param order
 217    *          - sep separated list
 218    * @param undoName
 219    *          - string to use when referring to ordering action in undo buffer
 220    * @return 'true' if alignment was actually reordered. empty string if
 221    *         alignment did not contain sequences.
 222    */
 223   public abstract String orderBy(String order, String undoName);
 224
 225   /**
 226    * re-order the current alignment using the given list of sequence IDs
 227    * separated by sep
 228    *
 229    * @param order
 230    *          - sep separated list
 231    * @param undoName
 232    *          - string to use when referring to ordering action in undo buffer
 233    * @param sep
 234    * @return 'true' if alignment was actually reordered. empty string if
 235    *         alignment did not contain sequences.
 236    */
 237   public abstract String orderBy(String order, String undoName,
 238           String sep);
 239
 240   /**
 241    * re-order the given alignment using the given list of sequence IDs separated
 242    * by sep
 243    *
 244    * @param alf
 245    * @param order
 246    *          - sep separated list
 247    * @param undoName
 248    *          - string to use when referring to ordering action in undo buffer
 249    * @param sep
 250    * @return 'true' if alignment was actually reordered. empty string if
 251    *         alignment did not contain sequences.
 252    */
 253   public abstract String orderAlignmentBy(AlignFrameI alf, String order,
 254           String undoName, String sep);
 255
 256   /**
 257    * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
 258    * PFAM - see jalview.io.AppletFormatAdapter for full list);
 259    *
 260    * @param format
 261    * @return
 262    */
 263   public abstract String getAlignment(String format);
 264
 265   /**
 266    * get alignment displayed in alf as format
 267    *
 268    * @param alf
 269    * @param format
 270    * @return
 271    */
 272   public abstract String getAlignmentFrom(AlignFrameI alf, String format);
 273
 274   /**
 275    * get alignment as format with jalview start-end sequence suffix appended
 276    *
 277    * @param format
 278    * @param suffix
 279    * @return
 280    */
 281   public abstract String getAlignment(String format, String suffix);
 282
 283   /**
 284    * get alignment displayed in alf as format with or without the jalview
 285    * start-end sequence suffix appended
 286    *
 287    * @param alf
 288    * @param format
 289    * @param suffix
 290    * @return
 291    */
 292   public abstract String getAlignmentFrom(AlignFrameI alf, String format,
 293           String suffix);
 294
 295   /**
 296    * add the given features or annotation to the current alignment
 297    *
 298    * @param annotation
 299    */
 300   public abstract void loadAnnotation(String annotation);
 301
 302   /**
 303    * add the given features or annotation to the given alignment view
 304    *
 305    * @param alf
 306    * @param annotation
 307    */
 308   public abstract void loadAnnotationFrom(AlignFrameI alf,
 309           String annotation);
 310
 311   /**
 312    * parse the given string as a jalview feature or GFF annotation file and
 313    * optionally enable feature display on the current AlignFrameI
 314    *
 315    * @param features
 316    *          - gff or features file
 317    * @param autoenabledisplay
 318    *          - when true, feature display will be enabled if any features can
 319    *          be parsed from the string.
 320    */
 321   public abstract void loadFeatures(String features,
 322           boolean autoenabledisplay);
 323
 324   /**
 325    * parse the given string as a jalview feature or GFF annotation file and
 326    * optionally enable feature display on the given AlignFrameI.
 327    *
 328    * @param alf
 329    * @param features
 330    *          - gff or features file
 331    * @param autoenabledisplay
 332    *          - when true, feature display will be enabled if any features can
 333    *          be parsed from the string.
 334    * @return true if data parsed as features
 335    */
 336   public abstract boolean loadFeaturesFrom(AlignFrameI alf, String features,
 337           boolean autoenabledisplay);
 338
 339   /**
 340    * get the sequence features in the given format (Jalview or GFF);
 341    *
 342    * @param format
 343    * @return
 344    */
 345   public abstract String getFeatures(String format);
 346
 347   /**
 348    * get the sequence features in alf in the given format (Jalview or GFF);
 349    *
 350    * @param alf
 351    * @param format
 352    * @return
 353    */
 354   public abstract String getFeaturesFrom(AlignFrameI alf, String format);
 355
 356   /**
 357    * get current alignment's annotation as an annotation file
 358    *
 359    * @return
 360    */
 361   public abstract String getAnnotation();
 362
 363   /**
 364    * get alignment view alf's annotation as an annotation file
 365    *
 366    * @param alf
 367    * @return
 368    */
 369   public abstract String getAnnotationFrom(AlignFrameI alf);
 370
 371   /**
 372    * create a new view and return the AlignFrameI instance
 373    *
 374    * @return
 375    */
 376   public abstract AlignFrameI newView();
 377
 378   /**
 379    * create a new view named name and return the AlignFrameI instance
 380    *
 381    * @param name
 382    * @return
 383    */
 384   public abstract AlignFrameI newView(String name);
 385
 386   /**
 387    * create a new view on alf and return the AlignFrameI instance
 388    *
 389    * @param alf
 390    * @return
 391    */
 392   public abstract AlignFrameI newViewFrom(AlignFrameI alf);
 393
 394   /**
 395    * create a new view named name on alf
 396    *
 397    * @param alf
 398    * @param name
 399    * @return
 400    */
 401   public abstract AlignFrameI newViewFrom(AlignFrameI alf, String name);
 402
 403   /**
 404    *
 405    * @param text
 406    *          alignment file as a string
 407    * @param title
 408    *          window title
 409    * @return null or new alignment frame
 410    */
 411   public abstract AlignFrameI loadAlignment(String text, String title);
 412
 413   /**
 414    * register a javascript function to handle any alignment mouseover events
 415    *
 416    * @param listener
 417    *          name of javascript function (called with arguments
 418    *          [jalview.appletgui.AlignFrameI,String(sequence id);,String(column
 419    *          in alignment);, String(position in sequence);]
 420    */
 421   public abstract void setMouseoverListener(String listener);
 422
 423   /**
 424    * register a javascript function to handle mouseover events
 425    *
 426    * @param af
 427    *          (null or specific AlignFrameI for which events are to be listened
 428    *          for);
 429    * @param listener
 430    *          name of javascript function
 431    */
 432   public abstract void setMouseoverListener(AlignFrameI af,
 433           String listener);
 434
 435   /**
 436    * register a javascript function to handle any alignment selection events.
 437    * Events are generated when the user completes a selection event, or when the
 438    * user deselects all selected regions.
 439    *
 440    * @param listener
 441    *          name of javascript function (called with arguments
 442    *          [jalview.appletgui.AlignFrameI, String(sequence set id);,
 443    *          String(separator separated list of sequences which were
 444    *          selected);, String(separator separated list of column ranges (i.e.
 445    *          single number or hyphenated range); that were selected);]
 446    */
 447   public abstract void setSelectionListener(String listener);
 448
 449   public abstract void setSelectionListener(AlignFrameI af,
 450           String listener);
 451
 452   /**
 453    * register a javascript function to handle events normally routed to a Jmol
 454    * structure viewer.
 455    *
 456    * @param listener
 457    *          - javascript function (arguments are variable, see
 458    *          jalview.javascript.MouseOverStructureListener for full details);
 459    * @param modelSet
 460    *          - separator separated list of PDB file URIs that this viewer is
 461    *          handling. These files must be in the same order they appear in
 462    *          Jmol (e.g. first one is frame 1, second is frame 2, etc);.
 463    * @see jalview.javascript.MouseOverStructureListener
 464    */
 465   public abstract void setStructureListener(String listener,
 466           String modelSet);
 467
 468   /**
 469    * remove any callback using the given listener function and associated with
 470    * the given AlignFrameI (or null for all callbacks);
 471    *
 472    * @param af
 473    *          (may be null);
 474    * @param listener
 475    *          (may be null);
 476    */
 477   public abstract void removeJavascriptListener(AlignFrameI af,
 478           String listener);
 479
 480   /**
 481    * send a mouseover message to all the alignment windows associated with the
 482    * given residue in the pdbfile
 483    *
 484    * @param pdbResNum
 485    * @param chain
 486    * @param pdbfile
 487    */
 488   public abstract void mouseOverStructure(String pdbResNum, String chain,
 489           String pdbfile);
 490
 491   /**
 492    * bind a pdb file to a sequence in the given AlignFrameI.
 493    *
 494    * @param alFrame
 495    *          - null or specific AlignFrameI. This specifies the dataset that
 496    *          will be searched for a seuqence called sequenceId
 497    * @param sequenceId
 498    *          - sequenceId within the dataset.
 499    * @param pdbEntryString
 500    *          - the short name for the PDB file
 501    * @param pdbFile
 502    *          - pdb file - either a URL or a valid PDB file.
 503    * @return true if binding was as success TODO: consider making an exception
 504    *         structure for indicating when PDB parsing or sequenceId location
 505    *         fails.
 506    */
 507   public abstract boolean addPdbFile(AlignFrameI alFrame, String sequenceId,
 508           String pdbEntryString, String pdbFile);
 509
 510   /**
 511    * adjust horizontal/vertical scroll to make the given location the top left
 512    * hand corner for the given view
 513    *
 514    * @param alf
 515    * @param topRow
 516    * @param leftHandColumn
 517    */
 518   public abstract void scrollViewToIn(AlignFrameI alf, String topRow,
 519           String leftHandColumn);
 520
 521   /**
 522    * adjust vertical scroll to make the given row the top one for given view
 523    *
 524    * @param alf
 525    * @param topRow
 526    */
 527   public abstract void scrollViewToRowIn(AlignFrameI alf, String topRow);
 528
 529   /**
 530    * adjust horizontal scroll to make the given column the left one in the given
 531    * view
 532    *
 533    * @param alf
 534    * @param leftHandColumn
 535    */
 536   public abstract void scrollViewToColumnIn(AlignFrameI alf,
 537           String leftHandColumn);
 538
 539   /**
 540    *
 541    * @return
 542    * @see jalview.appletgui.AlignFrameI#getFeatureGroups();
 543    */
 544   public abstract String getFeatureGroups();
 545
 546   /**
 547    * @param alf
 548    *          AlignFrameI to get feature groups on
 549    * @return
 550    * @see jalview.appletgui.AlignFrameI#getFeatureGroups();
 551    */
 552   public abstract String getFeatureGroupsOn(AlignFrameI alf);
 553
 554   /**
 555    * @param visible
 556    * @return
 557    * @see jalview.appletgui.AlignFrameI#getFeatureGroupsOfState(boolean);
 558    */
 559   public abstract String getFeatureGroupsOfState(boolean visible);
 560
 561   /**
 562    * @param alf
 563    *          align frame to get groups of state visible
 564    * @param visible
 565    * @return
 566    * @see jalview.appletgui.AlignFrameI#getFeatureGroupsOfState(boolean);
 567    */
 568   public abstract String getFeatureGroupsOfStateOn(AlignFrameI alf,
 569           boolean visible);
 570
 571   /**
 572    * @param groups
 573    *          tab separated list of group names
 574    * @param state
 575    *          true or false
 576    * @see jalview.appletgui.AlignFrameI#setFeatureGroupState(java.lang.String[],
 577    *      boolean);
 578    */
 579   public abstract void setFeatureGroupStateOn(AlignFrameI alf,
 580           String groups,
 581           boolean state);
 582
 583   public abstract void setFeatureGroupState(String groups, boolean state);
 584
 585   /**
 586    * List separator string
 587    *
 588    * @return the separator
 589    */
 590   public abstract String getSeparator();
 591
 592   /**
 593    * List separator string
 594    *
 595    * @param separator
 596    *          the separator to set. empty string will reset separator to default
 597    */
 598   public abstract void setSeparator(String separator);
 599
 600   /**
 601    * Retrieve fragments of a large packet of data made available by JalviewLite.
 602    *
 603    * @param messageclass
 604    * @param viewId
 605    * @return next chunk of message
 606    */
 607   public abstract String getJsMessage(String messageclass, String viewId);
 608
 609   /// in http://www.jalview.org/examples/jalviewLiteJs.html but missing here
 610
 611   // get selected sequences as alignment as format with or without start-end
 612   // suffix
 613   public String getSelectedSequencesAsAlignment(String format,
 614           boolean suffix);
 615
 616   // get selected sequences as alignment from given view as format with or
 617   // without start-end suffix
 618   public String getSelectedSequencesAsAlignmentFrom(AlignFrameI alf,
 619           String format, boolean suffix);
 620
 621   public String arrayToSeparatorList(String[] array);
 622
 623   // get a string array from a list
 624   public String[] separatorListToArray(String list);
 625
 626   // debug flag - controls output to standard out
 627   public static boolean debug = false;
 628
 629 }