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