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);

}