--- /dev/null
+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);
+
+}