src/jalview/api/JalviewJSApi.java

   1 package jalview.api;
   2
   3 import java.net.URL;
   4
   5 import jalview.datamodel.SequenceI;
   6 import jalview.gui.AlignFrame;
   7
   8 /**
   9  * JAL-3369 JalviewJS API BH 2019.07.17
  10  *
  11  * @author hansonr
  12  *
  13  */
  14 public interface JalviewJSApi
  15 {
  16
  17   /**
  18    * bind a pdb file to a sequence in the given AlignFrame.
  19    *
  20    * @param sequenceId
  21    *          - sequenceId within the dataset or null
  22    * @param pdbId
  23    *          - the four-character PDB ID
  24    * @param pdbFile
  25    *          - pdb file - either a URL or a valid PDB file or null.
  26    * @param alFrame
  27    *          - null or specific AlignFrame. This specifies the dataset that
  28    *          will be searched for a seuqence called sequenceId
  29    *
  30    * @return true if binding was success
  31    */
  32   public boolean addPdbFile(String sequenceId, String pdbId, String pdbFile,
  33           AlignFrame alFrame);
  34
  35   /**
  36    * Get alignment as format with or without the jalview start-end sequence
  37    * suffix appended.
  38    *
  39    * @param format
  40    * @param addSuffix
  41    *          (default false)
  42    * @param alf
  43    *          (default current)
  44    *
  45    * @return
  46    */
  47   public String getAlignment(String format, boolean addSuffix,
  48           AlignFrame alf);
  49
  50   /**
  51    * Get an array of sequence IDs reflecting the order of the alignment in the
  52    * specified alignment frame
  53    *
  54    * @param alf
  55    *          (default current)
  56    * @return array of sequence IDs
  57    */
  58   public String[] getAlignmentOrder(AlignFrame alf);
  59
  60   /**
  61    * Get alignment view alf's annotation as an annotation file
  62    *
  63    * @param alf
  64    *          (default current)
  65    * @return annotation
  66    */
  67   public String getAnnotation(AlignFrame alf);
  68
  69   /**
  70    * Get the URL for the location where the code is found; typically ending in
  71    * "swingjs/j2s".
  72    *
  73    * @return web page URL
  74    */
  75   public URL getCodeBase();
  76
  77   AlignFrame getCurrentAlignFrame();
  78
  79   /**
  80    * Get the URL for the hosting web page.
  81    *
  82    * @return web page URL
  83    */
  84   public URL getDocumentBase();
  85
  86   /**
  87    * Get the array of feature groups for an alignment frame.
  88    *
  89    * @param alf
  90    *          AlignFrame to get feature groups for (default current)
  91    * @return
  92    */
  93   public String[] getFeatureGroups(AlignFrame alf);
  94
  95   /**
  96    * Get the array of feature groups for an alignment frame with a specific
  97    * on/off state.
  98    *
  99    * @param visible
 100    *          (default off)
 101    * @param alf
 102    *          align frame (default current)
 103    *
 104    * @return
 105    */
 106   public String[] getFeatureGroupsOfState(boolean visible, AlignFrame alf);
 107
 108   /**
 109    * Get the sequence features in the alignment frame in the given format
 110    * (Jalview or GFF). Two additional options can be added to the format, each
 111    * starting with a semicolon:
 112    *
 113    * ;includeNonpositional (default) or ;positionalOnly
 114    *
 115    * ;includeComplement
 116    *
 117    * @param format
 118    *          case-insensitive "Jalview" or "GFF" (default "GFF")
 119    * @param alf
 120    *          (default current)
 121    * @return formatted sequence features
 122    */
 123   public String getFeatures(String format, AlignFrame alf);
 124
 125   /**
 126    * Get an applet parameter as a string.
 127    *
 128    * @param name
 129    * @return value or null
 130    */
 131   public String getParameter(String name);
 132
 133   /**
 134    * Get an applet parameter object value.
 135    *
 136    * @param name
 137    * @return value or null
 138    */
 139   public Object getParameterAsObject(String name);
 140
 141   /**
 142    * @param alf
 143    *          AlignFrame containing selection
 144    * @return String list of selected sequence IDs, each terminated by current
 145    *         default separator sequence
 146    *
 147    */
 148   public SequenceI[] getSelectedSequences(AlignFrame alf);
 149
 150   // BH incompatibility here -- JalviewLite created an AlignFrame; Jalview
 151   // creates an AlignmentPanel
 152   // /**
 153   // * create a new view and return the AlignFrame instance
 154   // *
 155   // * @return
 156   // */
 157   //
 158   // public AlignFrame newView();
 159   //
 160   // /**
 161   // * create a new view named name and return the AlignFrame instance
 162   // *
 163   // * @param name
 164   // * @return
 165   // */
 166   //
 167   // public AlignFrame newView(String name);
 168   //
 169   // /**
 170   // * create a new view on alf and return the AlignFrame instance
 171   // *
 172   // * @param alf
 173   // * @return
 174   // */
 175   // public AlignFrame newViewFrom(AlignFrame alf);
 176   //
 177   // /**
 178   // * create a new view named name on alf
 179   // *
 180   // * @param alf
 181   // * @param name
 182   // * @return
 183   // */
 184   // public AlignFrame newViewFrom(AlignFrame alf, String name);
 185   //
 186
 187   /**
 188    * get sequences selected in alf and return their alignment in format 'format'
 189    * either with or without suffix
 190    *
 191    * @param format
 192    *          - format of alignment file
 193    * @param alf
 194    *          - where selection is
 195    * @param suffix
 196    *          - true to append /start-end string to each sequence ID
 197    *
 198    * @return selected sequences as flat file or empty string if there was no
 199    *         current selection
 200    */
 201   public String getSelectedSequencesAsAlignment(String format,
 202           boolean addSuffix, AlignFrame alf);
 203
 204   /**
 205    *
 206    * @param sequenceId
 207    *          id of sequence to highlight
 208    * @param position
 209    *          integer position [ tobe implemented or range ] on sequence
 210    * @param alignedPosition
 211    *          false, blank or something else - indicate if position is an
 212    *          alignment column or unaligned sequence position
 213    * @param alf
 214    *          alignment frame (default current)
 215    */
 216   public void highlight(String sequenceId, String position,
 217           String alignedPosition, AlignFrame alf);
 218
 219   /**
 220    *
 221    * @param data
 222    *          alignment data as a string
 223    * @param title
 224    *          window title
 225    * @param width
 226    *          desired width or 0 for default width
 227    * @param height
 228    *          desired height or 0 for default height
 229    * @return null or new alignment frame
 230    */
 231
 232   public AlignFrame loadAlignment(String data, String title, int width,
 233           int height);
 234
 235   /**
 236    * add the given features or annotation to the given alignment view
 237    *
 238    * @param annotation
 239    * @param alf
 240    *          alignment frame (default current)
 241    */
 242   public void loadAnnotation(String annotation, AlignFrame alf);
 243
 244   /**
 245    * Parse the given string as a jalview feature or GFF annotation file and
 246    * optionally enable feature display on the given AlignFrame.
 247    *
 248    * @param features
 249    *          - gff or features file
 250    * @param autoenabledisplay
 251    *          - when true, feature display will be enabled if any features can
 252    *          be parsed from the string.
 253    * @param alf
 254    *          alignment frame (default current)
 255    *
 256    * @return true if data parsed as features
 257    */
 258   public boolean loadFeatures(String features, boolean autoenabledisplay,
 259           AlignFrame alf);
 260
 261   /**
 262    * Load a score file.
 263    *
 264    * @param sScoreFile
 265    * @param alf
 266    *          alignment frame (default current)
 267    *
 268    * @return
 269    */
 270   public boolean loadScoreFile(String sScoreFile, AlignFrame alf);
 271
 272   /**
 273    * public static method for JalviewJS API to open a PCAPanel without
 274    * necessarily using a dialog.
 275    *
 276    * @param modelName
 277    * @param alf
 278    *          may be null
 279    *
 280    * @return the PCAPanel, or the string "label.you_need_at_least_n_sequences"
 281    *         if number of sequences selected is inappropriate
 282    */
 283   public Object openPcaPanel(String modelName, AlignFrame alf);
 284
 285   /**
 286    * Open a new Tree panel on the desktop statically. Params are standard (not
 287    * set by Groovy). No dialog is opened.
 288    *
 289    * @param treeType
 290    * @param modelName
 291    * @param alf
 292    *          align frame (default current)
 293    *
 294    * @return null, or the string "label.you_need_at_least_n_sequences" if number
 295    *         of sequences selected is inappropriate
 296    */
 297   public Object openTreePanel(String treeType, String modelName,
 298           AlignFrame alf);
 299
 300   /**
 301    * re-order the given alignment using the given array of sequence IDs
 302    *
 303    * @param ids
 304    *          array of sequence IDs
 305    * @param undoName
 306    *          - string to use when referring to ordering action in undo buffer
 307    * @param alf
 308    *          alignment frame (default current)
 309    *
 310    * @return 'true' if alignment was actually reordered. empty string if
 311    *         alignment did not contain sequences.
 312    */
 313   public boolean orderAlignment(String[] ids, String undoName,
 314           AlignFrame alf);
 315
 316   /**
 317    * process commandline arguments after the JavaScript application has started
 318    *
 319    * @param args
 320    * @return
 321    */
 322   public Object parseArguments(String[] args);
 323
 324   boolean parseFeaturesFile(String filename, AlignFrame alf);
 325
 326   // Bob's additions:
 327
 328   /**
 329    * remove any callback using the given listener function and associated with
 330    * the given AlignFrame (or null for all callbacks);
 331    *
 332    * @param listener
 333    *          (may be null);
 334    * @param alf
 335    *          alignment frame (default current)
 336    */
 337   public void removeSelectionListener(String listener, AlignFrame af);
 338
 339   /**
 340    * adjust horizontal/vertical scroll to make the given location the top left
 341    * hand corner for the given view
 342    *
 343    * @param topRow
 344    *          -1 for current top row
 345    * @param leftHandColumn
 346    *          -1 for current left-hand column
 347    * @param alf
 348    *          alignment frame (default current)
 349    */
 350   public void scrollViewTo(int topRow, int leftHandColumn, AlignFrame alf);
 351   /**
 352    * select regions of the given alignment frame
 353    *
 354    * @param alf
 355    *          alignment frame (default current)
 356    * @param toselect
 357    *          String separated list { column range, seq1...seqn sequence ids }
 358    * @param sep
 359    *          separator between toselect fields
 360    */
 361   public void select(String[] sequenceIds, String[] columns,
 362           AlignFrame alf);
 363
 364   /**
 365    * Set the state (visible or not) of the selected feature groups.
 366    *
 367    * @param groups
 368    * @param state
 369    * @param alf
 370    *          (default current)
 371    */
 372   public void setFeatureGroupState(String[] groups, boolean state,
 373           AlignFrame alf);
 374
 375   /**
 376    * Register a JavaScript function to handle alignment selection events. Events
 377    * are generated when the user completes a selection event, or when the user
 378    * deselects all selected regions. The method is called back with the
 379    * following arguments:
 380    *
 381    * the appletID (such as "Jalview1")
 382    *
 383    * the source alignment frame
 384    *
 385    * the SelectionSource object (for example, an AlignViewport)
 386    *
 387    * the sequence set ID
 388    *
 389    * an array of sequence IDs
 390    *
 391    * an array of columns (single number or hyphenated range)
 392    *
 393    * @param listener
 394    *          name of JavaScript function to be called
 395    *
 396    * @param alf
 397    *          alignment frame (default ALL)
 398    */
 399   public void setSelectionListener(String listener, AlignFrame alf);
 400
 401   public void showOverview();
 402
 403   /**
 404    *
 405    * @param pdbID
 406    * @param fileType
 407    * @param alf
 408    *          align frame (default current)
 409    */
 410   public void showStructure(String pdbID, String fileType, AlignFrame alf);
 411
 412 }