src/jalview/javascript/JalviewLiteJsApi.java

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