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