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.
 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 the make the given location the top left hand corner for given current 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   /**
 413    *
 414    * @return
 415    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
 416    */
 417   public abstract String getFeatureGroups();
 418
 419   /**
 420    * @param alf
 421    *          alignframe to get feature groups on
 422    * @return
 423    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
 424    */
 425   public abstract String getFeatureGroupsOn(AlignFrame alf);
 426
 427   /**
 428    * @param visible
 429    * @return
 430    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
 431    */
 432   public abstract String getFeatureGroupsOfState(boolean visible);
 433
 434   /**
 435    * @param alf
 436    *          align frame to get groups of state visible
 437    * @param visible
 438    * @return
 439    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
 440    */
 441   public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
 442           boolean visible);
 443
 444   /**
 445    * @param groups
 446    *          tab separated list of group names
 447    * @param state
 448    *          true or false
 449    * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
 450    *      boolean)
 451    */
 452   public abstract void setFeatureGroupStateOn(AlignFrame alf,
 453           String groups, boolean state);
 454
 455   public abstract void setFeatureGroupState(String groups, boolean state);
 456
 457   /**
 458    * List separator string
 459    *
 460    * @return the separator
 461    */
 462   public abstract String getSeparator();
 463
 464   /**
 465    * List separator string
 466    *
 467    * @param separator
 468    *          the separator to set. empty string will reset separator to default
 469    */
 470   public abstract void setSeparator(String separator);
 471
 472   /**
 473    * Retrieve fragments of a large packet of data made available by JalviewLite.
 474    * @param messageclass
 475    * @param viewId
 476    * @return next chunk of message
 477    */
 478   public abstract String getJsMessage(String messageclass, String viewId);
 479
 480 }