src/jalview/javascript/JalviewLiteJsApi.java

   1 package jalview.javascript;
   2
   3 import jalview.appletgui.AlignFrame;
   4
   5 /**
   6  * The following public methods may be called
   7  * externally, eg via javascript in an HTML page.
   8  *
   9  * <br><em>TODO: introduce abstract interface for jalview.appletgui.AlignFrame</em><br>
  10  *
  11  * Most function arguments are strings, which contain serialised versions of lists.
  12  * Lists of things are separated by a separator character - either the default or a user supplied one.
  13  * 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.
  14  */
  15
  16 /**
  17  * @author jimp
  18  *
  19  */
  20 public interface JalviewLiteJsApi
  21 {
  22
  23   /**
  24    * @return String list of selected sequence IDs, each terminated by the
  25    *         'boolean not' character (""+0x00AC) or (&#172;)
  26    */
  27   public abstract String getSelectedSequences();
  28
  29   /**
  30    * @param sep
  31    *          separator string or null for default
  32    * @return String list of selected sequence IDs, each terminated by given
  33    *         separator string
  34    */
  35   public abstract String getSelectedSequences(String sep);
  36
  37   /**
  38    * @param alf
  39    *          alignframe containing selection
  40    * @return String list of selected sequence IDs, each terminated by current
  41    *         default separator sequence
  42    *
  43    */
  44   public abstract String getSelectedSequencesFrom(AlignFrame alf);
  45
  46   /**
  47    * get list of selected sequence IDs separated by given separator
  48    *
  49    * @param alf
  50    *          window containing selection
  51    * @param sep
  52    *          separator string to use - default is 'boolean not'
  53    * @return String list of selected sequence IDs, each terminated by the given
  54    *         separator
  55    */
  56   public abstract String getSelectedSequencesFrom(AlignFrame alf, String sep);
  57
  58   /**
  59    *
  60    * @param sequenceId
  61    *          id of sequence to highlight
  62    * @param position
  63    *          integer position [ tobe implemented or range ] on sequence
  64    * @param alignedPosition
  65    *          true/false/empty string - indicate if position is an alignment
  66    *          column or unaligned sequence position
  67    */
  68   public abstract void highlight(String sequenceId, String position,
  69           String alignedPosition);
  70
  71   /**
  72    *
  73    * @param sequenceId
  74    *          id of sequence to highlight
  75    * @param position
  76    *          integer position [ tobe implemented or range ] on sequence
  77    * @param alignedPosition
  78    *          false, blank or something else - indicate if position is an
  79    *          alignment column or unaligned sequence position
  80    */
  81   public abstract void highlightIn(AlignFrame alf, String sequenceId,
  82           String position, String alignedPosition);
  83
  84   /**
  85    * select regions of the currrent alignment frame
  86    *
  87    * @param sequenceIds
  88    *          String separated list of sequence ids or empty string
  89    * @param columns
  90    *          String separated list { column range or column, ..} or empty
  91    *          string
  92    */
  93   public abstract void select(String sequenceIds, String columns);
  94
  95   /**
  96    * select regions of the currrent alignment frame
  97    *
  98    * @param toselect
  99    *          String separated list { column range, seq1...seqn sequence ids }
 100    * @param sep
 101    *          separator between toselect fields
 102    */
 103   public abstract void select(String sequenceIds, String columns, String sep);
 104
 105   /**
 106    * select regions of the given alignment frame
 107    *
 108    * @param alf
 109    * @param toselect
 110    *          String separated list { column range, seq1...seqn sequence ids }
 111    * @param sep
 112    *          separator between toselect fields
 113    */
 114   public abstract void selectIn(AlignFrame alf, String sequenceIds,
 115           String columns);
 116
 117   /**
 118    * select regions of the given alignment frame
 119    *
 120    * @param alf
 121    * @param toselect
 122    *          String separated list { column range, seq1...seqn sequence ids }
 123    * @param sep
 124    *          separator between toselect fields
 125    */
 126   public abstract void selectIn(AlignFrame alf, String sequenceIds,
 127           String columns, String sep);
 128
 129   /**
 130    * get sequences selected in current alignFrame and return their alignment in
 131    * format 'format' either with or without suffix
 132    *
 133    * @param alf
 134    *          - where selection is
 135    * @param format
 136    *          - format of alignment file
 137    * @param suffix
 138    *          - "true" to append /start-end string to each sequence ID
 139    * @return selected sequences as flat file or empty string if there was no
 140    *         current selection
 141    */
 142   public abstract String getSelectedSequencesAsAlignment(String format,
 143           String suffix);
 144
 145   /**
 146    * get sequences selected in alf and return their alignment in format 'format'
 147    * either with or without suffix
 148    *
 149    * @param alf
 150    *          - where selection is
 151    * @param format
 152    *          - format of alignment file
 153    * @param suffix
 154    *          - "true" to append /start-end string to each sequence ID
 155    * @return selected sequences as flat file or empty string if there was no
 156    *         current selection
 157    */
 158   public abstract String getSelectedSequencesAsAlignmentFrom(
 159           AlignFrame alf, String format, String suffix);
 160
 161   /**
 162    * get a separator separated list of sequence IDs reflecting the order of the current alignment
 163    * @return
 164    */
 165   public abstract String getAlignmentOrder();
 166   /**
 167    * get a separator separated list of sequence IDs reflecting the order of the alignment in alf
 168    *
 169    * @param alf
 170    * @return
 171    */
 172   public abstract String getAlignmentOrderFrom(AlignFrame alf);
 173
 174   /**
 175    * get a sep separated list of sequence IDs reflecting the order of the alignment in alf
 176    *
 177    * @param alf
 178    * @param sep - separator to use
 179    * @return
 180    */
 181   public abstract String getAlignmentOrderFrom(AlignFrame alf, String sep);
 182   /**
 183    * re-order the current alignment using the given list of sequence IDs
 184    * @param order - sep separated list
 185    * @param undoName - string to use when referring to ordering action in undo buffer
 186    * @return 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
 187    */
 188   public abstract String orderBy(String order, String undoName);
 189
 190   /**
 191    * re-order the current alignment using the given list of sequence IDs
 192    * separated by sep
 193    *
 194    * @param order
 195    *          - sep separated list
 196    * @param undoName
 197    *          - string to use when referring to ordering action in undo buffer
 198    * @param sep
 199    * @return 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
 200    */
 201   public abstract String orderBy(String order, String undoName, String sep);
 202
 203   /**
 204    * re-order the given alignment using the given list of sequence IDs
 205    * separated by sep
 206    *
 207    * @param alf
 208    * @param order
 209    *          - sep separated list
 210    * @param undoName
 211    *          - string to use when referring to ordering action in undo buffer
 212    * @param sep
 213    * @return 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
 214    */
 215   public abstract String orderAlignmentBy(AlignFrame alf, String order,
 216           String undoName, String sep);
 217
 218   /**
 219    * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP, PFAM - see jalview.io.AppletFormatAdapter for full list)
 220    * @param format
 221    * @return
 222    */
 223   public abstract String getAlignment(String format);
 224
 225   /**
 226    * get alignment displayed in alf as format
 227    * @param alf
 228    * @param format
 229    * @return
 230    */
 231   public abstract String getAlignmentFrom(AlignFrame alf, String format);
 232
 233   /**
 234    * get alignment as format with jalview start-end sequence suffix appended
 235    * @param format
 236    * @param suffix
 237    * @return
 238    */
 239   public abstract String getAlignment(String format, String suffix);
 240
 241   /**
 242    * get alignment displayed in alf as format
 243    *  with or without the jalview start-end sequence suffix appended
 244    * @param alf
 245    * @param format
 246    * @param suffix
 247    * @return
 248    */
 249   public abstract String getAlignmentFrom(AlignFrame alf, String format,
 250           String suffix);
 251
 252   /**
 253    * add the given features or annotation to the current alignment
 254    * @param annotation
 255    */
 256   public abstract void loadAnnotation(String annotation);
 257
 258   /**
 259    * add the given features or annotation to the given alignment view
 260    * @param alf
 261    * @param annotation
 262    */
 263   public abstract void loadAnnotationFrom(AlignFrame alf, String annotation);
 264
 265   /**
 266    * get the sequence features in the given format (Jalview or GFF)
 267    * @param format
 268    * @return
 269    */
 270   public abstract String getFeatures(String format);
 271
 272   /**
 273    * get the sequence features in alf in the given format (Jalview or GFF)
 274    * @param alf
 275    * @param format
 276    * @return
 277    */
 278   public abstract String getFeaturesFrom(AlignFrame alf, String format);
 279
 280   /**
 281    * get current alignment's annotation as an annotation file
 282    * @return
 283    */
 284   public abstract String getAnnotation();
 285
 286   /**
 287    * get alignment view alf's annotation as an annotation file
 288    * @param alf
 289    * @return
 290    */
 291   public abstract String getAnnotationFrom(AlignFrame alf);
 292
 293   /**
 294    * create a new view and return the alignFrame instance
 295    * @return
 296    */
 297   public abstract AlignFrame newView();
 298
 299   /**
 300    * create a new view named name and return the alignFrame instance
 301    * @param name
 302    * @return
 303    */
 304   public abstract AlignFrame newView(String name);
 305
 306   /**
 307    * create a new view on alf and return the alignFrame instance
 308    * @param alf
 309    * @return
 310    */
 311   public abstract AlignFrame newViewFrom(AlignFrame alf);
 312
 313   /**
 314    * create a new view named name on alf
 315    * @param alf
 316    * @param name
 317    * @return
 318    */
 319   public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
 320
 321   /**
 322    *
 323    * @param text
 324    *          alignment file as a string
 325    * @param title
 326    *          window title
 327    * @return null or new alignment frame
 328    */
 329   public abstract AlignFrame loadAlignment(String text, String title);
 330
 331   /**
 332    * register a javascript function to handle any alignment mouseover events
 333    * @param listener name of javascript function  (called with arguments [jalview.appletgui.AlignFrame,String(sequence id),String(column in alignment), String(position in sequence)]
 334    */
 335   public abstract void setMouseoverListener(String listener);
 336
 337   /**
 338    * register a javascript function to handle mouseover events
 339    * @param af (null or specific alignframe for which events are to be listened for)
 340    * @param listener name of javascript function
 341    */
 342   public abstract void setMouseoverListener(AlignFrame af, String listener);
 343
 344   /**
 345    * 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.
 346    * @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)]
 347    */
 348   public abstract void setSelectionListener(String listener);
 349
 350   public abstract void setSelectionListener(AlignFrame af, String listener);
 351
 352   /**
 353    * register a javascript function to handle events normally routed to a Jmol structure viewer.
 354    * @param listener - javascript function (arguments are variable, see jalview.javascript.MouseOverStructureListener for full details)
 355    * @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).
 356      @see jalview.javascript.MouseOverStructureListener
 357    */
 358   public abstract void setStructureListener(String listener, String modelSet);
 359
 360   /**
 361    * remove any callback using the given listener function and associated with
 362    * the given alignFrame (or null for all callbacks)
 363    *
 364    * @param af
 365    *          (may be null)
 366    * @param listener
 367    *          (may be null)
 368    */
 369   public abstract void removeJavascriptListener(AlignFrame af,
 370           String listener);
 371
 372   /**
 373    * send a mouseover message to all the alignment windows associated with the
 374    * given residue in the pdbfile
 375    *
 376    * @param pdbResNum
 377    * @param chain
 378    * @param pdbfile
 379    */
 380   public abstract void mouseOverStructure(String pdbResNum, String chain,
 381           String pdbfile);
 382
 383   /**
 384    * bind a pdb file to a sequence in the given alignFrame.
 385    *
 386    * @param alFrame
 387    *          - null or specific alignFrame. This specifies the dataset that
 388    *          will be searched for a seuqence called sequenceId
 389    * @param sequenceId
 390    *          - sequenceId within the dataset.
 391    * @param pdbEntryString
 392    *          - the short name for the PDB file
 393    * @param pdbFile
 394    *          - pdb file - either a URL or a valid PDB file.
 395    * @return true if binding was as success TODO: consider making an exception
 396    *         structure for indicating when PDB parsing or sequenceId location
 397    *         fails.
 398    */
 399   public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
 400           String pdbEntryString, String pdbFile);
 401
 402   /**
 403    * adjust horizontal/vertical scroll to make the given location the top left hand corner for the given view
 404    *
 405    * @param alf
 406    * @param topRow
 407    * @param leftHandColumn
 408    */
 409   public abstract void scrollViewToIn(AlignFrame alf, String topRow,
 410           String leftHandColumn);
 411   /**
 412    * adjust vertical scroll to make the given row the top one for given view
 413    *
 414    * @param alf
 415    * @param topRow
 416    */
 417   public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
 418   /**
 419    * adjust horizontal scroll to make the given column the left one in the given view
 420    *
 421    * @param alf
 422    * @param leftHandColumn
 423    */
 424   public abstract void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn);
 425
 426   /**
 427    *
 428    * @return
 429    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
 430    */
 431   public abstract String getFeatureGroups();
 432
 433   /**
 434    * @param alf
 435    *          alignframe to get feature groups on
 436    * @return
 437    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
 438    */
 439   public abstract String getFeatureGroupsOn(AlignFrame alf);
 440
 441   /**
 442    * @param visible
 443    * @return
 444    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
 445    */
 446   public abstract String getFeatureGroupsOfState(boolean visible);
 447
 448   /**
 449    * @param alf
 450    *          align frame to get groups of state visible
 451    * @param visible
 452    * @return
 453    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
 454    */
 455   public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
 456           boolean visible);
 457
 458   /**
 459    * @param groups
 460    *          tab separated list of group names
 461    * @param state
 462    *          true or false
 463    * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
 464    *      boolean)
 465    */
 466   public abstract void setFeatureGroupStateOn(AlignFrame alf,
 467           String groups, boolean state);
 468
 469   public abstract void setFeatureGroupState(String groups, boolean state);
 470
 471   /**
 472    * List separator string
 473    *
 474    * @return the separator
 475    */
 476   public abstract String getSeparator();
 477
 478   /**
 479    * List separator string
 480    *
 481    * @param separator
 482    *          the separator to set. empty string will reset separator to default
 483    */
 484   public abstract void setSeparator(String separator);
 485
 486   /**
 487    * Retrieve fragments of a large packet of data made available by JalviewLite.
 488    * @param messageclass
 489    * @param viewId
 490    * @return next chunk of message
 491    */
 492   public abstract String getJsMessage(String messageclass, String viewId);
 493
 494 }