src/jalview/bin/JalviewJSApi.java

   1 package jalview.bin;
   2
   3 import java.io.IOException;
   4 import java.net.URL;
   5
   6 import jalview.api.AlignViewportI;
   7 import jalview.datamodel.ColumnSelection;
   8 import jalview.datamodel.HiddenColumns;
   9 import jalview.datamodel.PDBEntry;
  10 import jalview.datamodel.SequenceGroup;
  11 import jalview.datamodel.SequenceI;
  12 import jalview.gui.AlignFrame;
  13 import jalview.io.DataSourceType;
  14 import jalview.structure.SelectionSource;
  15 import jalview.structure.VamsasSource;
  16
  17 /**
  18  * JAL-3369 JalviewJS API BH 2019.07.17
  19  *
  20  * @author hansonr
  21  *
  22  */
  23 public interface JalviewJSApi
  24 {
  25
  26   // debug flag - controls output to standard out
  27   public static boolean debug = false;
  28
  29   /**
  30    * bind a pdb file to a sequence in the given AlignFrame.
  31    *
  32    * @param alFrame
  33    *          - null or specific AlignFrame. This specifies the dataset that
  34    *          will be searched for a seuqence called sequenceId
  35    * @param sequenceId
  36    *          - sequenceId within the dataset or null
  37    * @param pdbId
  38    *          - the four-character PDB ID
  39    * @param pdbFile
  40    *          - pdb file - either a URL or a valid PDB file or null.
  41    * @return true if binding was success
  42    */
  43   public boolean addPdbFile(AlignFrame alFrame, String sequenceId,
  44           String pdbId, String pdbFile);
  45
  46   /**
  47    * The following public methods may be called externally, eg via javascript in
  48    * an HTML page.
  49    *
  50    * <br>
  51    * <em>TODO: introduce interface for jalview.appletgui.AlignFrame</em><br>
  52    *
  53    * Most function arguments are strings, which contain serialised versions of
  54    * lists. Lists of things are separated by a separator character - either the
  55    * default or a user supplied one. Ranges and positions on an alignment or
  56    * sequence can be specified as a list, where an item containing a single
  57    * number is a single position, and an item like 1-2 specifies columns 1 and 2
  58    * as a range.
  59    */
  60
  61   // /**
  62   // * @author jimp
  63   // *
  64   // */
  65   // public interface JalviewLiteJsApi
  66   // {
  67
  68   /**
  69    * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
  70    * PFAM - see jalview.io.AppletFormatAdapter for full list);
  71    *
  72    * @param format
  73    * @return
  74    */
  75
  76   public String getAlignment(String format);
  77
  78   /**
  79    * get alignment as format with jalview start-end sequence suffix appended
  80    *
  81    * @param format
  82    * @param suffix
  83    * @return
  84    */
  85
  86   public String getAlignment(String format, String suffix);
  87
  88   /**
  89    * get alignment displayed in alf as format
  90    *
  91    * @param alf
  92    * @param format
  93    * @return
  94    */
  95   public String getAlignmentFrom(AlignFrame alf, String format);
  96
  97   /**
  98    * get alignment displayed in alf as format with or without the jalview
  99    * start-end sequence suffix appended
 100    *
 101    * @param alf
 102    * @param format
 103    * @param suffix
 104    * @return
 105    */
 106   public String getAlignmentFrom(AlignFrame alf, String format,
 107           String suffix);
 108
 109   /**
 110    * get a separator separated list of sequence IDs reflecting the order of the
 111    * current alignment
 112    *
 113    * @return
 114    */
 115
 116   public String getAlignmentOrder();
 117
 118   /**
 119    * get a separator separated list of sequence IDs reflecting the order of the
 120    * alignment in alf
 121    *
 122    * @param alf
 123    * @return
 124    */
 125   public String[] getAlignmentOrderFrom(AlignFrame alf);
 126
 127   /**
 128    * get current alignment's annotation as an annotation file
 129    *
 130    * @return
 131    */
 132
 133   public String getAnnotation();
 134
 135   /**
 136    * get alignment view alf's annotation as an annotation file
 137    *
 138    * @param alf
 139    * @return
 140    */
 141   public String getAnnotationFrom(AlignFrame alf);
 142
 143   public Object getAppletParameter(String name, boolean asString);
 144
 145   public URL getCodeBase();
 146
 147   public URL getDocumentBase();
 148
 149   /**
 150    *
 151    * @return
 152    * @see jalview.appletgui.AlignFrame#getFeatureGroups();
 153    */
 154
 155   public String[] getFeatureGroups();
 156
 157   /**
 158    * @param visible
 159    * @return
 160    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
 161    */
 162
 163   public String[] getFeatureGroupsOfState(boolean visible);
 164
 165   /**
 166    * @param alf
 167    *          align frame to get groups of state visible
 168    * @param visible
 169    * @return
 170    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
 171    */
 172   public String[] getFeatureGroupsOfStateOn(AlignFrame alf,
 173           boolean visible);
 174
 175   /**
 176    * @param alf
 177    *          AlignFrame to get feature groups on
 178    * @return
 179    * @see jalview.appletgui.AlignFrame#getFeatureGroups();
 180    */
 181   public String[] getFeatureGroupsOn(AlignFrame alf);
 182
 183   /**
 184    * get the sequence features in the given format (Jalview or GFF);
 185    *
 186    * @param format
 187    * @return
 188    */
 189
 190   public String getFeatures(String format);
 191
 192   /**
 193    * get the sequence features in alf in the given format (Jalview or GFF);
 194    *
 195    * @param alf
 196    * @param format
 197    * @return
 198    */
 199   public String getFeaturesFrom(AlignFrame alf, String format);
 200
 201   public Object getFrameForSource(VamsasSource source);
 202
 203   public String getParameter(String name);
 204
 205   /**
 206    * @return String list of selected sequence IDs, each terminated by the
 207    *         'boolean not' character (""+0x00AC); or (&#172;);
 208    */
 209
 210   public SequenceI[] getSelectedSequences();
 211
 212   /**
 213    * @param sep
 214    *          separator string or null for default
 215    * @return String list of selected sequence IDs, each terminated by given
 216    *         separator string
 217    */
 218
 219   public SequenceI[] getSelectedSequences(String sep);
 220
 221   /**
 222    * get sequences selected in current AlignFrame and return their alignment in
 223    * format 'format' either with or without suffix
 224    *
 225    * @param alf
 226    *          - where selection is
 227    * @param format
 228    *          - format of alignment file
 229    * @param suffix
 230    *          - "true" to append /start-end string to each sequence ID
 231    * @return selected sequences as flat file or empty string if there was no
 232    *         current selection
 233    */
 234
 235   public String getSelectedSequencesAsAlignment(String format,
 236           String suffix);
 237
 238   /**
 239    * get sequences selected in alf and return their alignment in format 'format'
 240    * either with or without suffix
 241    *
 242    * @param alf
 243    *          - where selection is
 244    * @param format
 245    *          - format of alignment file
 246    * @param suffix
 247    *          - "true" to append /start-end string to each sequence ID
 248    * @return selected sequences as flat file or empty string if there was no
 249    *         current selection
 250    */
 251   public String getSelectedSequencesAsAlignmentFrom(AlignFrame alf,
 252           String format, String suffix);
 253
 254   /**
 255    * @param alf
 256    *          AlignFrame containing selection
 257    * @return String list of selected sequence IDs, each terminated by current
 258    *         default separator sequence
 259    *
 260    */
 261   public SequenceI[] getSelectedSequencesFrom(AlignFrame alf);
 262
 263   // BH incompatibility here -- JalviewLite created an AlignFrame; Jalview
 264   // creates an AlignmentPanel
 265   // /**
 266   // * create a new view and return the AlignFrame instance
 267   // *
 268   // * @return
 269   // */
 270   //
 271   // public AlignFrame newView();
 272   //
 273   // /**
 274   // * create a new view named name and return the AlignFrame instance
 275   // *
 276   // * @param name
 277   // * @return
 278   // */
 279   //
 280   // public AlignFrame newView(String name);
 281   //
 282   // /**
 283   // * create a new view on alf and return the AlignFrame instance
 284   // *
 285   // * @param alf
 286   // * @return
 287   // */
 288   // public AlignFrame newViewFrom(AlignFrame alf);
 289   //
 290   // /**
 291   // * create a new view named name on alf
 292   // *
 293   // * @param alf
 294   // * @param name
 295   // * @return
 296   // */
 297   // public AlignFrame newViewFrom(AlignFrame alf, String name);
 298
 299   /**
 300    * get list of selected sequence IDs separated by given separator
 301    *
 302    * @param alf
 303    *          window containing selection
 304    * @param sep
 305    *          separator string to use - default is 'boolean not'
 306    * @return String list of selected sequence IDs, each terminated by the given
 307    *         separator
 308    */
 309   public SequenceI[] getSelectedSequencesFrom(AlignFrame alf, String sep);
 310
 311   public Object[] getSelectionForListener(SequenceGroup seqsel,
 312           ColumnSelection colsel, HiddenColumns hidden,
 313           SelectionSource source, Object alignFrame);
 314
 315   public AlignViewportI getViewport();
 316
 317   /**
 318    *
 319    * @param sequenceId
 320    *          id of sequence to highlight
 321    * @param position
 322    *          integer position [ tobe implemented or range ] on sequence
 323    * @param alignedPosition
 324    *          true/false/empty string - indicate if position is an alignment
 325    *          column or unaligned sequence position
 326    */
 327
 328   public void highlight(String sequenceId, String position,
 329           String alignedPosition);
 330
 331   /**
 332    *
 333    * @param sequenceId
 334    *          id of sequence to highlight
 335    * @param position
 336    *          integer position [ tobe implemented or range ] on sequence
 337    * @param alignedPosition
 338    *          false, blank or something else - indicate if position is an
 339    *          alignment column or unaligned sequence position
 340    */
 341   public void highlightIn(AlignFrame alf, String sequenceId,
 342           String position, String alignedPosition);
 343
 344   /**
 345    *
 346    * @param text
 347    *          alignment file as a string
 348    * @param title
 349    *          window title
 350    * @return null or new alignment frame
 351    */
 352
 353   public AlignFrame loadAlignment(String text, String title);
 354
 355   /**
 356    * add the given features or annotation to the current alignment
 357    *
 358    * @param annotation
 359    */
 360
 361   public void loadAnnotation(String annotation);
 362
 363   /**
 364    * add the given features or annotation to the given alignment view
 365    *
 366    * @param alf
 367    * @param annotation
 368    */
 369   public void loadAnnotationFrom(AlignFrame alf, String annotation);
 370
 371   /**
 372    * parse the given string as a jalview feature or GFF annotation file and
 373    * optionally enable feature display on the current AlignFrame
 374    *
 375    * @param features
 376    *          - gff or features file
 377    * @param autoenabledisplay
 378    *          - when true, feature display will be enabled if any features can
 379    *          be parsed from the string.
 380    */
 381
 382   public void loadFeatures(String features, boolean autoenabledisplay);
 383
 384   /**
 385    * parse the given string as a jalview feature or GFF annotation file and
 386    * optionally enable feature display on the given AlignFrame.
 387    *
 388    * @param alf
 389    * @param features
 390    *          - gff or features file
 391    * @param autoenabledisplay
 392    *          - when true, feature display will be enabled if any features can
 393    *          be parsed from the string.
 394    * @return true if data parsed as features
 395    */
 396   public boolean loadFeaturesFrom(AlignFrame alf, String features,
 397           boolean autoenabledisplay);
 398
 399   public boolean loadScoreFile(String sScoreFile) throws IOException;
 400
 401   public void newFeatureSettings();
 402
 403   public void newStructureView(PDBEntry pdb, SequenceI[] seqs,
 404           String[] chains, DataSourceType protocol);
 405
 406   /// in http://www.jalview.org/examples/jalviewLiteJs.html but missing here
 407
 408   // get selected sequences as alignment as format with or without start-end
 409   // suffix
 410
 411   /**
 412    * re-order the given alignment using the given array of sequence IDs
 413    *
 414    * @param alf
 415    * @param ids
 416    *          array of sequence IDs
 417    * @param undoName
 418    *          - string to use when referring to ordering action in undo buffer
 419    * @return 'true' if alignment was actually reordered. empty string if
 420    *         alignment did not contain sequences.
 421    */
 422   String orderAlignmentBy(AlignFrame alf, String[] ids, String undoName);
 423
 424   // get a string array from a list
 425
 426   /**
 427    * re-order the current alignment using the given list of sequence IDs
 428    *
 429    * @param ids
 430    *          array of sequence IDs
 431    * @param undoName
 432    *          - string to use when referring to ordering action in undo buffer
 433    * @return 'true' if alignment was actually reordered. empty string if
 434    *         alignment did not contain sequences.
 435    */
 436
 437   public String orderBy(String[] ids, String undoName);
 438
 439   /**
 440    * re-order the current alignment using the given list of sequence IDs
 441    *
 442    * @param ids
 443    *          array of sequence IDs
 444    * @param undoName
 445    *          - string to use when referring to ordering action in undo buffer
 446    * @param sep
 447    * @return 'true' if alignment was actually reordered. empty string if
 448    *         alignment did not contain sequences.
 449    */
 450
 451   // public String orderBy(String[] ids, String undoName, String sep);
 452   //
 453
 454   // public boolean getDefaultParameter(String name, boolean def);
 455
 456   public boolean parseFeaturesFile(String param, DataSourceType protocol);
 457
 458   /**
 459    * remove any callback using the given listener function and associated with
 460    * the given AlignFrame (or null for all callbacks);
 461    *
 462    * @param af
 463    *          (may be null);
 464    * @param listener
 465    *          (may be null);
 466    */
 467   public void removeSelectionListener(AlignFrame af, String listener);
 468
 469   // public void setAlignPdbStructures(boolean defaultParameter);
 470
 471   /**
 472    * adjust horizontal scroll to make the given column the left one in the given
 473    * view
 474    *
 475    * @param alf
 476    * @param leftHandColumn
 477    */
 478   public void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn);
 479
 480   /**
 481    * adjust horizontal/vertical scroll to make the given location the top left
 482    * hand corner for the given view
 483    *
 484    * @param alf
 485    * @param topRow
 486    * @param leftHandColumn
 487    */
 488   public void scrollViewToIn(AlignFrame alf, String topRow,
 489           String leftHandColumn);
 490
 491   /**
 492    * adjust vertical scroll to make the given row the top one for given view
 493    *
 494    * @param alf
 495    * @param topRow
 496    */
 497   public void scrollViewToRowIn(AlignFrame alf, String topRow);
 498
 499   /**
 500    * select regions of the currrent alignment frame
 501    *
 502    * @param sequenceIds
 503    *          String separated list of sequence ids or empty string
 504    * @param columns
 505    *          String separated list { column range or column, ..} or empty
 506    *          string
 507    */
 508
 509   public void select(String sequenceIds, String columns);
 510
 511   /**
 512    * select regions of the currrent alignment frame
 513    *
 514    * @param toselect
 515    *          String separated list { column range, seq1...seqn sequence ids }
 516    * @param sep
 517    *          separator between toselect fields
 518    */
 519
 520   public void select(String sequenceIds, String columns, String sep);
 521
 522   /**
 523    * select regions of the given alignment frame
 524    *
 525    * @param alf
 526    * @param toselect
 527    *          String separated list { column range, seq1...seqn sequence ids }
 528    * @param sep
 529    *          separator between toselect fields
 530    */
 531   public void selectIn(AlignFrame alf, String sequenceIds, String columns);
 532
 533   /**
 534    * select regions of the given alignment frame
 535    *
 536    * @param alf
 537    * @param toselect
 538    *          String separated list { column range, seq1...seqn sequence ids }
 539    * @param sep
 540    *          separator between toselect fields
 541    */
 542   public void selectIn(AlignFrame alf, String sequenceIds, String columns,
 543           String sep);
 544
 545   public void setFeatureGroupState(String groups, boolean state);
 546
 547   public void setFeatureGroupState(String[] groups, boolean state);
 548
 549   // public StructureSelectionManagerProvider
 550   // getStructureSelectionManagerProvider();
 551
 552   /**
 553    * @param groups
 554    *          tab separated list of group names
 555    * @param state
 556    *          true or false
 557    * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
 558    *      boolean);
 559    */
 560   public void setFeatureGroupStateOn(AlignFrame alf, String groups,
 561           boolean state);
 562
 563   public void setSelectionListener(AlignFrame af, String listener);
 564
 565   /**
 566    * register a javascript function to handle any alignment selection events.
 567    * Events are generated when the user completes a selection event, or when the
 568    * user deselects all selected regions.
 569    *
 570    * @param listener
 571    *          name of javascript function (called with arguments
 572    *          [jalview.appletgui.AlignFrame, String(sequence set id);,
 573    *          String(separator separated list of sequences which were
 574    *          selected);, String(separator separated list of column ranges (i.e.
 575    *          single number or hyphenated range); that were selected);]
 576    */
 577
 578   public void setSelectionListener(String listener);
 579
 580   public void updateForAnnotations();
 581
 582   // Bob's additions:
 583
 584   /**
 585    * public static method for JalviewJS API to open a PCAPanel without
 586    * necessarily using a dialog.
 587    *
 588    * @param af
 589    *          may be null
 590    * @param modelName
 591    * @return the PCAPanel, or the string "label.you_need_at_least_n_sequences"
 592    *         if number of sequences selected is inappropriate
 593    */
 594   public Object openPcaPanel(AlignFrame af, String modelName);
 595
 596   /**
 597    * Open a new Tree panel on the desktop statically. Params are standard (not
 598    * set by Groovy). No dialog is opened.
 599    *
 600    * @param af
 601    *          may be null
 602    * @param treeType
 603    * @param modelName
 604    * @return null, or the string "label.you_need_at_least_n_sequences" if number
 605    *         of sequences selected is inappropriate
 606    */
 607   public Object openTreePanel(AlignFrame af, String treeType,
 608           String modelName);
 609
 610   /**
 611    * process commandline arguments after the JavaScript application has started
 612    *
 613    * @param args
 614    * @return
 615    */
 616   public Object parseArguments(String[] args);
 617
 618   public void showStructure(AlignFrame af, String pdbID, String fileType);
 619
 620   public void showOverview();
 621
 622 }