src/jalview/bin/JalviewJSApi.java

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