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, String sep);
 211
 212   /**
 213    * re-order the current alignment using the given list of sequence IDs
 214    *
 215    * @param order
 216    *          - sep separated list
 217    * @param undoName
 218    *          - string to use when referring to ordering action in undo buffer
 219    * @return 'true' if alignment was actually reordered. empty string if
 220    *         alignment did not contain sequences.
 221    */
 222   public abstract String orderBy(String order, String undoName);
 223
 224   /**
 225    * re-order the current alignment using the given list of sequence IDs
 226    * separated by sep
 227    *
 228    * @param order
 229    *          - sep separated list
 230    * @param undoName
 231    *          - string to use when referring to ordering action in undo buffer
 232    * @param sep
 233    * @return 'true' if alignment was actually reordered. empty string if
 234    *         alignment did not contain sequences.
 235    */
 236   public abstract String orderBy(String order, String undoName, String sep);
 237
 238   /**
 239    * re-order the given alignment using the given list of sequence IDs separated
 240    * by sep
 241    *
 242    * @param alf
 243    * @param order
 244    *          - sep separated list
 245    * @param undoName
 246    *          - string to use when referring to ordering action in undo buffer
 247    * @param sep
 248    * @return 'true' if alignment was actually reordered. empty string if
 249    *         alignment did not contain sequences.
 250    */
 251   public abstract String orderAlignmentBy(AlignFrameI alf, String order,
 252           String undoName, String sep);
 253
 254   /**
 255    * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
 256    * PFAM - see jalview.io.AppletFormatAdapter for full list)
 257    *
 258    * @param format
 259    * @return
 260    */
 261   public abstract String getAlignment(String format);
 262
 263   /**
 264    * get alignment displayed in alf as format
 265    *
 266    * @param alf
 267    * @param format
 268    * @return
 269    */
 270   public abstract String getAlignmentFrom(AlignFrameI alf, String format);
 271
 272   /**
 273    * get alignment as format with jalview start-end sequence suffix appended
 274    *
 275    * @param format
 276    * @param suffix
 277    * @return
 278    */
 279   public abstract String getAlignment(String format, String suffix);
 280
 281   /**
 282    * get alignment displayed in alf as format with or without the jalview
 283    * start-end sequence suffix appended
 284    *
 285    * @param alf
 286    * @param format
 287    * @param suffix
 288    * @return
 289    */
 290   public abstract String getAlignmentFrom(AlignFrameI alf, String format,
 291           String suffix);
 292
 293   /**
 294    * add the given features or annotation to the current alignment
 295    *
 296    * @param annotation
 297    */
 298   public abstract void loadAnnotation(String annotation);
 299
 300   /**
 301    * add the given features or annotation to the given alignment view
 302    *
 303    * @param alf
 304    * @param annotation
 305    */
 306   public abstract void loadAnnotationFrom(AlignFrameI alf,
 307           String annotation);
 308
 309   /**
 310    * parse the given string as a jalview feature or GFF annotation file and
 311    * optionally enable feature display on the current AlignFrameI
 312    *
 313    * @param features
 314    *          - gff or features file
 315    * @param autoenabledisplay
 316    *          - when true, feature display will be enabled if any features can
 317    *          be parsed from the string.
 318    */
 319   public abstract void loadFeatures(String features,
 320           boolean autoenabledisplay);
 321
 322   /**
 323    * parse the given string as a jalview feature or GFF annotation file and
 324    * optionally enable feature display on the given AlignFrameI.
 325    *
 326    * @param alf
 327    * @param features
 328    *          - gff or features file
 329    * @param autoenabledisplay
 330    *          - when true, feature display will be enabled if any features can
 331    *          be parsed from the string.
 332    * @return true if data parsed as features
 333    */
 334   public abstract boolean loadFeaturesFrom(AlignFrameI alf, String features,
 335           boolean autoenabledisplay);
 336
 337   /**
 338    * get the sequence features in the given format (Jalview or GFF)
 339    *
 340    * @param format
 341    * @return
 342    */
 343   public abstract String getFeatures(String format);
 344
 345   /**
 346    * get the sequence features in alf in the given format (Jalview or GFF)
 347    *
 348    * @param alf
 349    * @param format
 350    * @return
 351    */
 352   public abstract String getFeaturesFrom(AlignFrameI alf, String format);
 353
 354   /**
 355    * get current alignment's annotation as an annotation file
 356    *
 357    * @return
 358    */
 359   public abstract String getAnnotation();
 360
 361   /**
 362    * get alignment view alf's annotation as an annotation file
 363    *
 364    * @param alf
 365    * @return
 366    */
 367   public abstract String getAnnotationFrom(AlignFrameI alf);
 368
 369   /**
 370    * create a new view and return the AlignFrameI instance
 371    *
 372    * @return
 373    */
 374   public abstract AlignFrameI newView();
 375
 376   /**
 377    * create a new view named name and return the AlignFrameI instance
 378    *
 379    * @param name
 380    * @return
 381    */
 382   public abstract AlignFrameI newView(String name);
 383
 384   /**
 385    * create a new view on alf and return the AlignFrameI instance
 386    *
 387    * @param alf
 388    * @return
 389    */
 390   public abstract AlignFrameI newViewFrom(AlignFrameI alf);
 391
 392   /**
 393    * create a new view named name on alf
 394    *
 395    * @param alf
 396    * @param name
 397    * @return
 398    */
 399   public abstract AlignFrameI newViewFrom(AlignFrameI alf, String name);
 400
 401   /**
 402    *
 403    * @param text
 404    *          alignment file as a string
 405    * @param title
 406    *          window title
 407    * @return null or new alignment frame
 408    */
 409   public abstract AlignFrameI loadAlignment(String text, String title);
 410
 411   /**
 412    * register a javascript function to handle any alignment mouseover events
 413    *
 414    * @param listener
 415    *          name of javascript function (called with arguments
 416    *          [jalview.appletgui.AlignFrameI,String(sequence id),String(column
 417    *          in alignment), String(position in sequence)]
 418    */
 419   public abstract void setMouseoverListener(String listener);
 420
 421   /**
 422    * register a javascript function to handle mouseover events
 423    *
 424    * @param af
 425    *          (null or specific AlignFrameI for which events are to be listened
 426    *          for)
 427    * @param listener
 428    *          name of javascript function
 429    */
 430   public abstract void setMouseoverListener(AlignFrameI af,
 431           String listener);
 432
 433   /**
 434    * register a javascript function to handle any alignment selection events.
 435    * Events are generated when the user completes a selection event, or when the
 436    * user deselects all selected regions.
 437    *
 438    * @param listener
 439    *          name of javascript function (called with arguments
 440    *          [jalview.appletgui.AlignFrameI, String(sequence set id),
 441    *          String(separator separated list of sequences which were selected),
 442    *          String(separator separated list of column ranges (i.e. single
 443    *          number or hyphenated range) that were selected)]
 444    */
 445   public abstract void setSelectionListener(String listener);
 446
 447   public abstract void setSelectionListener(AlignFrameI af,
 448           String listener);
 449
 450   /**
 451    * register a javascript function to handle events normally routed to a Jmol
 452    * structure viewer.
 453    *
 454    * @param listener
 455    *          - javascript function (arguments are variable, see
 456    *          jalview.javascript.MouseOverStructureListener for full details)
 457    * @param modelSet
 458    *          - separator separated list of PDB file URIs that this viewer is
 459    *          handling. These files must be in the same order they appear in
 460    *          Jmol (e.g. first one is frame 1, second is frame 2, etc).
 461    * @see jalview.javascript.MouseOverStructureListener
 462    */
 463   public abstract void setStructureListener(String listener,
 464           String modelSet);
 465
 466   /**
 467    * remove any callback using the given listener function and associated with
 468    * the given AlignFrameI (or null for all callbacks)
 469    *
 470    * @param af
 471    *          (may be null)
 472    * @param listener
 473    *          (may be null)
 474    */
 475   public abstract void removeJavascriptListener(AlignFrameI af,
 476           String listener);
 477
 478   /**
 479    * send a mouseover message to all the alignment windows associated with the
 480    * given residue in the pdbfile
 481    *
 482    * @param pdbResNum
 483    * @param chain
 484    * @param pdbfile
 485    */
 486   public abstract void mouseOverStructure(String pdbResNum, String chain,
 487           String pdbfile);
 488
 489   /**
 490    * bind a pdb file to a sequence in the given AlignFrameI.
 491    *
 492    * @param alFrame
 493    *          - null or specific AlignFrameI. This specifies the dataset that
 494    *          will be searched for a seuqence called sequenceId
 495    * @param sequenceId
 496    *          - sequenceId within the dataset.
 497    * @param pdbEntryString
 498    *          - the short name for the PDB file
 499    * @param pdbFile
 500    *          - pdb file - either a URL or a valid PDB file.
 501    * @return true if binding was as success TODO: consider making an exception
 502    *         structure for indicating when PDB parsing or sequenceId location
 503    *         fails.
 504    */
 505   public abstract boolean addPdbFile(AlignFrameI alFrame, String sequenceId,
 506           String pdbEntryString, String pdbFile);
 507
 508   /**
 509    * adjust horizontal/vertical scroll to make the given location the top left
 510    * hand corner for the given view
 511    *
 512    * @param alf
 513    * @param topRow
 514    * @param leftHandColumn
 515    */
 516   public abstract void scrollViewToIn(AlignFrameI alf, String topRow,
 517           String leftHandColumn);
 518
 519   /**
 520    * adjust vertical scroll to make the given row the top one for given view
 521    *
 522    * @param alf
 523    * @param topRow
 524    */
 525   public abstract void scrollViewToRowIn(AlignFrameI alf, String topRow);
 526
 527   /**
 528    * adjust horizontal scroll to make the given column the left one in the given
 529    * view
 530    *
 531    * @param alf
 532    * @param leftHandColumn
 533    */
 534   public abstract void scrollViewToColumnIn(AlignFrameI alf,
 535           String leftHandColumn);
 536
 537   /**
 538    *
 539    * @return
 540    * @see jalview.appletgui.AlignFrameI#getFeatureGroups()
 541    */
 542   public abstract String getFeatureGroups();
 543
 544   /**
 545    * @param alf
 546    *          AlignFrameI to get feature groups on
 547    * @return
 548    * @see jalview.appletgui.AlignFrameI#getFeatureGroups()
 549    */
 550   public abstract String getFeatureGroupsOn(AlignFrameI alf);
 551
 552   /**
 553    * @param visible
 554    * @return
 555    * @see jalview.appletgui.AlignFrameI#getFeatureGroupsOfState(boolean)
 556    */
 557   public abstract String getFeatureGroupsOfState(boolean visible);
 558
 559   /**
 560    * @param alf
 561    *          align frame to get groups of state visible
 562    * @param visible
 563    * @return
 564    * @see jalview.appletgui.AlignFrameI#getFeatureGroupsOfState(boolean)
 565    */
 566   public abstract String getFeatureGroupsOfStateOn(AlignFrameI alf,
 567           boolean visible);
 568
 569   /**
 570    * @param groups
 571    *          tab separated list of group names
 572    * @param state
 573    *          true or false
 574    * @see jalview.appletgui.AlignFrameI#setFeatureGroupState(java.lang.String[],
 575    *      boolean)
 576    */
 577   public abstract void setFeatureGroupStateOn(AlignFrameI alf,
 578           String groups,
 579           boolean state);
 580
 581   public abstract void setFeatureGroupState(String groups, boolean state);
 582
 583   /**
 584    * List separator string
 585    *
 586    * @return the separator
 587    */
 588   public abstract String getSeparator();
 589
 590   /**
 591    * List separator string
 592    *
 593    * @param separator
 594    *          the separator to set. empty string will reset separator to default
 595    */
 596   public abstract void setSeparator(String separator);
 597
 598   /**
 599    * Retrieve fragments of a large packet of data made available by JalviewLite.
 600    *
 601    * @param messageclass
 602    * @param viewId
 603    * @return next chunk of message
 604    */
 605   public abstract String getJsMessage(String messageclass, String viewId);
 606
 607 }