X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fjalview%2Fapi%2FJalviewJSApi.java;fp=src%2Fjalview%2Fapi%2FJalviewJSApi.java;h=895fd154413d9c49ba62ad832da19ff7ae0c51fd;hb=586ade46bdcd05ff028a1cff82c3c527326d28ec;hp=0000000000000000000000000000000000000000;hpb=adcef27f5747b4e70e89a56c3735bc3afb8ce9bf;p=jalview.git

diff --git a/src/jalview/api/JalviewJSApi.java b/src/jalview/api/JalviewJSApi.java
new file mode 100644
index 0000000..895fd15
--- /dev/null
+++ b/src/jalview/api/JalviewJSApi.java
@@ -0,0 +1,412 @@
+package jalview.api;
+
+import java.net.URL;
+
+import jalview.datamodel.SequenceI;
+import jalview.gui.AlignFrame;
+
+/**
+ * JAL-3369 JalviewJS API BH 2019.07.17
+ * 
+ * @author hansonr
+ *
+ */
+public interface JalviewJSApi
+{
+
+  /**
+   * bind a pdb file to a sequence in the given AlignFrame.
+   * 
+   * @param sequenceId
+   *          - sequenceId within the dataset or null
+   * @param pdbId
+   *          - the four-character PDB ID
+   * @param pdbFile
+   *          - pdb file - either a URL or a valid PDB file or null.
+   * @param alFrame
+   *          - null or specific AlignFrame. This specifies the dataset that
+   *          will be searched for a seuqence called sequenceId
+   * 
+   * @return true if binding was success
+   */
+  public boolean addPdbFile(String sequenceId, String pdbId, String pdbFile,
+          AlignFrame alFrame);
+
+  /**
+   * Get alignment as format with or without the jalview start-end sequence
+   * suffix appended.
+   * 
+   * @param format
+   * @param addSuffix
+   *          (default false)
+   * @param alf
+   *          (default current)
+   * 
+   * @return
+   */
+  public String getAlignment(String format, boolean addSuffix,
+          AlignFrame alf);
+
+  /**
+   * Get an array of sequence IDs reflecting the order of the alignment in the
+   * specified alignment frame
+   * 
+   * @param alf
+   *          (default current)
+   * @return array of sequence IDs
+   */
+  public String[] getAlignmentOrder(AlignFrame alf);
+
+  /**
+   * Get alignment view alf's annotation as an annotation file
+   * 
+   * @param alf
+   *          (default current)
+   * @return annotation
+   */
+  public String getAnnotation(AlignFrame alf);
+
+  /**
+   * Get the URL for the location where the code is found; typically ending in
+   * "swingjs/j2s".
+   * 
+   * @return web page URL
+   */
+  public URL getCodeBase();
+
+  AlignFrame getCurrentAlignFrame();
+
+  /**
+   * Get the URL for the hosting web page.
+   * 
+   * @return web page URL
+   */
+  public URL getDocumentBase();
+
+  /**
+   * Get the array of feature groups for an alignment frame.
+   * 
+   * @param alf
+   *          AlignFrame to get feature groups for (default current)
+   * @return
+   */
+  public String[] getFeatureGroups(AlignFrame alf);
+
+  /**
+   * Get the array of feature groups for an alignment frame with a specific
+   * on/off state.
+   * 
+   * @param visible
+   *          (default off)
+   * @param alf
+   *          align frame (default current)
+   * 
+   * @return
+   */
+  public String[] getFeatureGroupsOfState(boolean visible, AlignFrame alf);
+
+  /**
+   * Get the sequence features in the alignment frame in the given format
+   * (Jalview or GFF). Two additional options can be added to the format, each
+   * starting with a semicolon:
+   * 
+   * ;includeNonpositional (default) or ;positionalOnly
+   * 
+   * ;includeComplement
+   * 
+   * @param format
+   *          case-insensitive "Jalview" or "GFF" (default "GFF")
+   * @param alf
+   *          (default current)
+   * @return formatted sequence features
+   */
+  public String getFeatures(String format, AlignFrame alf);
+
+  /**
+   * Get an applet parameter as a string.
+   * 
+   * @param name
+   * @return value or null
+   */
+  public String getParameter(String name);
+
+  /**
+   * Get an applet parameter object value.
+   * 
+   * @param name
+   * @return value or null
+   */
+  public Object getParameterAsObject(String name);
+
+  /**
+   * @param alf
+   *          AlignFrame containing selection
+   * @return String list of selected sequence IDs, each terminated by current
+   *         default separator sequence
+   * 
+   */
+  public SequenceI[] getSelectedSequences(AlignFrame alf);
+
+  // BH incompatibility here -- JalviewLite created an AlignFrame; Jalview
+  // creates an AlignmentPanel
+  // /**
+  // * create a new view and return the AlignFrame instance
+  // *
+  // * @return
+  // */
+  //
+  // public AlignFrame newView();
+  //
+  // /**
+  // * create a new view named name and return the AlignFrame instance
+  // *
+  // * @param name
+  // * @return
+  // */
+  //
+  // public AlignFrame newView(String name);
+  //
+  // /**
+  // * create a new view on alf and return the AlignFrame instance
+  // *
+  // * @param alf
+  // * @return
+  // */
+  // public AlignFrame newViewFrom(AlignFrame alf);
+  //
+  // /**
+  // * create a new view named name on alf
+  // *
+  // * @param alf
+  // * @param name
+  // * @return
+  // */
+  // public AlignFrame newViewFrom(AlignFrame alf, String name);
+  //
+
+  /**
+   * get sequences selected in alf and return their alignment in format 'format'
+   * either with or without suffix
+   * 
+   * @param format
+   *          - format of alignment file
+   * @param alf
+   *          - where selection is
+   * @param suffix
+   *          - true to append /start-end string to each sequence ID
+   * 
+   * @return selected sequences as flat file or empty string if there was no
+   *         current selection
+   */
+  public String getSelectedSequencesAsAlignment(String format,
+          boolean addSuffix, AlignFrame alf);
+
+  /**
+   * 
+   * @param sequenceId
+   *          id of sequence to highlight
+   * @param position
+   *          integer position [ tobe implemented or range ] on sequence
+   * @param alignedPosition
+   *          false, blank or something else - indicate if position is an
+   *          alignment column or unaligned sequence position
+   * @param alf
+   *          alignment frame (default current)
+   */
+  public void highlight(String sequenceId, String position,
+          String alignedPosition, AlignFrame alf);
+
+  /**
+   * 
+   * @param data
+   *          alignment data as a string
+   * @param title
+   *          window title
+   * @param width
+   *          desired width or 0 for default width
+   * @param height
+   *          desired height or 0 for default height
+   * @return null or new alignment frame
+   */
+
+  public AlignFrame loadAlignment(String data, String title, int width,
+          int height);
+
+  /**
+   * add the given features or annotation to the given alignment view
+   * 
+   * @param annotation
+   * @param alf
+   *          alignment frame (default current)
+   */
+  public void loadAnnotation(String annotation, AlignFrame alf);
+
+  /**
+   * Parse the given string as a jalview feature or GFF annotation file and
+   * optionally enable feature display on the given AlignFrame.
+   * 
+   * @param features
+   *          - gff or features file
+   * @param autoenabledisplay
+   *          - when true, feature display will be enabled if any features can
+   *          be parsed from the string.
+   * @param alf
+   *          alignment frame (default current)
+   * 
+   * @return true if data parsed as features
+   */
+  public boolean loadFeatures(String features, boolean autoenabledisplay,
+          AlignFrame alf);
+
+  /**
+   * Load a score file.
+   * 
+   * @param sScoreFile
+   * @param alf
+   *          alignment frame (default current)
+   * 
+   * @return
+   */
+  public boolean loadScoreFile(String sScoreFile, AlignFrame alf);
+
+  /**
+   * public static method for JalviewJS API to open a PCAPanel without
+   * necessarily using a dialog.
+   * 
+   * @param modelName
+   * @param alf
+   *          may be null
+   * 
+   * @return the PCAPanel, or the string "label.you_need_at_least_n_sequences"
+   *         if number of sequences selected is inappropriate
+   */
+  public Object openPcaPanel(String modelName, AlignFrame alf);
+
+  /**
+   * Open a new Tree panel on the desktop statically. Params are standard (not
+   * set by Groovy). No dialog is opened.
+   * 
+   * @param treeType
+   * @param modelName
+   * @param alf
+   *          align frame (default current)
+   * 
+   * @return null, or the string "label.you_need_at_least_n_sequences" if number
+   *         of sequences selected is inappropriate
+   */
+  public Object openTreePanel(String treeType, String modelName,
+          AlignFrame alf);
+
+  /**
+   * re-order the given alignment using the given array of sequence IDs
+   * 
+   * @param ids
+   *          array of sequence IDs
+   * @param undoName
+   *          - string to use when referring to ordering action in undo buffer
+   * @param alf
+   *          alignment frame (default current)
+   * 
+   * @return 'true' if alignment was actually reordered. empty string if
+   *         alignment did not contain sequences.
+   */
+  public boolean orderAlignment(String[] ids, String undoName,
+          AlignFrame alf);
+
+  /**
+   * process commandline arguments after the JavaScript application has started
+   *
+   * @param args
+   * @return
+   */
+  public Object parseArguments(String[] args);
+
+  boolean parseFeaturesFile(String filename, AlignFrame alf);
+
+  // Bob's additions:
+
+  /**
+   * remove any callback using the given listener function and associated with
+   * the given AlignFrame (or null for all callbacks);
+   * 
+   * @param listener
+   *          (may be null);
+   * @param alf
+   *          alignment frame (default current)
+   */
+  public void removeSelectionListener(String listener, AlignFrame af);
+
+  /**
+   * adjust horizontal/vertical scroll to make the given location the top left
+   * hand corner for the given view
+   * 
+   * @param topRow
+   *          -1 for current top row
+   * @param leftHandColumn
+   *          -1 for current left-hand column
+   * @param alf
+   *          alignment frame (default current)
+   */
+  public void scrollViewTo(int topRow, int leftHandColumn, AlignFrame alf);
+  /**
+   * select regions of the given alignment frame
+   * 
+   * @param alf
+   *          alignment frame (default current)
+   * @param toselect
+   *          String separated list { column range, seq1...seqn sequence ids }
+   * @param sep
+   *          separator between toselect fields
+   */
+  public void select(String[] sequenceIds, String[] columns,
+          AlignFrame alf);
+  
+  /**
+   * Set the state (visible or not) of the selected feature groups.
+   * 
+   * @param groups
+   * @param state
+   * @param alf
+   *          (default current)
+   */
+  public void setFeatureGroupState(String[] groups, boolean state,
+          AlignFrame alf);
+
+  /**
+   * Register a JavaScript function to handle alignment selection events. Events
+   * are generated when the user completes a selection event, or when the user
+   * deselects all selected regions. The method is called back with the
+   * following arguments:
+   * 
+   * the appletID (such as "Jalview1")
+   * 
+   * the source alignment frame
+   * 
+   * the SelectionSource object (for example, an AlignViewport)
+   * 
+   * the sequence set ID
+   * 
+   * an array of sequence IDs
+   * 
+   * an array of columns (single number or hyphenated range)
+   * 
+   * @param listener
+   *          name of JavaScript function to be called
+   * 
+   * @param alf
+   *          alignment frame (default ALL)
+   */
+  public void setSelectionListener(String listener, AlignFrame alf);
+
+  public void showOverview();
+
+  /**
+   * 
+   * @param pdbID
+   * @param fileType
+   * @param alf
+   *          align frame (default current)
+   */
+  public void showStructure(String pdbID, String fileType, AlignFrame alf);
+
+}