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.
*
*
* TODO: introduce interface for jalview.appletgui.AlignFrame
*
* 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();
}