src/jalview/bin/JalviewJSApi.java

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