src/jalview/javascript/JalviewLiteJsApi.java

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