-package jalview.bin;
-
-import java.io.IOException;
-import java.net.URL;
-
-import jalview.api.AlignViewportI;
-import jalview.datamodel.ColumnSelection;
-import jalview.datamodel.HiddenColumns;
-import jalview.datamodel.PDBEntry;
-import jalview.datamodel.SequenceGroup;
-import jalview.datamodel.SequenceI;
-import jalview.gui.AlignFrame;
-import jalview.io.DataSourceType;
-import jalview.structure.SelectionSource;
-import jalview.structure.VamsasSource;
-
-/**
- * JAL-3369 JalviewJS API BH 2019.07.17
- *
- * @author hansonr
- *
- */
-public interface JalviewJSApi
-{
-
- // debug flag - controls output to standard out
- public static boolean debug = false;
-
- /**
- * bind a pdb file to a sequence in the given AlignFrame.
- *
- * @param alFrame
- * - null or specific AlignFrame. This specifies the dataset that
- * will be searched for a seuqence called sequenceId
- * @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.
- * @return true if binding was success
- */
- public boolean addPdbFile(AlignFrame alFrame, String sequenceId,
- String pdbId, String pdbFile);
-
- /**
- * The following public methods may be called externally, eg via javascript in
- * an HTML page.
- *
- * <br>
- * <em>TODO: introduce interface for jalview.appletgui.AlignFrame</em><br>
- *
- * Most function arguments are strings, which contain serialised versions of
- * lists. Lists of things are separated by a separator character - either the
- * default or a user supplied one. Ranges and positions on an alignment or
- * sequence can be specified as a list, where an item containing a single
- * number is a single position, and an item like 1-2 specifies columns 1 and 2
- * as a range.
- */
-
- // /**
- // * @author jimp
- // *
- // */
- // public interface JalviewLiteJsApi
- // {
-
- /**
- * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
- * PFAM - see jalview.io.AppletFormatAdapter for full list);
- *
- * @param format
- * @return
- */
-
- public String getAlignment(String format);
-
- /**
- * get alignment as format with jalview start-end sequence suffix appended
- *
- * @param format
- * @param suffix
- * @return
- */
-
- public String getAlignment(String format, String suffix);
-
- /**
- * get alignment displayed in alf as format
- *
- * @param alf
- * @param format
- * @return
- */
- public String getAlignmentFrom(AlignFrame alf, String format);
-
- /**
- * get alignment displayed in alf as format with or without the jalview
- * start-end sequence suffix appended
- *
- * @param alf
- * @param format
- * @param suffix
- * @return
- */
- public String getAlignmentFrom(AlignFrame alf, String format,
- String suffix);
-
- /**
- * get a separator separated list of sequence IDs reflecting the order of the
- * current alignment
- *
- * @return
- */
-
- public String getAlignmentOrder();
-
- /**
- * get a separator separated list of sequence IDs reflecting the order of the
- * alignment in alf
- *
- * @param alf
- * @return
- */
- public String[] getAlignmentOrderFrom(AlignFrame alf);
-
- /**
- * get current alignment's annotation as an annotation file
- *
- * @return
- */
-
- public String getAnnotation();
-
- /**
- * get alignment view alf's annotation as an annotation file
- *
- * @param alf
- * @return
- */
- public String getAnnotationFrom(AlignFrame alf);
-
- public Object getAppletParameter(String name, boolean asString);
-
- public URL getCodeBase();
-
- public URL getDocumentBase();
-
- /**
- *
- * @return
- * @see jalview.appletgui.AlignFrame#getFeatureGroups();
- */
-
- public String[] getFeatureGroups();
-
- /**
- * @param visible
- * @return
- * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
- */
-
- public String[] getFeatureGroupsOfState(boolean visible);
-
- /**
- * @param alf
- * align frame to get groups of state visible
- * @param visible
- * @return
- * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
- */
- public String[] getFeatureGroupsOfStateOn(AlignFrame alf,
- boolean visible);
-
- /**
- * @param alf
- * AlignFrame to get feature groups on
- * @return
- * @see jalview.appletgui.AlignFrame#getFeatureGroups();
- */
- public String[] getFeatureGroupsOn(AlignFrame alf);
-
- /**
- * get the sequence features in the given format (Jalview or GFF);
- *
- * @param format
- * @return
- */
-
- public String getFeatures(String format);
-
- /**
- * get the sequence features in alf in the given format (Jalview or GFF);
- *
- * @param alf
- * @param format
- * @return
- */
- public String getFeaturesFrom(AlignFrame alf, String format);
-
- public Object getFrameForSource(VamsasSource source);
-
- public String getParameter(String name);
-
- /**
- * @return String list of selected sequence IDs, each terminated by the
- * 'boolean not' character (""+0x00AC); or (¬);
- */
-
- public SequenceI[] getSelectedSequences();
-
- /**
- * @param sep
- * separator string or null for default
- * @return String list of selected sequence IDs, each terminated by given
- * separator string
- */
-
- public SequenceI[] getSelectedSequences(String sep);
-
- /**
- * get sequences selected in current AlignFrame and return their alignment in
- * format 'format' either with or without suffix
- *
- * @param alf
- * - where selection is
- * @param format
- * - format of alignment file
- * @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,
- String suffix);
-
- /**
- * get sequences selected in alf and return their alignment in format 'format'
- * either with or without suffix
- *
- * @param alf
- * - where selection is
- * @param format
- * - format of alignment file
- * @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 getSelectedSequencesAsAlignmentFrom(AlignFrame alf,
- String format, String suffix);
-
- /**
- * @param alf
- * AlignFrame containing selection
- * @return String list of selected sequence IDs, each terminated by current
- * default separator sequence
- *
- */
- public SequenceI[] getSelectedSequencesFrom(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 list of selected sequence IDs separated by given separator
- *
- * @param alf
- * window containing selection
- * @param sep
- * separator string to use - default is 'boolean not'
- * @return String list of selected sequence IDs, each terminated by the given
- * separator
- */
- public SequenceI[] getSelectedSequencesFrom(AlignFrame alf, String sep);
-
- public Object[] getSelectionForListener(SequenceGroup seqsel,
- ColumnSelection colsel, HiddenColumns hidden,
- SelectionSource source, Object alignFrame);
-
- public AlignViewportI getViewport();
-
- /**
- *
- * @param sequenceId
- * id of sequence to highlight
- * @param position
- * integer position [ tobe implemented or range ] on sequence
- * @param alignedPosition
- * true/false/empty string - indicate if position is an alignment
- * column or unaligned sequence position
- */
-
- public void highlight(String sequenceId, String position,
- String alignedPosition);
-
- /**
- *
- * @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
- */
- public void highlightIn(AlignFrame alf, String sequenceId,
- String position, String alignedPosition);
-
- /**
- *
- * @param text
- * alignment file as a string
- * @param title
- * window title
- * @return null or new alignment frame
- */
-
- public AlignFrame loadAlignment(String text, String title);
-
- /**
- * add the given features or annotation to the current alignment
- *
- * @param annotation
- */
-
- public void loadAnnotation(String annotation);
-
- /**
- * add the given features or annotation to the given alignment view
- *
- * @param alf
- * @param annotation
- */
- public void loadAnnotationFrom(AlignFrame alf, String annotation);
-
- /**
- * parse the given string as a jalview feature or GFF annotation file and
- * optionally enable feature display on the current 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.
- */
-
- public void loadFeatures(String features, boolean autoenabledisplay);
-
- /**
- * parse the given string as a jalview feature or GFF annotation file and
- * optionally enable feature display on the given AlignFrame.
- *
- * @param alf
- * @param features
- * - gff or features file
- * @param autoenabledisplay
- * - when true, feature display will be enabled if any features can
- * be parsed from the string.
- * @return true if data parsed as features
- */
- public boolean loadFeaturesFrom(AlignFrame alf, String features,
- boolean autoenabledisplay);
-
- public boolean loadScoreFile(String sScoreFile) throws IOException;
-
- public void newFeatureSettings();
-
- public void newStructureView(PDBEntry pdb, SequenceI[] seqs,
- String[] chains, DataSourceType protocol);
-
- /// in http://www.jalview.org/examples/jalviewLiteJs.html but missing here
-
- // get selected sequences as alignment as format with or without start-end
- // suffix
-
- /**
- * re-order the given alignment using the given array of sequence IDs
- *
- * @param alf
- * @param ids
- * array of sequence IDs
- * @param undoName
- * - string to use when referring to ordering action in undo buffer
- * @return 'true' if alignment was actually reordered. empty string if
- * alignment did not contain sequences.
- */
- String orderAlignmentBy(AlignFrame alf, String[] ids, String undoName);
-
- // get a string array from a list
-
- /**
- * re-order the current alignment using the given list of sequence IDs
- *
- * @param ids
- * array of sequence IDs
- * @param undoName
- * - string to use when referring to ordering action in undo buffer
- * @return 'true' if alignment was actually reordered. empty string if
- * alignment did not contain sequences.
- */
-
- public String orderBy(String[] ids, String undoName);
-
- /**
- * re-order the current alignment using the given list of sequence IDs
- *
- * @param ids
- * array of sequence IDs
- * @param undoName
- * - string to use when referring to ordering action in undo buffer
- * @param sep
- * @return 'true' if alignment was actually reordered. empty string if
- * alignment did not contain sequences.
- */
-
- // public String orderBy(String[] ids, String undoName, String sep);
- //
-
- // public boolean getDefaultParameter(String name, boolean def);
-
- public boolean parseFeaturesFile(String param, DataSourceType protocol);
-
- /**
- * remove any callback using the given listener function and associated with
- * the given AlignFrame (or null for all callbacks);
- *
- * @param af
- * (may be null);
- * @param listener
- * (may be null);
- */
- public void removeSelectionListener(AlignFrame af, String listener);
-
- // public void setAlignPdbStructures(boolean defaultParameter);
-
- /**
- * adjust horizontal scroll to make the given column the left one in the given
- * view
- *
- * @param alf
- * @param leftHandColumn
- */
- public void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn);
-
- /**
- * adjust horizontal/vertical scroll to make the given location the top left
- * hand corner for the given view
- *
- * @param alf
- * @param topRow
- * @param leftHandColumn
- */
- public void scrollViewToIn(AlignFrame alf, String topRow,
- String leftHandColumn);
-
- /**
- * adjust vertical scroll to make the given row the top one for given view
- *
- * @param alf
- * @param topRow
- */
- public void scrollViewToRowIn(AlignFrame alf, String topRow);
-
- /**
- * select regions of the currrent alignment frame
- *
- * @param sequenceIds
- * String separated list of sequence ids or empty string
- * @param columns
- * String separated list { column range or column, ..} or empty
- * string
- */
-
- public void select(String sequenceIds, String columns);
-
- /**
- * select regions of the currrent alignment frame
- *
- * @param toselect
- * String separated list { column range, seq1...seqn sequence ids }
- * @param sep
- * separator between toselect fields
- */
-
- public void select(String sequenceIds, String columns, String sep);
-
- /**
- * select regions of the given alignment frame
- *
- * @param alf
- * @param toselect
- * String separated list { column range, seq1...seqn sequence ids }
- * @param sep
- * separator between toselect fields
- */
- public void selectIn(AlignFrame alf, String sequenceIds, String columns);
-
- /**
- * select regions of the given alignment frame
- *
- * @param alf
- * @param toselect
- * String separated list { column range, seq1...seqn sequence ids }
- * @param sep
- * separator between toselect fields
- */
- public void selectIn(AlignFrame alf, String sequenceIds, String columns,
- String sep);
-
- public void setFeatureGroupState(String groups, boolean state);
-
- public void setFeatureGroupState(String[] groups, boolean state);
-
- // public StructureSelectionManagerProvider
- // getStructureSelectionManagerProvider();
-
- /**
- * @param groups
- * tab separated list of group names
- * @param state
- * true or false
- * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
- * boolean);
- */
- public void setFeatureGroupStateOn(AlignFrame alf, String groups,
- boolean state);
-
- public void setSelectionListener(AlignFrame af, String listener);
-
- /**
- * register a javascript function to handle any alignment selection events.
- * Events are generated when the user completes a selection event, or when the
- * user deselects all selected regions.
- *
- * @param listener
- * name of javascript function (called with arguments
- * [jalview.appletgui.AlignFrame, String(sequence set id);,
- * String(separator separated list of sequences which were
- * selected);, String(separator separated list of column ranges (i.e.
- * single number or hyphenated range); that were selected);]
- */
-
- public void setSelectionListener(String listener);
-
- public void updateForAnnotations();
-
- // Bob's additions:
-
- /**
- * public static method for JalviewJS API to open a PCAPanel without
- * necessarily using a dialog.
- *
- * @param af
- * may be null
- * @param modelName
- * @return the PCAPanel, or the string "label.you_need_at_least_n_sequences"
- * if number of sequences selected is inappropriate
- */
- public Object openPcaPanel(AlignFrame af, String modelName);
-
- /**
- * Open a new Tree panel on the desktop statically. Params are standard (not
- * set by Groovy). No dialog is opened.
- *
- * @param af
- * may be null
- * @param treeType
- * @param modelName
- * @return null, or the string "label.you_need_at_least_n_sequences" if number
- * of sequences selected is inappropriate
- */
- public Object openTreePanel(AlignFrame af, String treeType,
- String modelName);
-
- /**
- * process commandline arguments after the JavaScript application has started
- *
- * @param args
- * @return
- */
- public Object parseArguments(String[] args);
-
- public void showStructure(AlignFrame af, String pdbID, String fileType);
-
- public void showOverview();
-
-}