src/jalview/javascript/JalviewLiteJsApi.java

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