From: BobHanson Date: Mon, 1 Jun 2020 21:20:28 +0000 (-0500) Subject: JAL-3262 from JAL-3523-applet JalviewApp and JalviewJSApi X-Git-Url: http://source.jalview.org/gitweb/?a=commitdiff_plain;h=7eea865f7a04c9dde807f907155f0e6e4c86f7b9;p=jalview.git JAL-3262 from JAL-3523-applet JalviewApp and JalviewJSApi - removes JaliewJSLite dependence - removes AlignFrameI reference --- diff --git a/src/jalview/api/JalviewApp.java b/src/jalview/api/JalviewApp.java new file mode 100644 index 0000000..0548c85 --- /dev/null +++ b/src/jalview/api/JalviewApp.java @@ -0,0 +1,82 @@ +package jalview.api; + +import jalview.datamodel.ColumnSelection; +import jalview.datamodel.HiddenColumns; +import jalview.datamodel.PDBEntry; +import jalview.datamodel.SequenceGroup; +import jalview.datamodel.SequenceI; +import jalview.io.DataSourceType; +import jalview.io.NewickFile; +import jalview.javascript.JSFunctionExec; +import jalview.javascript.MouseOverStructureListener; +import jalview.structure.SelectionSource; +import jalview.structure.VamsasSource; + +import java.applet.AppletContext; +import java.io.IOException; +import java.net.URL; +import java.util.Hashtable; +import java.util.Vector; + +import netscape.javascript.JSObject; + +public interface JalviewApp +{ + public String getParameter(String name); + + public boolean getDefaultParameter(String name, boolean def); + + public URL getDocumentBase(); + + public URL getCodeBase(); + + public void setAlignPdbStructures(boolean defaultParameter); + + public void newStructureView(PDBEntry pdb, SequenceI[] seqs, + String[] chains, DataSourceType protocol); + + public void alignedStructureView(PDBEntry[] pdb, SequenceI[][] seqs, + String[][] chains, String[] protocols); + + public void updateForAnnotations(); + + public AlignViewportI getViewport(); + + public void setFeatureGroupState(String[] groups, boolean state); + + public boolean parseFeaturesFile(String param, DataSourceType protocol); + + public void newFeatureSettings(); + + public boolean loadScoreFile(String sScoreFile) throws IOException; + + public void loadTree(NewickFile fin, String treeFile) throws IOException; + + public Vector getJsExecQueue(JSFunctionExec jsFunctionExec); + + public AppletContext getAppletContext(); + + public boolean isJsfallbackEnabled(); + + public JSObject getJSObject(); + + public StructureSelectionManagerProvider getStructureSelectionManagerProvider(); + + public void updateColoursFromMouseOver(Object source, + MouseOverStructureListener mouseOverStructureListener); + + public Object[] getSelectionForListener(SequenceGroup seqsel, ColumnSelection colsel, + HiddenColumns hidden, SelectionSource source, Object alignFrame); + + public String arrayToSeparatorList(String[] array); + + public Hashtable getJSHashes(); + + Hashtable> getJSMessages(); + + public Object getFrameForSource(VamsasSource source); + + public jalview.renderer.seqfeatures.FeatureRenderer getNewFeatureRenderer( + AlignViewportI vp); + +} diff --git a/src/jalview/bin/JalviewJSApi.java b/src/jalview/bin/JalviewJSApi.java new file mode 100644 index 0000000..a21bebe --- /dev/null +++ b/src/jalview/bin/JalviewJSApi.java @@ -0,0 +1,693 @@ +package jalview.bin; + +import jalview.gui.AlignFrame; + +/** + * JAL-3369 JalviewJS API BH 2019.07.17 + * + * @author hansonr + * + */ +public interface JalviewJSApi +{ + + void showOverview(); + + /** + * process commandline arguments after the JavaScript application has started + * + * @param args + * @return + */ + Object parseArguments(String[] args); + + + /** + * 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); + + /** + * 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); + + /** + * The following public methods may be called externally, eg via javascript in + * an HTML page. + * + *
+ * TODO: introduce abstract 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 + // { + + /** + * @return String list of selected sequence IDs, each terminated by the + * 'boolean not' character (""+0x00AC); or (¬); + */ + + public abstract String getSelectedSequences(); + + /** + * @param sep + * separator string or null for default + * @return String list of selected sequence IDs, each terminated by given + * separator string + */ + + public abstract String getSelectedSequences(String sep); + + /** + * @param alf + * AlignFrame containing selection + * @return String list of selected sequence IDs, each terminated by current + * default separator sequence + * + */ + public abstract String getSelectedSequencesFrom(AlignFrame alf); + + /** + * 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 abstract String getSelectedSequencesFrom(AlignFrame alf, + String sep); + + /** + * + * @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 abstract 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 abstract void highlightIn(AlignFrame alf, String sequenceId, + String position, String alignedPosition); + + /** + * 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 abstract 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 abstract 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 abstract 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 abstract void selectIn(AlignFrame alf, String sequenceIds, + String columns, 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 abstract 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 abstract String getSelectedSequencesAsAlignmentFrom( + AlignFrame alf, + String format, String suffix); + + /** + * get a separator separated list of sequence IDs reflecting the order of the + * current alignment + * + * @return + */ + + public abstract String getAlignmentOrder(); + + /** + * get a separator separated list of sequence IDs reflecting the order of the + * alignment in alf + * + * @param alf + * @return + */ + public abstract String getAlignmentOrderFrom(AlignFrame alf); + + /** + * get a sep separated list of sequence IDs reflecting the order of the + * alignment in alf + * + * @param alf + * @param sep + * - separator to use + * @return + */ + public abstract String getAlignmentOrderFrom(AlignFrame alf, + String sep); + + /** + * re-order the current alignment using the given list of sequence IDs + * + * @param order + * - sep separated list + * @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 abstract String orderBy(String order, String undoName); + + /** + * re-order the current alignment using the given list of sequence IDs + * separated by sep + * + * @param order + * - sep separated list + * @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 abstract String orderBy(String order, String undoName, + String sep); + + /** + * re-order the given alignment using the given list of sequence IDs separated + * by sep + * + * @param alf + * @param order + * - sep separated list + * @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 abstract String orderAlignmentBy(AlignFrame alf, String order, + String undoName, String sep); + + /** + * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP, + * PFAM - see jalview.io.AppletFormatAdapter for full list); + * + * @param format + * @return + */ + + public abstract String getAlignment(String format); + + /** + * get alignment displayed in alf as format + * + * @param alf + * @param format + * @return + */ + public abstract String getAlignmentFrom(AlignFrame alf, String format); + + /** + * get alignment as format with jalview start-end sequence suffix appended + * + * @param format + * @param suffix + * @return + */ + + public abstract String getAlignment(String format, String suffix); + + /** + * 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 abstract String getAlignmentFrom(AlignFrame alf, String format, + String suffix); + + /** + * add the given features or annotation to the current alignment + * + * @param annotation + */ + + public abstract void loadAnnotation(String annotation); + + /** + * add the given features or annotation to the given alignment view + * + * @param alf + * @param annotation + */ + public abstract 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 abstract 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 abstract boolean loadFeaturesFrom(AlignFrame alf, String features, + boolean autoenabledisplay); + + /** + * get the sequence features in the given format (Jalview or GFF); + * + * @param format + * @return + */ + + public abstract String getFeatures(String format); + + /** + * get the sequence features in alf in the given format (Jalview or GFF); + * + * @param alf + * @param format + * @return + */ + public abstract String getFeaturesFrom(AlignFrame alf, String format); + + /** + * get current alignment's annotation as an annotation file + * + * @return + */ + + public abstract String getAnnotation(); + + /** + * get alignment view alf's annotation as an annotation file + * + * @param alf + * @return + */ + public abstract String getAnnotationFrom(AlignFrame alf); + + // BH incompatibility here -- JalviewLite created an AlignFrame; Jalview + // creates an AlignmentPanel + // /** + // * create a new view and return the AlignFrame instance + // * + // * @return + // */ + // + // public abstract AlignFrame newView(); + // + // /** + // * create a new view named name and return the AlignFrame instance + // * + // * @param name + // * @return + // */ + // + // public abstract AlignFrame newView(String name); + // + // /** + // * create a new view on alf and return the AlignFrame instance + // * + // * @param alf + // * @return + // */ + // public abstract AlignFrame newViewFrom(AlignFrame alf); + // + // /** + // * create a new view named name on alf + // * + // * @param alf + // * @param name + // * @return + // */ + // public abstract AlignFrame newViewFrom(AlignFrame alf, String name); + + /** + * + * @param text + * alignment file as a string + * @param title + * window title + * @return null or new alignment frame + */ + + public abstract AlignFrame loadAlignment(String text, String title); + + /** + * register a javascript function to handle any alignment mouseover events + * + * @param listener + * name of javascript function (called with arguments + * [jalview.appletgui.AlignFrame,String(sequence id);,String(column + * in alignment);, String(position in sequence);] + */ + + public abstract void setMouseoverListener(String listener); + + /** + * register a javascript function to handle mouseover events + * + * @param af + * (null or specific AlignFrame for which events are to be listened + * for); + * @param listener + * name of javascript function + */ + public abstract void setMouseoverListener(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 abstract void setSelectionListener(String listener); + + public abstract void setSelectionListener(AlignFrame af, + String listener); + + /** + * register a javascript function to handle events normally routed to a Jmol + * structure viewer. + * + * @param listener + * - javascript function (arguments are variable, see + * jalview.javascript.MouseOverStructureListener for full details); + * @param modelSet + * - separator separated list of PDB file URIs that this viewer is + * handling. These files must be in the same order they appear in + * Jmol (e.g. first one is frame 1, second is frame 2, etc);. + * @see jalview.javascript.MouseOverStructureListener + */ + + public abstract void setStructureListener(String listener, + String modelSet); + + /** + * 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 abstract void removeJavascriptListener(AlignFrame af, + String listener); + + /** + * send a mouseover message to all the alignment windows associated with the + * given residue in the pdbfile + * + * @param pdbResNum + * @param chain + * @param pdbfile + */ + + public abstract void mouseOverStructure(String pdbResNum, String chain, + String pdbfile); + + /** + * 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. + * @param pdbEntryString + * - the short name for the PDB file + * @param pdbFile + * - pdb file - either a URL or a valid PDB file. + * @return true if binding was as success TODO: consider making an exception + * structure for indicating when PDB parsing or sequenceId location + * fails. + */ + public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId, + String pdbEntryString, String pdbFile); + + /** + * 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 abstract 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 abstract void scrollViewToRowIn(AlignFrame alf, String topRow); + + /** + * adjust horizontal scroll to make the given column the left one in the given + * view + * + * @param alf + * @param leftHandColumn + */ + public abstract void scrollViewToColumnIn(AlignFrame alf, + String leftHandColumn); + + /** + * + * @return + * @see jalview.appletgui.AlignFrame#getFeatureGroups(); + */ + + public abstract String getFeatureGroups(); + + /** + * @param alf + * AlignFrame to get feature groups on + * @return + * @see jalview.appletgui.AlignFrame#getFeatureGroups(); + */ + public abstract String getFeatureGroupsOn(AlignFrame alf); + + /** + * @param visible + * @return + * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean); + */ + + public abstract String getFeatureGroupsOfState(boolean visible); + + /** + * @param alf + * align frame to get groups of state visible + * @param visible + * @return + * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean); + */ + public abstract String getFeatureGroupsOfStateOn(AlignFrame alf, + boolean visible); + + /** + * @param groups + * tab separated list of group names + * @param state + * true or false + * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[], + * boolean); + */ + public abstract void setFeatureGroupStateOn(AlignFrame alf, + String groups, + boolean state); + + + public abstract void setFeatureGroupState(String groups, boolean state); + + /** + * List separator string + * + * @return the separator + */ + + public abstract String getSeparator(); + + /** + * List separator string + * + * @param separator + * the separator to set. empty string will reset separator to default + */ + + public abstract void setSeparator(String separator); + + /** + * Retrieve fragments of a large packet of data made available by JalviewLite. + * + * @param messageclass + * @param viewId + * @return next chunk of message + */ + + public abstract String getJsMessage(String messageclass, String viewId); + + /// in http://www.jalview.org/examples/jalviewLiteJs.html but missing here + + // get selected sequences as alignment as format with or without start-end + // suffix + + public String getSelectedSequencesAsAlignment(String format, + boolean suffix); + + // get selected sequences as alignment from given view as format with or + // without start-end suffix + public String getSelectedSequencesAsAlignmentFrom(AlignFrame alf, + String format, boolean suffix); + + + public String arrayToSeparatorList(String[] array); + + // get a string array from a list + + public String[] separatorListToArray(String list); + + // debug flag - controls output to standard out + public static boolean debug = false; + +}