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