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    * @return true if data parsed as features
 295    */
 296   public abstract boolean loadFeaturesFrom(AlignFrame alf, String features, boolean autoenabledisplay);
 297
 298   /**
 299    * get the sequence features in the given format (Jalview or GFF)
 300    * @param format
 301    * @return
 302    */
 303   public abstract String getFeatures(String format);
 304
 305   /**
 306    * get the sequence features in alf in the given format (Jalview or GFF)
 307    * @param alf
 308    * @param format
 309    * @return
 310    */
 311   public abstract String getFeaturesFrom(AlignFrame alf, String format);
 312
 313   /**
 314    * get current alignment's annotation as an annotation file
 315    * @return
 316    */
 317   public abstract String getAnnotation();
 318
 319   /**
 320    * get alignment view alf's annotation as an annotation file
 321    * @param alf
 322    * @return
 323    */
 324   public abstract String getAnnotationFrom(AlignFrame alf);
 325
 326   /**
 327    * create a new view and return the alignFrame instance
 328    * @return
 329    */
 330   public abstract AlignFrame newView();
 331
 332   /**
 333    * create a new view named name and return the alignFrame instance
 334    * @param name
 335    * @return
 336    */
 337   public abstract AlignFrame newView(String name);
 338
 339   /**
 340    * create a new view on alf and return the alignFrame instance
 341    * @param alf
 342    * @return
 343    */
 344   public abstract AlignFrame newViewFrom(AlignFrame alf);
 345
 346   /**
 347    * create a new view named name on alf
 348    * @param alf
 349    * @param name
 350    * @return
 351    */
 352   public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
 353
 354   /**
 355    *
 356    * @param text
 357    *          alignment file as a string
 358    * @param title
 359    *          window title
 360    * @return null or new alignment frame
 361    */
 362   public abstract AlignFrame loadAlignment(String text, String title);
 363
 364   /**
 365    * register a javascript function to handle any alignment mouseover events
 366    * @param listener name of javascript function  (called with arguments [jalview.appletgui.AlignFrame,String(sequence id),String(column in alignment), String(position in sequence)]
 367    */
 368   public abstract void setMouseoverListener(String listener);
 369
 370   /**
 371    * register a javascript function to handle mouseover events
 372    * @param af (null or specific alignframe for which events are to be listened for)
 373    * @param listener name of javascript function
 374    */
 375   public abstract void setMouseoverListener(AlignFrame af, String listener);
 376
 377   /**
 378    * 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.
 379    * @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)]
 380    */
 381   public abstract void setSelectionListener(String listener);
 382
 383   public abstract void setSelectionListener(AlignFrame af, String listener);
 384
 385   /**
 386    * register a javascript function to handle events normally routed to a Jmol structure viewer.
 387    * @param listener - javascript function (arguments are variable, see jalview.javascript.MouseOverStructureListener for full details)
 388    * @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).
 389      @see jalview.javascript.MouseOverStructureListener
 390    */
 391   public abstract void setStructureListener(String listener, String modelSet);
 392
 393   /**
 394    * remove any callback using the given listener function and associated with
 395    * the given alignFrame (or null for all callbacks)
 396    *
 397    * @param af
 398    *          (may be null)
 399    * @param listener
 400    *          (may be null)
 401    */
 402   public abstract void removeJavascriptListener(AlignFrame af,
 403           String listener);
 404
 405   /**
 406    * send a mouseover message to all the alignment windows associated with the
 407    * given residue in the pdbfile
 408    *
 409    * @param pdbResNum
 410    * @param chain
 411    * @param pdbfile
 412    */
 413   public abstract void mouseOverStructure(String pdbResNum, String chain,
 414           String pdbfile);
 415
 416   /**
 417    * bind a pdb file to a sequence in the given alignFrame.
 418    *
 419    * @param alFrame
 420    *          - null or specific alignFrame. This specifies the dataset that
 421    *          will be searched for a seuqence called sequenceId
 422    * @param sequenceId
 423    *          - sequenceId within the dataset.
 424    * @param pdbEntryString
 425    *          - the short name for the PDB file
 426    * @param pdbFile
 427    *          - pdb file - either a URL or a valid PDB file.
 428    * @return true if binding was as success TODO: consider making an exception
 429    *         structure for indicating when PDB parsing or sequenceId location
 430    *         fails.
 431    */
 432   public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
 433           String pdbEntryString, String pdbFile);
 434
 435   /**
 436    * adjust horizontal/vertical scroll to make the given location the top left hand corner for the given view
 437    *
 438    * @param alf
 439    * @param topRow
 440    * @param leftHandColumn
 441    */
 442   public abstract void scrollViewToIn(AlignFrame alf, String topRow,
 443           String leftHandColumn);
 444   /**
 445    * adjust vertical scroll to make the given row the top one for given view
 446    *
 447    * @param alf
 448    * @param topRow
 449    */
 450   public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
 451   /**
 452    * adjust horizontal scroll to make the given column the left one in the given view
 453    *
 454    * @param alf
 455    * @param leftHandColumn
 456    */
 457   public abstract void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn);
 458
 459   /**
 460    *
 461    * @return
 462    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
 463    */
 464   public abstract String getFeatureGroups();
 465
 466   /**
 467    * @param alf
 468    *          alignframe to get feature groups on
 469    * @return
 470    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
 471    */
 472   public abstract String getFeatureGroupsOn(AlignFrame alf);
 473
 474   /**
 475    * @param visible
 476    * @return
 477    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
 478    */
 479   public abstract String getFeatureGroupsOfState(boolean visible);
 480
 481   /**
 482    * @param alf
 483    *          align frame to get groups of state visible
 484    * @param visible
 485    * @return
 486    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
 487    */
 488   public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
 489           boolean visible);
 490
 491   /**
 492    * @param groups
 493    *          tab separated list of group names
 494    * @param state
 495    *          true or false
 496    * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
 497    *      boolean)
 498    */
 499   public abstract void setFeatureGroupStateOn(AlignFrame alf,
 500           String groups, boolean state);
 501
 502   public abstract void setFeatureGroupState(String groups, boolean state);
 503
 504   /**
 505    * List separator string
 506    *
 507    * @return the separator
 508    */
 509   public abstract String getSeparator();
 510
 511   /**
 512    * List separator string
 513    *
 514    * @param separator
 515    *          the separator to set. empty string will reset separator to default
 516    */
 517   public abstract void setSeparator(String separator);
 518
 519   /**
 520    * Retrieve fragments of a large packet of data made available by JalviewLite.
 521    * @param messageclass
 522    * @param viewId
 523    * @return next chunk of message
 524    */
 525   public abstract String getJsMessage(String messageclass, String viewId);
 526
 527 }